From 7722301ab42ee18d520cbabfe743be384ebfa046 Mon Sep 17 00:00:00 2001
From: Balint Ujvari <balint.ujvari@solarpunk.buzz>
Date: Thu, 7 May 2026 14:09:06 +0200
Subject: [PATCH 1/2] feat: display member cursors

refactor: logging
chore: removed unnecessary transprots
---
 README.md                                     |   2 +-
 src/app/components/DocEditor/DocEditor.scss   |  30 ++
 src/app/components/DocEditor/DocEditor.tsx    | 154 ++++++++++-
 src/app/components/LoginView/LoginView.tsx    |  20 +-
 .../components/SessionView/SessionView.tsx    |  31 ++-
 src/app/hooks/useSwarmDoc.tsx                 |  19 +-
 src/app/main.tsx                              |   6 +-
 src/app/pages/TestPage.tsx                    |  20 +-
 src/app/utils/peerColor.ts                    |   7 +
 src/app/utils/types.ts                        |   4 -
 src/lib/doc/doc.ts                            | 113 ++++++--
 src/lib/doc/events.ts                         |   8 +
 src/lib/doc/members.ts                        |  10 +-
 src/lib/index.ts                              |   7 +-
 src/lib/interfaces/notification.ts            |  54 +++-
 src/lib/notification/broadcastChannel.ts      |  69 -----
 src/lib/notification/swarmFeed.ts             | 261 ------------------
 src/lib/notification/swarmPubSubTransport.ts  |   6 +-
 src/lib/notification/swarmRtcTransport.ts     | 104 ++++---
 src/lib/notification/swarmSignal.ts           |  17 +-
 src/lib/notification/wakuTransport.ts         |  18 +-
 src/lib/notification/yWebrtcTransport.ts      |   6 +-
 src/lib/utils/constants.ts                    |   2 -
 23 files changed, 468 insertions(+), 500 deletions(-)
 create mode 100644 src/app/utils/peerColor.ts
 delete mode 100644 src/lib/notification/broadcastChannel.ts
 delete mode 100644 src/lib/notification/swarmFeed.ts

diff --git a/README.md b/README.md
index 14e4f4a..a420e57 100644
--- a/README.md
+++ b/README.md
@@ -306,7 +306,7 @@ Enter a username, then configure:
   - _WebRTC_ — y-webrtc via a signaling server or Swarm-based SDP signaling (see Advanced Settings)
 - **Advanced Settings** (collapsible):
   - Bee API URL
-  - `MUTABLE_STAMP` postage batch ID
+  - Postage batch ID
   - Disable editing until a peer is connected (WebRTC / Waku only)
   - Broker Peer multiaddress (Swarm PubSub only)
   - Signaling Server URL or Swarm Signaling STUN URL (WebRTC only)
diff --git a/src/app/components/DocEditor/DocEditor.scss b/src/app/components/DocEditor/DocEditor.scss
index 472c2b4..287dd59 100644
--- a/src/app/components/DocEditor/DocEditor.scss
+++ b/src/app/components/DocEditor/DocEditor.scss
@@ -10,6 +10,7 @@ $swarm-text: #f8f8ff;
   flex-direction: column;
   height: 100%;
   background: $swarm-dark;
+  position: relative;
 
   &--loading {
     padding: 24px;
@@ -68,6 +69,35 @@ $swarm-text: #f8f8ff;
       background: rgba(247, 104, 8, 0.25);
     }
   }
+  &__cursor-overlay {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    pointer-events: none;
+    overflow: hidden;
+  }
+
+  &__cursor-line {
+    position: absolute;
+    width: 2px;
+    border-radius: 1px;
+    opacity: 0.85;
+  }
+
+  &__cursor-badge {
+    position: absolute;
+    font-family: 'Inter', system-ui, sans-serif;
+    font-size: 10px;
+    font-weight: 600;
+    color: #fff;
+    padding: 1px 5px;
+    border-radius: 3px;
+    white-space: nowrap;
+    opacity: 0.92;
+    line-height: 16px;
+  }
 }
 
 @keyframes doc-editor-pulse {
diff --git a/src/app/components/DocEditor/DocEditor.tsx b/src/app/components/DocEditor/DocEditor.tsx
index 0b8e255..ce46738 100644
--- a/src/app/components/DocEditor/DocEditor.tsx
+++ b/src/app/components/DocEditor/DocEditor.tsx
@@ -1,11 +1,63 @@
-import React, { useEffect, useRef, useState } from 'react'
+import React, { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import * as Y from 'yjs'
 
+import { AwarenessState } from '../../hooks/useSwarmDoc'
+import { colorForAddress } from '../../utils/peerColor'
+
 import './DocEditor.scss'
 
-interface DocEditorProps {
-  doc: Y.Doc | null
-  disabled?: boolean
+// Mirror-div technique: measure pixel coordinates of a character offset in a textarea.
+// Returns coordinates relative to the textarea's top-left padding origin.
+function getCaretXY(el: HTMLTextAreaElement, position: number): { top: number; left: number } {
+  const style = window.getComputedStyle(el)
+  const div = document.createElement('div')
+
+  const props = [
+    'boxSizing',
+    'width',
+    'paddingTop',
+    'paddingRight',
+    'paddingBottom',
+    'paddingLeft',
+    'borderTopWidth',
+    'borderRightWidth',
+    'borderBottomWidth',
+    'borderLeftWidth',
+    'fontFamily',
+    'fontSize',
+    'fontWeight',
+    'fontStyle',
+    'fontVariant',
+    'lineHeight',
+    'letterSpacing',
+    'wordSpacing',
+    'textTransform',
+    'textIndent',
+    'whiteSpace',
+    'wordBreak',
+    'wordWrap',
+    'tabSize',
+  ] as const
+
+  div.style.position = 'absolute'
+  div.style.visibility = 'hidden'
+  div.style.top = '-9999px'
+  div.style.left = '-9999px'
+  div.style.overflow = 'hidden'
+  props.forEach(p => {
+    div.style[p as never] = style[p as never]
+  })
+
+  const text = el.value.slice(0, position)
+  div.textContent = text || ' '
+  const span = document.createElement('span')
+  span.textContent = el.value[position] ?? ' '
+  div.appendChild(span)
+  document.body.appendChild(div)
+  const coords = { top: span.offsetTop, left: span.offsetLeft }
+  document.body.removeChild(div)
+
+  return coords
 }
 
 function commonPrefixLen(a: string, b: string): number {
@@ -23,8 +75,6 @@ function commonSuffixLen(a: string, b: string, prefixLen: number): number {
   return i
 }
 
-// Apply only the diff between oldValue and newValue to Y.Text.
-// This preserves other users' items that are outside the changed range.
 function applyDiff(yText: Y.Text, doc: Y.Doc, oldValue: string, newValue: string): void {
   const prefix = commonPrefixLen(oldValue, newValue)
   const suffix = commonSuffixLen(oldValue, newValue, prefix)
@@ -32,7 +82,6 @@ function applyDiff(yText: Y.Text, doc: Y.Doc, oldValue: string, newValue: string
   const insertText = newValue.slice(prefix, newValue.length - suffix)
 
   if (deleteCount === 0 && insertText.length === 0) return
-
   doc.transact(() => {
     if (deleteCount > 0) yText.delete(prefix, deleteCount)
 
@@ -40,41 +89,93 @@ function applyDiff(yText: Y.Text, doc: Y.Doc, oldValue: string, newValue: string
   })
 }
 
-export const DocEditor: React.FC<DocEditorProps> = ({ doc, disabled = false }) => {
+interface DocEditorProps {
+  doc: Y.Doc | null
+  disabled?: boolean
+  awareness?: Map<string, AwarenessState>
+  onCursorChange?: (cursor: { anchor: number; head: number } | null) => void
+}
+
+interface CursorBadge {
+  address: string
+  username: string
+  color: string
+  top: number
+  left: number
+  lineHeight: number
+}
+
+export const DocEditor: React.FC<DocEditorProps> = ({ doc, disabled = false, awareness, onCursorChange }) => {
   const yTextRef = useRef<Y.Text | null>(null)
   const prevContentRef = useRef('')
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
   const [content, setContent] = useState('')
+  const [scrollTop, setScrollTop] = useState(0)
+  const [badges, setBadges] = useState<CursorBadge[]>([])
 
   useEffect(() => {
     if (!doc) return
-
     const yText = doc.getText('content')
     yTextRef.current = yText
-
     const initial = yText.toString()
     prevContentRef.current = initial
     setContent(initial)
-
     const observer = () => {
       const text = yText.toString()
       prevContentRef.current = text
       setContent(text)
     }
-
     yText.observe(observer)
 
     return () => yText.unobserve(observer)
   }, [doc])
 
+  // Recompute badge positions whenever awareness or content changes
+  useLayoutEffect(() => {
+    const el = textareaRef.current
+
+    if (!el || !awareness || awareness.size === 0) {
+      setBadges([])
+
+      return
+    }
+
+    const style = window.getComputedStyle(el)
+    const lineHeight = parseFloat(style.lineHeight)
+    const next: CursorBadge[] = []
+
+    for (const [address, state] of awareness) {
+      if (state.cursor) {
+        const pos = Math.max(0, Math.min(state.cursor.anchor, el.value.length))
+        const { top, left } = getCaretXY(el, pos)
+        next.push({
+          address,
+          username: state.username,
+          color: colorForAddress(address),
+          top: top - scrollTop,
+          left,
+          lineHeight,
+        })
+      }
+    }
+
+    setBadges(next)
+  }, [awareness, content, scrollTop])
+
+  const reportCursor = () => {
+    const el = textareaRef.current
+
+    if (!el || !onCursorChange) return
+    onCursorChange({ anchor: el.selectionStart, head: el.selectionEnd })
+  }
+
   const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
     if (!yTextRef.current || !doc) return
-
     const newValue = e.target.value
     const oldValue = prevContentRef.current
-    // Update prevContent immediately so rapid keystrokes diff against the right base
     prevContentRef.current = newValue
-
     applyDiff(yTextRef.current, doc, oldValue, newValue)
+    reportCursor()
   }
 
   if (!doc) {
@@ -84,13 +185,36 @@ export const DocEditor: React.FC<DocEditorProps> = ({ doc, disabled = false }) =
   return (
     <div className="doc-editor">
       <textarea
+        ref={textareaRef}
         className="doc-editor__textarea"
         value={content}
         onChange={handleChange}
+        onSelect={reportCursor}
+        onKeyUp={reportCursor}
+        onClick={reportCursor}
+        onScroll={e => setScrollTop((e.target as HTMLTextAreaElement).scrollTop)}
         disabled={disabled}
         placeholder="Start typing — changes sync across peers via Swarm…"
         spellCheck={false}
       />
+      {badges.length > 0 && (
+        <div className="doc-editor__cursor-overlay" aria-hidden="true">
+          {badges.map(b => (
+            <React.Fragment key={b.address}>
+              <div
+                className="doc-editor__cursor-line"
+                style={{ top: b.top, left: b.left, height: b.lineHeight, background: b.color }}
+              />
+              <div
+                className="doc-editor__cursor-badge"
+                style={{ top: Math.max(0, b.top - 20), left: b.left, background: b.color }}
+              >
+                {b.username || b.address.slice(0, 6)}
+              </div>
+            </React.Fragment>
+          ))}
+        </div>
+      )}
     </div>
   )
 }
diff --git a/src/app/components/LoginView/LoginView.tsx b/src/app/components/LoginView/LoginView.tsx
index 9b70eda..47be8ca 100644
--- a/src/app/components/LoginView/LoginView.tsx
+++ b/src/app/components/LoginView/LoginView.tsx
@@ -290,7 +290,7 @@ export const LoginView: React.FC<LoginViewProps> = ({
               </div>
 
               <div className="login-view__field">
-                <label className="login-view__field-label">MUTABLE_STAMP</label>
+                <label className="login-view__field-label">Postage stamp</label>
                 <input
                   value={mutableStamp}
                   onChange={e => onMutableStampChange(e.target.value)}
@@ -306,16 +306,14 @@ export const LoginView: React.FC<LoginViewProps> = ({
                 )}
               </div>
 
-              {transport !== Transport.SWARM_FEED_POLL && (
-                <label className="login-view__checkbox-label">
-                  <input
-                    type="checkbox"
-                    checked={disableUntilConnected}
-                    onChange={e => onDisableUntilConnectedChange(e.target.checked)}
-                  />
-                  Disable editing until peer connected
-                </label>
-              )}
+              <label className="login-view__checkbox-label">
+                <input
+                  type="checkbox"
+                  checked={disableUntilConnected}
+                  onChange={e => onDisableUntilConnectedChange(e.target.checked)}
+                />
+                Disable editing until peer connected
+              </label>
 
               {transport === Transport.SWARM_PUBSUB && (
                 <div className="login-view__field">
diff --git a/src/app/components/SessionView/SessionView.tsx b/src/app/components/SessionView/SessionView.tsx
index 8b07421..4587ab2 100644
--- a/src/app/components/SessionView/SessionView.tsx
+++ b/src/app/components/SessionView/SessionView.tsx
@@ -1,7 +1,5 @@
 import { PrivateKey } from '@ethersphere/bee-js'
 import {
-  createBroadcastChannelTransport,
-  createSwarmFeedTransport,
   createSwarmPubSubTransport,
   createSwarmRtcTransport,
   createWakuTransport,
@@ -21,6 +19,7 @@ import {
   MUTABLE_STAMP_KEY,
   TOPIC_KEY,
 } from '../../utils/constants'
+import { colorForAddress } from '../../utils/peerColor'
 import { Session, Transport, TRANSPORT_LABELS } from '../../utils/types'
 import { DocEditor } from '../DocEditor/DocEditor'
 
@@ -71,14 +70,6 @@ export const SessionView: React.FC<SessionViewProps> = ({
 
   const docConfig: DocSettings = useMemo(() => {
     const getTransport = () => {
-      if (session.transport === Transport.BROADCAST_CHANNEL) {
-        return createBroadcastChannelTransport()
-      }
-
-      if (session.transport === Transport.SWARM_FEED_POLL) {
-        return createSwarmFeedTransport(beeUrl, signer.toHex(), mutableStamp, topic)
-      }
-
       if (session.transport === Transport.WAKU) {
         let wakuAddress: string[] | undefined = undefined
 
@@ -131,7 +122,8 @@ export const SessionView: React.FC<SessionViewProps> = ({
     mutableStamp,
   ])
 
-  const { doc, error, members, connected, refreshMemberList, dismissError } = useSwarmDoc(docConfig)
+  const { doc, error, members, connected, awareness, updateCursor, refreshMemberList, dismissError } =
+    useSwarmDoc(docConfig)
 
   const transportLabel = TRANSPORT_LABELS[session.transport]
 
@@ -146,7 +138,12 @@ export const SessionView: React.FC<SessionViewProps> = ({
             </button>
           </div>
         ) : null}
-        <DocEditor doc={doc} disabled={disableUntilConnected && !connected} />
+        <DocEditor
+          doc={doc}
+          disabled={disableUntilConnected && !connected}
+          awareness={awareness}
+          onCursorChange={updateCursor}
+        />
       </div>
     )
   }
@@ -159,7 +156,11 @@ export const SessionView: React.FC<SessionViewProps> = ({
     for (const [addr, username] of members) {
       block.push(
         <span key={addr} className="session-view__member-chip">
-          <span className="session-view__member-dot" aria-hidden="true" />
+          <span
+            className="session-view__member-dot"
+            aria-hidden="true"
+            style={{ background: colorForAddress(addr), boxShadow: `0 0 0 2px ${colorForAddress(addr)}33` }}
+          />
           <code className="session-view__member-code" title={addr}>
             {username.length ? username : addr.slice(0, 8) + '…'}
           </code>
@@ -244,7 +245,7 @@ export const SessionView: React.FC<SessionViewProps> = ({
                   onReset: () => setUrlDraft(DEFAULT_BEE_API_URL),
                 },
                 {
-                  label: 'MUTABLE_STAMP',
+                  label: 'Postage stamp',
                   value: mutableStampDraft,
                   onChange: setMutableStampDraft,
                   placeholder: PLACEHOLDER_STAMP,
@@ -252,7 +253,7 @@ export const SessionView: React.FC<SessionViewProps> = ({
                   onReset: () => setMutableStampDraft(PLACEHOLDER_STAMP),
                 },
                 {
-                  label: 'TOPIC',
+                  label: 'Topic',
                   value: topicDraft,
                   onChange: setTopicDraft,
                   placeholder: DEFAULT_TOPIC,
diff --git a/src/app/hooks/useSwarmDoc.tsx b/src/app/hooks/useSwarmDoc.tsx
index 7921a10..2079f5a 100644
--- a/src/app/hooks/useSwarmDoc.tsx
+++ b/src/app/hooks/useSwarmDoc.tsx
@@ -2,11 +2,19 @@ import { DOC_EVENTS, DocSettings, SwarmDoc } from 'lib'
 import { useEffect, useRef, useState } from 'react'
 import * as Y from 'yjs'
 
+export interface AwarenessState {
+  address: string
+  username: string
+  cursor: { anchor: number; head: number } | null
+}
+
 export interface SwarmDocContext {
   doc: Y.Doc | null
   error: Error | null
   members: Map<string, string> | null
   connected: boolean
+  awareness: Map<string, AwarenessState>
+  updateCursor: (cursor: { anchor: number; head: number } | null) => void
   refreshMemberList: () => void
   dismissError: () => void
 }
@@ -23,6 +31,7 @@ export const useSwarmDoc = ({ user, infra }: DocSettings): SwarmDocContext => {
     members: null,
     connected: false,
   })
+  const [awareness, setAwareness] = useState<Map<string, AwarenessState>>(new Map())
 
   const dismissError = () => {
     setStatus(prev => (error ? { ...prev, error: null } : prev))
@@ -42,6 +51,9 @@ export const useSwarmDoc = ({ user, infra }: DocSettings): SwarmDocContext => {
       .getEmitter()
       .on(DOC_EVENTS.MEMBERS_UPDATED, (m: Map<string, string>) => setStatus(s => ({ ...s, members: m })))
     swarmDoc.getEmitter().on(DOC_EVENTS.PEERS_CONNECTED, () => setStatus(s => ({ ...s, connected: true })))
+    swarmDoc.getEmitter().on(DOC_EVENTS.AWARENESS_UPDATED, (update: AwarenessState) => {
+      setAwareness(prev => new Map(prev).set(update.address, update))
+    })
 
     swarmDoc.start()
     setDoc(swarmDoc.doc)
@@ -51,6 +63,7 @@ export const useSwarmDoc = ({ user, infra }: DocSettings): SwarmDocContext => {
       docRef.current = null
       setDoc(null)
       setStatus({ error: null, members: null, connected: false })
+      setAwareness(new Map())
     }
   }, [user, infra])
 
@@ -58,5 +71,9 @@ export const useSwarmDoc = ({ user, infra }: DocSettings): SwarmDocContext => {
     await docRef.current?.refreshMemberList()
   }
 
-  return { doc, error, members, connected, refreshMemberList, dismissError }
+  const updateCursor = (cursor: { anchor: number; head: number } | null) => {
+    docRef.current?.updateCursor(cursor)
+  }
+
+  return { doc, error, members, connected, awareness, updateCursor, refreshMemberList, dismissError }
 }
diff --git a/src/app/main.tsx b/src/app/main.tsx
index cde8140..8365939 100644
--- a/src/app/main.tsx
+++ b/src/app/main.tsx
@@ -6,7 +6,7 @@ import TestPage from './pages/TestPage'
 // TODO: react strict mode closes the WS connection
 const root = createRoot(document.getElementById('root') as HTMLElement)
 root.render(
-  <React.StrictMode>
-    <TestPage />
-  </React.StrictMode>,
+  // <React.StrictMode>
+  <TestPage />,
+  // </React.StrictMode>,
 )
diff --git a/src/app/pages/TestPage.tsx b/src/app/pages/TestPage.tsx
index a06b563..76355ac 100644
--- a/src/app/pages/TestPage.tsx
+++ b/src/app/pages/TestPage.tsx
@@ -1,11 +1,10 @@
-import React, { useCallback, useState } from 'react'
+import React, { useState } from 'react'
 
 import { LoginView } from '../components/LoginView/LoginView'
 import { SessionView } from '../components/SessionView/SessionView'
 import { useSession } from '../hooks/useSession'
 import { DISABLE_UNTIL_CONNECTED_KEY, TOPIC_KEY, TRANSPORT_KEY } from '../utils/constants'
 import { loadBeeUrl, loadDisableUntilConnected, loadMutableStamp, loadTopic, loadUsername } from '../utils/localStorage'
-import { Transport } from '../utils/types'
 
 const TestPage: React.FC = () => {
   const { session, login, logout } = useSession()
@@ -26,19 +25,12 @@ const TestPage: React.FC = () => {
   const [mutableStamp, setMutableStamp] = useState(loadMutableStamp())
   const [username, setUsername] = useState(loadUsername())
   const [isLoggedIn, setIsLoggedIn] = useState(false)
-  const [disableUntilConnected, setDisableUntilConnected] = useState(
-    session?.transport !== Transport.SWARM_FEED_POLL ? loadDisableUntilConnected() : false,
-  )
+  const [disableUntilConnected, setDisableUntilConnected] = useState(loadDisableUntilConnected())
 
-  const handleDisableUntilConnectedChange = useCallback(
-    (v: boolean) => {
-      if (session?.transport !== Transport.SWARM_FEED_POLL) {
-        setDisableUntilConnected(v)
-        localStorage.setItem(DISABLE_UNTIL_CONNECTED_KEY, String(v))
-      }
-    },
-    [session],
-  )
+  const handleDisableUntilConnectedChange = (v: boolean) => {
+    setDisableUntilConnected(v)
+    localStorage.setItem(DISABLE_UNTIL_CONNECTED_KEY, String(v))
+  }
 
   if (!isLoggedIn || !session) {
     return (
diff --git a/src/app/utils/peerColor.ts b/src/app/utils/peerColor.ts
new file mode 100644
index 0000000..139335b
--- /dev/null
+++ b/src/app/utils/peerColor.ts
@@ -0,0 +1,7 @@
+const CURSOR_COLORS = ['#e63946', '#2a9d8f', '#e9c46a', '#f4a261', '#a8dadc', '#457b9d', '#c77dff', '#06d6a0']
+
+export function colorForAddress(address: string): string {
+  const index = parseInt(address.slice(0, 8), 16) % CURSOR_COLORS.length
+
+  return CURSOR_COLORS[index]
+}
diff --git a/src/app/utils/types.ts b/src/app/utils/types.ts
index 43cf1c1..c5348fb 100644
--- a/src/app/utils/types.ts
+++ b/src/app/utils/types.ts
@@ -1,6 +1,4 @@
 export enum Transport {
-  SWARM_FEED_POLL = 'swarm-feed-poll',
-  BROADCAST_CHANNEL = 'broadcast',
   WEBRTC = 'webrtc',
   WAKU = 'waku',
   SWARM_PUBSUB = 'swarm-pubsub',
@@ -19,8 +17,6 @@ export interface Session {
 }
 
 export const TRANSPORT_LABELS: Record<Transport, string> = {
-  [Transport.SWARM_FEED_POLL]: 'Swarm Feed',
-  [Transport.BROADCAST_CHANNEL]: 'BroadcastChannel',
   [Transport.WEBRTC]: 'WebRTC',
   [Transport.WAKU]: 'Waku',
   [Transport.SWARM_PUBSUB]: 'Swarm Pubsub',
diff --git a/src/lib/doc/doc.ts b/src/lib/doc/doc.ts
index b843168..b72c1c6 100644
--- a/src/lib/doc/doc.ts
+++ b/src/lib/doc/doc.ts
@@ -1,4 +1,4 @@
-import { FeedIndex, PrivateKey, Topic } from '@ethersphere/bee-js'
+import { FeedIndex, PrivateKey, Signature, Topic } from '@ethersphere/bee-js'
 import {
   MessageData,
   MessageType,
@@ -11,7 +11,7 @@ import * as Y from 'yjs'
 import { DocSettings, DocTransport, NotificationHandler, NotificationPayload } from '../interfaces'
 import { validateStamps } from '../utils/bee'
 import { decode, encode, indexStrToBigint, remove0x, retryAwaitableAsync, uuidV4 } from '../utils/common'
-import { API_VERSION, DOC_FEED_SUFFIX, JOIN_FEED_INDEX, PLACEHOLDER_STAMP } from '../utils/constants'
+import { API_VERSION, DOC_FEED_SUFFIX, PLACEHOLDER_STAMP } from '../utils/constants'
 import { ErrorHandler } from '../utils/error'
 import { EventEmitter } from '../utils/eventEmitter'
 
@@ -61,6 +61,8 @@ export class SwarmDoc {
   private publishInFlight = false
   private fetchProcessRunning = false
   private memberListPollTimer: ReturnType<typeof setInterval> | null = null
+  private localCursor: { anchor: number; head: number } | null = null
+  private cursorTimer: ReturnType<typeof setInterval> | null = null
 
   constructor(settings: DocSettings) {
     this.doc = new Y.Doc()
@@ -82,12 +84,6 @@ export class SwarmDoc {
       : []
     const members = configuredMembers.filter(([addr]) => addr !== this.ownAddress)
 
-    console.log(`${TAG} ownAddress: ${this.ownAddress}`)
-    console.log(`${TAG} feedNamespace: ${this.docFeedId}`)
-    console.log(`${TAG} topic identifier: ${Topic.fromString(this.docFeedId + this.ownAddress).toString()}`)
-    console.log(`${TAG} members configured: ${members.length === 0 ? '(none)' : members.map(m => m).join(', ')}`)
-    console.log(`${TAG} mutable stamp: ${this.mutableStampId}`)
-
     this.transport = settings.infra.transport({
       doc: this.doc,
       emitter: this.emitter,
@@ -138,7 +134,7 @@ export class SwarmDoc {
     }
 
     this.transport.connectToPeer(address)
-    console.log(`${TAG} registerMember: ${address.slice(0, 8)}…`)
+    console.debug(`${TAG} registerMember: ${address.slice(0, 8)}…`)
   }
 
   /**
@@ -149,12 +145,17 @@ export class SwarmDoc {
     this.transport.start()
 
     // Collect incremental Yjs updates; debounce into a single publish.
-    // Guard both the legacy 'remote' string origin and transport-specific origins.
     this.doc.on('update', (update: Uint8Array, origin: unknown) => {
-      if (this.isRemoteOrigin(origin)) return
+      if (this.isRemoteOrigin(origin)) {
+        return
+      }
+
       this.pendingUpdates.push(update)
 
-      if (this.debounceTimer) clearTimeout(this.debounceTimer)
+      if (this.debounceTimer) {
+        clearTimeout(this.debounceTimer)
+      }
+
       this.debounceTimer = setTimeout(() => {
         const captured = [...this.pendingUpdates]
         this.pendingUpdates = []
@@ -166,6 +167,17 @@ export class SwarmDoc {
     this.init()
     this.startFetchProcess()
     this.startMemberListPoll()
+    this.startCursorBroadcast()
+  }
+
+  /**
+   * Updates the local cursor position in the shared `Y.Text` and schedules a broadcast.
+   * Call this from the editor's selection-change handler.
+   *
+   * @param cursor Character index offsets `{ anchor, head }`, or `null` to clear.
+   */
+  public updateCursor(cursor: { anchor: number; head: number } | null): void {
+    this.localCursor = cursor
   }
 
   // Returns true for any origin that should not trigger a Swarm publish or RTC forward.
@@ -182,6 +194,11 @@ export class SwarmDoc {
       this.memberListPollTimer = null
     }
 
+    if (this.cursorTimer) {
+      clearInterval(this.cursorTimer)
+      this.cursorTimer = null
+    }
+
     this.transport.stop()
     this.emitter.cleanAll()
     this.fetchProcessRunning = false
@@ -218,10 +235,7 @@ export class SwarmDoc {
     this.publishInFlight = true
 
     try {
-      // Full snapshot → written to Swarm with mutable stamp (old chunks get recycled)
       const snapshot = encode(Y.encodeStateAsUpdate(this.doc))
-
-      // Delta → sent in notification payload for peers already online (no Swarm read needed)
       const delta = encode(Y.mergeUpdates(allUpdates))
 
       const nextIndex = this.ownIndex === -1n ? 0n : this.ownIndex + 1n
@@ -229,7 +243,7 @@ export class SwarmDoc {
         `${TAG} publishSnapshot → index: ${nextIndex}, snapshot: ${(snapshot.length * 0.75) | 0}B, delta: ${(delta.length * 0.75) | 0}B`,
       )
 
-      // TODO: sign messages ?
+      // TODO: sign messages
       const messageObj: MessageData = {
         id: uuidV4(),
         username: this.username,
@@ -246,13 +260,18 @@ export class SwarmDoc {
       this.ownIndex = nextIndex
       console.log(`${TAG} publishSnapshot ✓ index: ${this.ownIndex}`)
 
+      const deltaBytes = decode(delta)
+      const sig = this.signer.sign(deltaBytes).toHex()
+
       this.transport.publish({
+        type: 'doc',
         v: API_VERSION,
         topic: this.docTopic,
         author: this.ownAddress,
         username: this.username,
         feedIndex: Number(nextIndex),
         delta,
+        sig,
       })
     } catch (err) {
       this.errorHandler.handleError(err, `${TAG}.publishSnapshot`)
@@ -323,13 +342,13 @@ export class SwarmDoc {
 
     this.emitter.emit(DOC_EVENTS.MEMBERS_UPDATED, this.members.all())
 
-    // JOIN_FEED_INDEX sentinel: announce presence via transport
+    // Announce presence to online peers
     this.transport.publish({
+      type: 'join',
       v: API_VERSION,
       topic: this.docTopic,
       author: this.ownAddress,
       username: this.username,
-      feedIndex: Number(JOIN_FEED_INDEX),
     })
     console.log(`${TAG} initMemberList: join notification sent`)
 
@@ -485,8 +504,7 @@ export class SwarmDoc {
 
       if (author === this.ownAddress) return
 
-      // JOIN_FEED_INDEX: join notification — register peer and fetch their latest snapshot
-      if (payload.feedIndex === Number(JOIN_FEED_INDEX)) {
+      if (payload.type === 'join') {
         console.log(`${TAG} notification: join from ${author.slice(0, 8)}…`)
         this.registerMember(author, payload.username)
         this.emitter.emit(DOC_EVENTS.MEMBERS_UPDATED, this.members.all())
@@ -495,6 +513,48 @@ export class SwarmDoc {
         return
       }
 
+      if (payload.type === 'cursor') {
+        this.emitter.emit(DOC_EVENTS.AWARENESS_UPDATED, {
+          address: author,
+          username: payload.username,
+          cursor: payload.cursor,
+        })
+
+        return
+      }
+
+      if (payload.type !== 'doc') {
+        console.warn(`${TAG} unknown payload type from ${author.slice(0, 8)}…`)
+
+        return
+      }
+
+      if (!payload.delta) {
+        console.warn(`${TAG} dropping message from ${author.slice(0, 8)}…, no delta provided`)
+
+        return
+      }
+
+      if (!payload.sig) {
+        console.warn(`${TAG} dropping unsigned delta from ${author.slice(0, 8)}…`)
+
+        return
+      }
+
+      try {
+        const valid = new Signature(payload.sig).isValid(decode(payload.delta), author)
+
+        if (!valid) {
+          console.warn(`${TAG} dropping delta with invalid signature from ${author.slice(0, 8)}…`)
+
+          return
+        }
+      } catch {
+        console.warn(`${TAG} signature verification error from ${author.slice(0, 8)}… — dropping`)
+
+        return
+      }
+
       console.log(
         `${TAG} notification: author=${author.slice(0, 8)}…, feedIndex=${payload.feedIndex}, hasDelta=${Boolean(payload.delta)}`,
       )
@@ -503,4 +563,17 @@ export class SwarmDoc {
 
     this.transport.subscribe(this.docTopic, handler)
   }
+
+  private startCursorBroadcast(): void {
+    this.cursorTimer = setInterval(() => {
+      this.transport.publish({
+        type: 'cursor',
+        v: API_VERSION,
+        topic: this.docTopic,
+        author: this.ownAddress,
+        username: this.username,
+        cursor: this.localCursor,
+      })
+    }, DEBOUNCE_MS)
+  }
 }
diff --git a/src/lib/doc/events.ts b/src/lib/doc/events.ts
index 395b698..3a3f6da 100644
--- a/src/lib/doc/events.ts
+++ b/src/lib/doc/events.ts
@@ -6,6 +6,8 @@
  * swarmDoc.getEmitter().on(DOC_EVENTS.DOC_ERROR,   (err: Error) => ...)
  * swarmDoc.getEmitter().on(DOC_EVENTS.MEMBERS_UPDATED, (members: Map<string, string>) => ...)
  * swarmDoc.getEmitter().on(DOC_EVENTS.PEERS_CONNECTED, (connected: true) => ...)
+ * swarmDoc.getEmitter().on(DOC_EVENTS.AWARENESS_UPDATED,
+ *   (update: { address: string; username: string; cursor: { anchor: number; head: number } | null }) => ...)
  * ```
  */
 export const DOC_EVENTS = {
@@ -17,4 +19,10 @@ export const DOC_EVENTS = {
   MEMBERS_UPDATED: 'membersUpdated',
   /** Fired once when the transport has at least one connected peer. Payload: `true`. */
   PEERS_CONNECTED: 'peersConnected',
+  /**
+   * Fired when a peer's cursor position changes.
+   * Payload: `{ address: string; username: string; cursor: { anchor: number; head: number } | null }`.
+   * `cursor: null` means the peer deselected or disconnected.
+   */
+  AWARENESS_UPDATED: 'awarenessUpdated',
 }
diff --git a/src/lib/doc/members.ts b/src/lib/doc/members.ts
index 77c8f6a..eca0721 100644
--- a/src/lib/doc/members.ts
+++ b/src/lib/doc/members.ts
@@ -41,7 +41,6 @@ export class Members {
     this.topic = Topic.fromString(memberFeedId)
     this.bee = new Bee(beeUrl)
     this.stamp = stamp || PLACEHOLDER_STAMP
-    console.log(`${TAG} consensus address: ${this.address}`)
   }
 
   // ── Local session tracking ────────────────────────────────────────────────
@@ -126,16 +125,13 @@ export class Members {
     }
 
     if (members.has(normalizedAddress)) {
-      console.log(`${TAG} add: ${normalizedAddress.slice(0, 8)}… already in list`)
+      console.debug(`${TAG} add: ${normalizedAddress.slice(0, 8)}… already in list`)
 
       return members
     }
 
     members.set(normalizedAddress, username)
     const nextIndex = this.currentIndex === -1n ? 0n : this.currentIndex + 1n
-    console.log(
-      `${TAG} add: writing index ${nextIndex}, total: ${members.size}, members: ${JSON.stringify(Object.fromEntries(members))}`,
-    )
 
     const writer = this.bee.makeFeedWriter(this.topic, this.signer)
     try {
@@ -162,11 +158,11 @@ export class Members {
         3,
         500,
       )
-      console.log(`${TAG} add: verified — ${Array.from(verified.keys()).join(', ')}`)
+      console.debug(`${TAG} add: verified — ${Array.from(verified.keys()).join(', ')}`)
 
       return verified
     } catch {
-      console.log(`${TAG} add: verify timed out, using optimistic list`)
+      console.debug(`${TAG} add: verify timed out, using optimistic list`)
 
       return members
     }
diff --git a/src/lib/index.ts b/src/lib/index.ts
index 43a6468..aa12c4b 100644
--- a/src/lib/index.ts
+++ b/src/lib/index.ts
@@ -6,19 +6,14 @@ export { DOC_EVENTS } from './doc/events'
 export { createSwarmRtcTransport } from './notification/swarmRtcTransport'
 export { createYWebrtcTransport } from './notification/yWebrtcTransport'
 
-export { createBroadcastChannelTransport } from './notification/broadcastChannel'
-export { createSwarmFeedTransport } from './notification/swarmFeed'
 export { createWakuTransport } from './notification/wakuTransport'
 export { createSwarmPubSubTransport } from './notification/swarmPubSubTransport'
 
 export type { DocSettings } from './interfaces'
-export type { NotificationPayload, NotificationHandler } from './interfaces'
+export type { NotificationPayload, NotificationHandler, JoinPayload, DocPayload, CursorPayload } from './interfaces'
 export type { SignalRecord, SignalFeedPayload } from './interfaces'
 export type { DocTransport, DocTransportDeps, DocTransportFactory } from './interfaces'
 
-export { BroadcastChannelNotificationProvider } from './notification/broadcastChannel'
-export { SwarmFeedNotificationProvider } from './notification/swarmFeed'
-
 export { getSigner, validateStamps } from './utils/bee'
 export { indexStrToBigint, uuidV4 } from './utils/common'
 export { PLACEHOLDER_STAMP } from './utils/constants'
diff --git a/src/lib/interfaces/notification.ts b/src/lib/interfaces/notification.ts
index 36ab3f2..aa71f99 100644
--- a/src/lib/interfaces/notification.ts
+++ b/src/lib/interfaces/notification.ts
@@ -1,25 +1,61 @@
-/** Opaque payload exchanged between peers via the notification channel. */
-export interface NotificationPayload {
+/** Fields shared by every notification payload variant. */
+interface BasePayload {
   /** Protocol version string (e.g. `"v1"`). Used to detect incompatible clients. */
   v: string
   /** Swarm feed topic identifier for the collaborative document. */
   topic: string
   /** Ethereum address of the publishing peer (hex, no 0x prefix). */
   author: string
-  /** Nickname of the publishing peer  */
+  /** Nickname of the publishing peer. */
   username: string
-  /**
-   * Swarm doc-feed index written by the author.
-   * Set to `JOIN_FEED_INDEX` (-1) to signal a peer join event (no doc update).
-   */
+}
+
+/**
+ * Peer-join announcement. Signals that a new peer has joined the session and
+ * that receivers should fetch the peer's latest snapshot from their Swarm feed.
+ * Carries no document data.
+ */
+export interface JoinPayload extends BasePayload {
+  type: 'join'
+}
+
+/**
+ * Incremental document update from a peer. Contains the Swarm doc-feed index
+ * written by the author and an optional base64 Yjs delta for fast-path application.
+ * The delta MUST be accompanied by a secp256k1 signature; unsigned deltas are dropped.
+ */
+export interface DocPayload extends BasePayload {
+  type: 'doc'
+  /** Swarm doc-feed index written by the author for this update. */
   feedIndex: number
   /**
-   * Base64-encoded Yjs incremental update (delta) for peers already online.
-   * Absent on join notifications or when a snapshot-only write occurred.
+   * Base64-encoded Yjs incremental update for peers already online.
+   * Absent when only a snapshot was written (e.g. retry after a missed delta).
    */
   delta?: string
+  /**
+   * Hex-encoded secp256k1 signature of the raw delta bytes (before base64 encoding).
+   * Required when `delta` is present. Receivers MUST verify and drop invalid signatures.
+   */
+  sig?: string
 }
 
+/**
+ * Cursor-only awareness update. Sent on a ~500ms timer independent of doc edits.
+ * Carries no document data and requires no signature.
+ */
+export interface CursorPayload extends BasePayload {
+  type: 'cursor'
+  /**
+   * Current cursor position in the shared `Y.Text` (character index offsets).
+   * `null` signals the peer has deselected or disconnected.
+   */
+  cursor: { anchor: number; head: number } | null
+}
+
+/** Union of all notification payload variants exchanged between peers. */
+export type NotificationPayload = JoinPayload | DocPayload | CursorPayload
+
 /** Callback invoked whenever a notification arrives on the subscribed topic. */
 export type NotificationHandler = (payload: NotificationPayload) => void
 
diff --git a/src/lib/notification/broadcastChannel.ts b/src/lib/notification/broadcastChannel.ts
deleted file mode 100644
index 0be4f41..0000000
--- a/src/lib/notification/broadcastChannel.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-import { DocTransport, DocTransportFactory } from '../interfaces/docTransport'
-import { NotificationHandler, NotificationPayload, NotificationProvider } from '../interfaces/notification'
-
-/**
- * `NotificationProvider` backed by the browser `BroadcastChannel` API.
- *
- * Delivers messages between same-origin tabs/windows sharing the same topic channel.
- * Useful for development and multi-tab testing — does not cross network boundaries.
- */
-export class BroadcastChannelNotificationProvider implements NotificationProvider {
-  private channel: BroadcastChannel | null = null
-
-  subscribe(topic: string, handler: NotificationHandler): void {
-    this.unsubscribe()
-    this.channel = new BroadcastChannel(topic)
-    this.channel.onmessage = (event: MessageEvent<NotificationPayload>) => {
-      handler(event.data)
-    }
-  }
-
-  publish(payload: NotificationPayload): void {
-    if (this.channel) {
-      this.channel.postMessage(payload)
-    }
-  }
-
-  unsubscribe(): void {
-    if (this.channel) {
-      this.channel.close()
-      this.channel = null
-    }
-  }
-}
-
-class BroadcastChannelDocTransport implements DocTransport {
-  private provider = new BroadcastChannelNotificationProvider()
-
-  start(): void {}
-
-  stop(): void {
-    this.provider.unsubscribe()
-  }
-
-  subscribe(topic: string, handler: NotificationHandler): void {
-    this.provider.subscribe(topic, handler)
-  }
-
-  publish(payload: NotificationPayload): void {
-    this.provider.publish(payload)
-  }
-
-  // BroadcastChannel uses a shared channel — no per-peer setup needed
-  connectToPeer(_address: string): void {}
-
-  isRemoteOrigin(_origin: unknown): boolean {
-    return false
-  }
-}
-
-/**
- * Creates a `DocTransportFactory` using the browser `BroadcastChannel` API.
- *
- * Intended for same-origin multi-tab testing. Does not work across devices or origins.
- * When using y-webrtc (`createYWebrtcTransport`), this transport is redundant because
- * y-webrtc's built-in BroadcastChannel already handles cross-tab Y.js sync.
- */
-export function createBroadcastChannelTransport(): DocTransportFactory {
-  return _deps => new BroadcastChannelDocTransport()
-}
diff --git a/src/lib/notification/swarmFeed.ts b/src/lib/notification/swarmFeed.ts
deleted file mode 100644
index afde1e6..0000000
--- a/src/lib/notification/swarmFeed.ts
+++ /dev/null
@@ -1,261 +0,0 @@
-import { Bee, FeedIndex, PrivateKey, Topic } from '@ethersphere/bee-js'
-
-import { DocTransport, DocTransportFactory } from '../interfaces/docTransport'
-import { NotificationHandler, NotificationPayload, NotificationProvider } from '../interfaces/notification'
-import { isNotFoundError } from '../utils/bee'
-import { remove0x } from '../utils/common'
-import { NOTIFY_FEED_SUFFIX } from '../utils/constants'
-
-function isAbortError(error: unknown): boolean {
-  if (!(error instanceof Error)) return false
-
-  return error.name === 'AbortError' || error.message?.includes('aborted')
-}
-
-const POLL_INTERVAL_MS = 1500
-const SLOW_POLL_INTERVAL_MS = 5000
-const SLOW_POLL_THRESHOLD = 5
-const MAX_DRAIN = 10
-const CHUNK_RETRIEVAL_TIMEOUT_MS = '1000ms'
-const TAG = 'SwarmFeedNotificationProvider'
-
-/**
- * Notification transport backed by per-user Swarm mutable feeds.
- *
- * Each peer writes outgoing `NotificationPayload` objects to their own
- * `<topic>_notify<address>` feed. Incoming notifications are obtained by
- * polling the feeds of all registered peers at a 1.5s interval, automatically
- * backing off to 5s when no new messages are found.
- *
- * Implements both `NotificationProvider` (for standalone use) and the
- * `DocTransport`-compatible `SwarmFeedDocTransport` wrapper (via `createSwarmFeedTransport`).
- */
-export class SwarmFeedNotificationProvider implements NotificationProvider {
-  private bee: Bee
-  private signer: PrivateKey
-  private mutableStamp: string
-  private topic: string
-  private ownAddress: string
-
-  private handler: NotificationHandler | null = null
-  private pollTimer: ReturnType<typeof setInterval> | null = null
-  private currentPollIntervalMs = POLL_INTERVAL_MS
-  private polling = false
-  private abortController: AbortController | null = null
-  private emptyPollCount = 0
-
-  // address → next expected notification-feed index (null = not yet anchored)
-  private members: Map<string, FeedIndex | null> = new Map()
-
-  // Tracks the next index to write on own notification feed.
-  // null = not yet probed (resolved on first publish).
-  private nextNotifyIndex: FeedIndex | null = null
-
-  // Serialises publish calls so the explicit index counter stays consistent
-  // even when publish() is called rapidly (e.g. quick successive edits).
-  private publishQueue: Promise<void> = Promise.resolve()
-
-  constructor(beeApiUrl: string, privateKey: string, mutableStamp: string, topic: string) {
-    this.bee = new Bee(beeApiUrl)
-    this.signer = new PrivateKey(remove0x(privateKey))
-    this.mutableStamp = mutableStamp
-    this.topic = topic
-    this.ownAddress = this.signer.publicKey().address().toString()
-  }
-
-  // Per-user notification feed topic: topic + "_notify" + address
-  private notifyTopic(address: string): Topic {
-    return Topic.fromString(this.topic + NOTIFY_FEED_SUFFIX + address)
-  }
-
-  subscribe(_topic: string, handler: NotificationHandler): void {
-    this.unsubscribe()
-    this.handler = handler
-    this.currentPollIntervalMs = POLL_INTERVAL_MS
-    this.emptyPollCount = 0
-    this.pollTimer = setInterval(() => this.poll(), POLL_INTERVAL_MS)
-  }
-
-  // Fire-and-forget. Serialised via publishQueue so index tracking stays consistent.
-  publish(payload: NotificationPayload): void {
-    this.publishQueue = this.publishQueue.then(() =>
-      this.doPublish(payload).catch(err => {
-        if (!isAbortError(err)) console.error(`${TAG} publish failed:`, err)
-      }),
-    )
-  }
-
-  private async doPublish(payload: NotificationPayload): Promise<void> {
-    // Probe own notification feed once on first publish to find the tip index
-    // (handles app restarts where the local counter was lost).
-    if (this.nextNotifyIndex === null) {
-      try {
-        const reader = this.bee.makeFeedReader(this.notifyTopic(this.ownAddress), this.ownAddress)
-        const tip = await reader.downloadPayload()
-        this.nextNotifyIndex = tip.feedIndexNext ?? tip.feedIndex.next()
-      } catch {
-        // 404: never published before, start at index 0
-        this.nextNotifyIndex = FeedIndex.fromBigInt(0n)
-      }
-    }
-
-    const writeIndex = this.nextNotifyIndex
-    const publishedAt = Date.now()
-    const data = JSON.stringify({ ...payload, _publishedAt: publishedAt })
-
-    console.debug(
-      `${TAG} publish → notifyIndex=${writeIndex.toBigInt()} docFeedIndex=${payload.feedIndex} author=${payload.author.slice(0, 8)}… deltaBytes=${payload.delta ? Math.round(payload.delta.length * 0.75) : 0}`,
-    )
-
-    const notifyWriter = this.bee.makeFeedWriter(this.notifyTopic(this.ownAddress), this.signer)
-    await notifyWriter.uploadPayload(this.mutableStamp, data, { index: writeIndex, deferred: false })
-
-    // Advance local counter before the next enqueued publish can run
-    this.nextNotifyIndex = writeIndex.next()
-  }
-
-  addMember(address: string): void {
-    if (address === this.ownAddress || this.members.has(address)) return
-    this.members.set(address, null)
-    console.log(`${TAG} addMember: ${address.slice(0, 8)}…`)
-  }
-
-  private adjustPollInterval(newIntervalMs: number): void {
-    if (this.currentPollIntervalMs === newIntervalMs || !this.pollTimer) return
-    this.currentPollIntervalMs = newIntervalMs
-    clearInterval(this.pollTimer)
-    this.pollTimer = setInterval(() => this.poll(), newIntervalMs)
-  }
-
-  private async poll(): Promise<void> {
-    if (!this.handler || this.polling) return
-    this.polling = true
-
-    // Fresh AbortController per cycle; abort the previous one in case it leaked
-    const cycleController = new AbortController()
-    const prev = this.abortController
-    this.abortController = cycleController
-    prev?.abort()
-
-    try {
-      const results = await Promise.allSettled(
-        [...this.members.keys()].map(address => this.pollMember(address, cycleController.signal)),
-      )
-
-      const totalDrained = results.reduce((sum, r) => sum + (r.status === 'fulfilled' ? r.value : 0), 0)
-
-      if (totalDrained === 0) {
-        this.emptyPollCount++
-
-        if (this.emptyPollCount >= SLOW_POLL_THRESHOLD) {
-          this.adjustPollInterval(SLOW_POLL_INTERVAL_MS)
-        }
-      } else {
-        this.emptyPollCount = 0
-        this.adjustPollInterval(POLL_INTERVAL_MS)
-      }
-    } finally {
-      this.polling = false
-    }
-  }
-
-  private async pollMember(address: string, signal: AbortController['signal']): Promise<number> {
-    const nextExpected = this.members.get(address) ?? FeedIndex.fromBigInt(0n)
-
-    const notifyReader = this.bee.makeFeedReader(this.notifyTopic(address), address, {
-      headers: { 'swarm-chunk-retrieval-timeout': CHUNK_RETRIEVAL_TIMEOUT_MS },
-      signal,
-    })
-
-    let nextIndex = nextExpected
-    let drained = 0
-
-    while (drained < MAX_DRAIN) {
-      if (!this.handler || signal.aborted) break
-
-      let result
-      try {
-        result = await notifyReader.downloadPayload({ index: nextIndex })
-      } catch (err) {
-        if (!isNotFoundError(err) && !isAbortError(err)) {
-          console.error(`${TAG} drain failed for ${address.slice(0, 8)}…:`, err)
-        }
-
-        break
-      }
-
-      nextIndex = result.feedIndex.next()
-      this.members.set(address, nextIndex)
-
-      const raw = JSON.parse(result.payload.toUtf8()) as NotificationPayload & { _publishedAt?: number }
-      const { _publishedAt: _, ...payload } = raw
-      this.handler(payload)
-      drained++
-    }
-
-    return drained
-  }
-
-  unsubscribe(): void {
-    if (this.pollTimer) {
-      clearInterval(this.pollTimer)
-      this.pollTimer = null
-    }
-
-    this.abortController?.abort()
-    this.abortController = null
-    this.handler = null
-    this.members.clear()
-  }
-}
-
-class SwarmFeedDocTransport implements DocTransport {
-  private provider: SwarmFeedNotificationProvider
-
-  constructor(beeApiUrl: string, privateKey: string, mutableStamp: string, topic: string) {
-    this.provider = new SwarmFeedNotificationProvider(beeApiUrl, privateKey, mutableStamp, topic)
-  }
-
-  start(): void {}
-
-  stop(): void {
-    this.provider.unsubscribe()
-  }
-
-  subscribe(topic: string, handler: NotificationHandler): void {
-    this.provider.subscribe(topic, handler)
-  }
-
-  publish(payload: NotificationPayload): void {
-    this.provider.publish(payload)
-  }
-
-  connectToPeer(address: string): void {
-    this.provider.addMember(address)
-  }
-
-  isRemoteOrigin(_origin: unknown): boolean {
-    return false
-  }
-}
-
-/**
- * Creates a `DocTransportFactory` that delivers notifications via Swarm mutable feeds.
- *
- * Use this transport when peers share a Bee node API and need persistent,
- * offline-tolerant message delivery. Notifications survive node restarts because
- * they are stored on Swarm feeds rather than kept in memory.
- *
- * @param beeApiUrl Bee node HTTP API URL.
- * @param privateKey Signer's secp256k1 private key (hex).
- * @param mutableStamp Mutable postage batch ID for notification feed writes.
- * @param topic Room topic string (used to derive per-user feed identifiers).
- */
-export function createSwarmFeedTransport(
-  beeApiUrl: string,
-  privateKey: string,
-  mutableStamp: string,
-  topic: string,
-): DocTransportFactory {
-  return _deps => new SwarmFeedDocTransport(beeApiUrl, privateKey, mutableStamp, topic)
-}
diff --git a/src/lib/notification/swarmPubSubTransport.ts b/src/lib/notification/swarmPubSubTransport.ts
index b468d3b..cd7a7c7 100644
--- a/src/lib/notification/swarmPubSubTransport.ts
+++ b/src/lib/notification/swarmPubSubTransport.ts
@@ -4,12 +4,14 @@ import { DOC_EVENTS } from '../doc/events'
 import type { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/docTransport'
 import type { NotificationHandler, NotificationPayload } from '../interfaces/notification'
 import { ErrorHandler } from '../utils/error'
+import { Logger } from '../utils/logger'
 
 const TAG = 'SwarmNotifTransport'
 const WS_RECONNECT_TIMEOUT_MS = 10_000
 
 class SwarmPubSubDocTransport implements DocTransport {
   private errorHandler = ErrorHandler.getInstance()
+  private logger = Logger.getInstance()
   private subscription: PubsubSubscription | null = null
   private stopped = false
   private isConnecting = false
@@ -68,7 +70,7 @@ class SwarmPubSubDocTransport implements DocTransport {
           this.isConnecting = false
           this.isConnected = true
           this.deps.emitter.emit(DOC_EVENTS.PEERS_CONNECTED, true)
-          console.log(`${TAG} connected, topicAddress derived from docFeedId=${this.deps.docFeedId}`)
+          this.logger.log(`${TAG} connected, docFeedId=${this.deps.docFeedId}`)
 
           // Drain buffered publishes now that the WebSocket is open
           const toSend = this.pendingPublishes.splice(0)
@@ -96,7 +98,7 @@ class SwarmPubSubDocTransport implements DocTransport {
         },
         onClose: _sub => {
           if (!this.stopped) {
-            console.warn(`${TAG} connection closed, reconnecting…`)
+            this.logger.warn(`${TAG} connection closed, reconnecting…`)
             this.subscription = null
             this.isConnecting = false
             this.isConnected = false
diff --git a/src/lib/notification/swarmRtcTransport.ts b/src/lib/notification/swarmRtcTransport.ts
index 3a2bccf..d458ee1 100644
--- a/src/lib/notification/swarmRtcTransport.ts
+++ b/src/lib/notification/swarmRtcTransport.ts
@@ -7,6 +7,7 @@ import type { NotificationHandler, NotificationPayload } from '../interfaces/not
 import { uuidV4 } from '../utils/common'
 import { FALLBACK_ICE_SERVER_URL } from '../utils/constants'
 import { ErrorHandler } from '../utils/error'
+import { Logger } from '../utils/logger'
 
 import { SwarmSignal } from './swarmSignal'
 
@@ -18,6 +19,7 @@ const CHANNEL_BINARY_TYPE = 'arraybuffer'
 
 class SwarmRtcTransport implements DocTransport {
   private errorHandler = ErrorHandler.getInstance()
+  private logger = Logger.getInstance()
 
   private swarmSignal: SwarmSignal
   private swarmRtcPeers = new Map<string, RTCPeerConnection>()
@@ -75,13 +77,13 @@ class SwarmRtcTransport implements DocTransport {
   /** Decides whether to initiate a WebRTC connection to a newly discovered peer. */
   connectToPeer(address: string): void {
     if (this.swarmRtcPeers.has(address)) {
-      console.log(`${TAG} connectToPeer ${address.slice(0, 8)}… skipped — already connected`)
+      this.logger.debug(`${TAG} connectToPeer ${address.slice(0, 8)}… skipped — already connected`)
 
       return
     }
 
     const role = this.isInitiatorFor(address) ? 'initiator' : 'answerer'
-    console.log(`${TAG} connectToPeer ${address.slice(0, 8)}… role=${role}`)
+    this.logger.debug(`${TAG} connectToPeer ${address.slice(0, 8)}… role=${role}`)
 
     if (this.isInitiatorFor(address)) {
       this.initiateConnectionTo(address)
@@ -96,9 +98,9 @@ class SwarmRtcTransport implements DocTransport {
 
   /** Creates an RTCPeerConnection as the initiator, gathers ICE, publishes offer to signal feed. */
   private async initiateConnectionTo(peerAddress: string): Promise<void> {
-    if (this.swarmRtcPeers.has(peerAddress)) return
-
-    console.log(`${TAG} initiating → ${peerAddress.slice(0, 8)}…`)
+    if (this.swarmRtcPeers.has(peerAddress)) {
+      return
+    }
 
     const pc = new RTCPeerConnection({
       iceServers: this.iceServers?.length
@@ -108,12 +110,12 @@ class SwarmRtcTransport implements DocTransport {
     this.swarmRtcPeers.set(peerAddress, pc)
 
     pc.addEventListener('connectionstatechange', () => {
-      console.log(`${TAG} [initiator→${peerAddress.slice(0, 8)}] connectionState=${pc.connectionState}`)
+      this.logger.debug(`${TAG} [initiator→${peerAddress.slice(0, 8)}] connectionState=${pc.connectionState}`)
 
       if (pc.connectionState === 'failed') {
         this.swarmRtcPeers.delete(peerAddress)
         this.pendingOfferSessions.delete(peerAddress)
-        console.log(`${TAG} [initiator→${peerAddress.slice(0, 8)}] ICE failed — retrying in 10s`)
+        this.logger.debug(`${TAG} [initiator→${peerAddress.slice(0, 8)}] ICE failed — retrying in 10s`)
         setTimeout(() => {
           if (!this.stopped && !this.swarmRtcPeers.has(peerAddress)) {
             this.initiateConnectionTo(peerAddress).catch(err =>
@@ -128,11 +130,11 @@ class SwarmRtcTransport implements DocTransport {
     })
 
     pc.addEventListener('iceconnectionstatechange', () => {
-      console.log(`${TAG} [initiator→${peerAddress.slice(0, 8)}] iceConnectionState=${pc.iceConnectionState}`)
+      this.logger.debug(`${TAG} [initiator→${peerAddress.slice(0, 8)}] iceConnectionState=${pc.iceConnectionState}`)
     })
 
     pc.addEventListener('icecandidateerror', (e: RTCPeerConnectionIceErrorEvent) => {
-      console.warn(
+      this.logger.warn(
         `${TAG} [initiator→${peerAddress.slice(0, 8)}] ICE candidate error — url=${e.url} errorCode=${e.errorCode} errorText=${e.errorText}`,
       )
     })
@@ -140,27 +142,30 @@ class SwarmRtcTransport implements DocTransport {
     const dc = pc.createDataChannel('yjs')
 
     dc.addEventListener('open', () => this.setupDataChannel(peerAddress, dc))
-    dc.addEventListener('error', e => console.error(`${TAG} [initiator] dataChannel error`, e))
+    dc.addEventListener('error', e => this.logger.error(`${TAG} [initiator] dataChannel error`, e))
 
     const offer = await pc.createOffer()
     await pc.setLocalDescription(offer)
 
-    console.log(`${TAG} ICE gathering started for ${peerAddress.slice(0, 8)}…`)
+    this.logger.debug(`${TAG} ICE gathering started for ${peerAddress.slice(0, 8)}…`)
+
     await this.waitForIceGatheringComplete(pc)
 
     const sdp = pc.localDescription?.sdp ?? ''
     const candidateCount = (sdp.match(/^a=candidate:/gm) || []).length
-    console.log(`${TAG} ICE gathered for ${peerAddress.slice(0, 8)}… candidates=${candidateCount} sdpLen=${sdp.length}`)
+    this.logger.debug(
+      `${TAG} ICE gathered for ${peerAddress.slice(0, 8)}… candidates=${candidateCount} sdpLen=${sdp.length}`,
+    )
 
     if (this.stopped) {
       pc.close()
       this.swarmRtcPeers.delete(peerAddress)
-      console.log(`${TAG} initiateConnectionTo ${peerAddress.slice(0, 8)}… aborted — instance stopped`)
+      this.logger.debug(`${TAG} initiateConnectionTo ${peerAddress.slice(0, 8)}… aborted — instance stopped`)
 
       return
     }
 
-    console.log(`${TAG} initiateConnectionTo ${peerAddress.slice(0, 8)}… instance live, writing offer`)
+    this.logger.debug(`${TAG} initiateConnectionTo ${peerAddress.slice(0, 8)}… instance live, writing offer`)
     const sessionId = uuidV4()
     this.pendingOfferSessions.set(peerAddress, sessionId)
 
@@ -174,7 +179,8 @@ class SwarmRtcTransport implements DocTransport {
     }
 
     await this.swarmSignal.writeRecord(record)
-    console.log(`${TAG} offer written → ${peerAddress.slice(0, 8)}… sessionId=${sessionId.slice(0, 8)}`)
+
+    this.logger.debug(`${TAG} offer written → ${peerAddress.slice(0, 8)}… sessionId=${sessionId.slice(0, 8)}`)
   }
 
   /** Receives a peer's offer, creates an answer, publishes it to own signal feed. */
@@ -185,7 +191,9 @@ class SwarmRtcTransport implements DocTransport {
 
     if (this.sentAnswerKeys.has(key)) return
 
-    console.log(`${TAG} answering offer from ${peerAddress.slice(0, 8)}… sessionId=${offer.sessionId.slice(0, 8)}`)
+    this.logger.debug(
+      `${TAG} answering offer from ${peerAddress.slice(0, 8)}… sessionId=${offer.sessionId.slice(0, 8)}`,
+    )
     this.sentAnswerKeys.add(key)
 
     const pc = new RTCPeerConnection({
@@ -196,7 +204,7 @@ class SwarmRtcTransport implements DocTransport {
     this.swarmRtcPeers.set(peerAddress, pc)
 
     pc.addEventListener('connectionstatechange', () => {
-      console.log(`${TAG} [answerer←${peerAddress.slice(0, 8)}] connectionState=${pc.connectionState}`)
+      this.logger.debug(`${TAG} [answerer←${peerAddress.slice(0, 8)}] connectionState=${pc.connectionState}`)
 
       if (pc.connectionState === 'failed' || pc.connectionState === 'closed') {
         this.swarmRtcPeers.delete(peerAddress)
@@ -204,39 +212,39 @@ class SwarmRtcTransport implements DocTransport {
     })
 
     pc.addEventListener('iceconnectionstatechange', () => {
-      console.log(`${TAG} [answerer←${peerAddress.slice(0, 8)}] iceConnectionState=${pc.iceConnectionState}`)
+      this.logger.debug(`${TAG} [answerer←${peerAddress.slice(0, 8)}] iceConnectionState=${pc.iceConnectionState}`)
     })
 
     pc.addEventListener('icecandidateerror', (e: RTCPeerConnectionIceErrorEvent) => {
-      console.warn(
+      this.logger.warn(
         `${TAG} [answerer←${peerAddress.slice(0, 8)}] ICE candidate error — url=${e.url} errorCode=${e.errorCode} errorText=${e.errorText}`,
       )
     })
 
     pc.addEventListener('datachannel', (event: RTCDataChannelEvent) => {
-      console.log(`${TAG} datachannel received from ${peerAddress.slice(0, 8)}…`)
+      this.logger.debug(`${TAG} datachannel received from ${peerAddress.slice(0, 8)}…`)
       const dc = event.channel
       dc.addEventListener('open', () => this.setupDataChannel(peerAddress, dc))
-      dc.addEventListener('error', e => console.error(`${TAG} [answerer] dataChannel error`, e))
+      dc.addEventListener('error', e => this.logger.error(`${TAG} [answerer] dataChannel error`, e))
     })
 
     await pc.setRemoteDescription({ type: SignalType.OFFER, sdp: offer.sdp })
     const answer = await pc.createAnswer()
     await pc.setLocalDescription(answer)
 
-    console.log(`${TAG} ICE gathering started (answerer) for ${peerAddress.slice(0, 8)}…`)
+    this.logger.debug(`${TAG} ICE gathering started (answerer) for ${peerAddress.slice(0, 8)}…`)
     await this.waitForIceGatheringComplete(pc)
 
     const sdp = pc.localDescription?.sdp ?? ''
     const candidateCount = (sdp.match(/^a=candidate:/gm) || []).length
-    console.log(
+    this.logger.debug(
       `${TAG} ICE gathered (answerer) for ${peerAddress.slice(0, 8)}… candidates=${candidateCount} sdpLen=${sdp.length}`,
     )
 
     if (this.stopped) {
       pc.close()
       this.swarmRtcPeers.delete(peerAddress)
-      console.log(`${TAG} answerPeerOffer ${peerAddress.slice(0, 8)}… aborted — instance stopped`)
+      this.logger.debug(`${TAG} answerPeerOffer ${peerAddress.slice(0, 8)}… aborted — instance stopped`)
 
       return
     }
@@ -251,12 +259,12 @@ class SwarmRtcTransport implements DocTransport {
     }
 
     await this.swarmSignal.writeRecord(record)
-    console.log(`${TAG} answer written → ${peerAddress.slice(0, 8)}… sessionId=${offer.sessionId.slice(0, 8)}`)
+    this.logger.debug(`${TAG} answer written → ${peerAddress.slice(0, 8)}… sessionId=${offer.sessionId.slice(0, 8)}`)
   }
 
   /** Polls each known peer's signal feed for offers (to answer) and answers (to finalise). */
   private startSignalPoll(): void {
-    console.log(`${TAG} signal poll started (interval=${SIGNAL_POLL_INTERVAL_MS}ms)`)
+    this.logger.debug(`${TAG} signal poll started (interval=${SIGNAL_POLL_INTERVAL_MS}ms)`)
     this.checkSignals()
     this.signalPollTimer = setInterval(() => this.checkSignals(), SIGNAL_POLL_INTERVAL_MS)
   }
@@ -275,7 +283,9 @@ class SwarmRtcTransport implements DocTransport {
 
     const peerAddrs = Array.from(peers.keys())
 
-    console.log(`${TAG} checking signals for ${peers.size} peer(s): ${peerAddrs.map(a => a.slice(0, 8)).join(', ')}`)
+    this.logger.debug(
+      `${TAG} checking signals for ${peers.size} peer(s): ${peerAddrs.map(a => a.slice(0, 8)).join(', ')}`,
+    )
 
     try {
       await Promise.allSettled(peerAddrs.map(addr => this.checkPeerSignals(addr)))
@@ -294,16 +304,16 @@ class SwarmRtcTransport implements DocTransport {
     const payload = await this.swarmSignal.read(peerAddress)
 
     if (!payload) {
-      console.log(`${TAG} no new signal from ${peerAddress.slice(0, 8)}…`)
+      this.logger.debug(`${TAG} no new signal from ${peerAddress.slice(0, 8)}…`)
 
       return
     }
 
-    console.log(`${TAG} signal feed for ${peerAddress.slice(0, 8)}… has ${payload.records.length} record(s)`)
+    this.logger.debug(`${TAG} signal feed for ${peerAddress.slice(0, 8)}… has ${payload.records.length} record(s)`)
 
     for (const record of payload.records) {
       const recordAgeS = Math.round((Date.now() - record.timestamp) / 1000)
-      console.log(
+      this.logger.debug(
         `${TAG}   record type=${record.type} to=${record.toAddress.slice(0, 8)} sessionId=${record.sessionId.slice(0, 8)} age=${recordAgeS}s`,
       )
 
@@ -318,7 +328,7 @@ class SwarmRtcTransport implements DocTransport {
     const ageMs = Date.now() - record.timestamp
 
     if (ageMs > OFFER_MAX_AGE_MS) {
-      console.log(`${TAG} skipping stale offer from ${peerAddress.slice(0, 8)}… age=${Math.round(ageMs / 1000)}s`)
+      this.logger.debug(`${TAG} skipping stale offer from ${peerAddress.slice(0, 8)}… age=${Math.round(ageMs / 1000)}s`)
 
       return
     }
@@ -326,13 +336,13 @@ class SwarmRtcTransport implements DocTransport {
     const key = `${peerAddress}:${record.sessionId}`
 
     if (this.swarmRtcPeers.has(peerAddress)) {
-      console.log(`${TAG} offer from ${peerAddress.slice(0, 8)}… skipped — already have PC`)
+      this.logger.debug(`${TAG} offer from ${peerAddress.slice(0, 8)}… skipped — already have PC`)
 
       return
     }
 
     if (this.sentAnswerKeys.has(key)) {
-      console.log(`${TAG} offer from ${peerAddress.slice(0, 8)}… skipped — already answered`)
+      this.logger.debug(`${TAG} offer from ${peerAddress.slice(0, 8)}… skipped — already answered`)
 
       return
     }
@@ -344,7 +354,9 @@ class SwarmRtcTransport implements DocTransport {
     const ageMs = Date.now() - record.timestamp
 
     if (ageMs > OFFER_MAX_AGE_MS) {
-      console.log(`${TAG} skipping stale answer from ${peerAddress.slice(0, 8)}… age=${Math.round(ageMs / 1000)}s`)
+      this.logger.debug(
+        `${TAG} skipping stale answer from ${peerAddress.slice(0, 8)}… age=${Math.round(ageMs / 1000)}s`,
+      )
 
       return
     }
@@ -352,7 +364,7 @@ class SwarmRtcTransport implements DocTransport {
     const pc = this.swarmRtcPeers.get(peerAddress)
     const expectedSession = this.pendingOfferSessions.get(peerAddress)
 
-    console.log(
+    this.logger.debug(
       `${TAG} answer from ${peerAddress.slice(0, 8)}… expectedSession=${expectedSession?.slice(0, 8) ?? 'none'} recordSession=${record.sessionId.slice(0, 8)} hasPC=${Boolean(pc)} alreadyAnswered=${Boolean(pc?.currentRemoteDescription)}`,
     )
 
@@ -361,14 +373,14 @@ class SwarmRtcTransport implements DocTransport {
     try {
       await pc.setRemoteDescription({ type: SignalType.ANSWER, sdp: record.sdp })
       this.pendingOfferSessions.delete(peerAddress)
-      console.log(`${TAG} handshake complete with ${peerAddress.slice(0, 8)}…`)
-      console.log(
+      this.logger.debug(`${TAG} handshake complete with ${peerAddress.slice(0, 8)}…`)
+      this.logger.debug(
         `${TAG} post-handshake state — connectionState=${pc.connectionState} iceConnectionState=${pc.iceConnectionState} signalingState=${pc.signalingState}`,
       )
 
       let polls = 0
       const poller = setInterval(() => {
-        console.log(
+        this.logger.debug(
           `${TAG} [poll ${++polls}] connectionState=${pc.connectionState} iceConnectionState=${pc.iceConnectionState}`,
         )
 
@@ -383,26 +395,26 @@ class SwarmRtcTransport implements DocTransport {
 
   /** Sets up Yjs sync over an open WebRTC data channel. */
   private setupDataChannel(peerAddress: string, channel: RTCDataChannel): void {
-    console.log(`${TAG} channel OPEN with ${peerAddress.slice(0, 8)}…`)
+    this.logger.debug(`${TAG} channel OPEN with ${peerAddress.slice(0, 8)}…`)
     this.deps.emitter.emit(DOC_EVENTS.PEERS_CONNECTED, true)
 
     // Must be set before any messages arrive; default 'blob' causes Uint8Array construction to fail.
     channel.binaryType = CHANNEL_BINARY_TYPE
 
     const initialState = Y.encodeStateAsUpdate(this.deps.doc)
-    console.log(`${TAG} sending initial state to ${peerAddress.slice(0, 8)}… bytes=${initialState.length}`)
+    this.logger.debug(`${TAG} sending initial state to ${peerAddress.slice(0, 8)}… bytes=${initialState.length}`)
     channel.send(initialState as unknown as Uint8Array<ArrayBuffer>)
 
     channel.addEventListener('message', (event: MessageEvent) => {
       const data = new Uint8Array(event.data as ArrayBuffer)
-      console.log(`${TAG} received ${data.length}B from ${peerAddress.slice(0, 8)}…`)
+      this.logger.debug(`${TAG} received ${data.length}B from ${peerAddress.slice(0, 8)}…`)
       Y.applyUpdate(this.deps.doc, data, 'swarm-rtc')
       this.deps.emitter.emit(DOC_EVENTS.DOC_UPDATED, this.deps.doc)
     })
 
     const forwardUpdate = (update: Uint8Array, origin: unknown) => {
       if (origin !== 'swarm-rtc' && origin !== 'remote' && channel.readyState === 'open') {
-        console.log(`${TAG} forwarding update ${update.length}B → ${peerAddress.slice(0, 8)}…`)
+        this.logger.debug(`${TAG} forwarding update ${update.length}B → ${peerAddress.slice(0, 8)}…`)
         channel.send(update as unknown as Uint8Array<ArrayBuffer>)
       }
     }
@@ -412,14 +424,14 @@ class SwarmRtcTransport implements DocTransport {
     channel.addEventListener('close', () => {
       this.deps.doc.off('update', forwardUpdate)
       this.swarmRtcPeers.delete(peerAddress)
-      console.log(`${TAG} channel CLOSED with ${peerAddress.slice(0, 8)}…`)
+      this.logger.debug(`${TAG} channel CLOSED with ${peerAddress.slice(0, 8)}…`)
     })
   }
 
   private waitForIceGatheringComplete(pc: RTCPeerConnection, timeoutMs = 5000): Promise<void> {
     return new Promise(resolve => {
       if (pc.iceGatheringState === 'complete') {
-        console.log(`${TAG} ICE already complete`)
+        this.logger.debug(`${TAG} ICE already complete`)
         resolve()
 
         return
@@ -427,14 +439,14 @@ class SwarmRtcTransport implements DocTransport {
 
       const onStateChange = () => {
         if (pc.iceGatheringState === 'complete') {
-          console.log(`${TAG} ICE gathering complete (event)`)
+          this.logger.debug(`${TAG} ICE gathering complete (event)`)
           resolve()
         }
       }
 
       pc.addEventListener('icegatheringstatechange', onStateChange)
       setTimeout(() => {
-        console.log(`${TAG} ICE gathering timed out after ${timeoutMs}ms, state=${pc.iceGatheringState}`)
+        this.logger.debug(`${TAG} ICE gathering timed out after ${timeoutMs}ms, state=${pc.iceGatheringState}`)
         resolve()
       }, timeoutMs)
     })
diff --git a/src/lib/notification/swarmSignal.ts b/src/lib/notification/swarmSignal.ts
index 631be3b..ac12db1 100644
--- a/src/lib/notification/swarmSignal.ts
+++ b/src/lib/notification/swarmSignal.ts
@@ -71,13 +71,14 @@ export class SwarmSignal {
    */
   // eslint-disable-next-line require-await
   async writeRecord(record: SignalRecord): Promise<void> {
-    console.log(
-      `${TAG} writeRecord called — type=${record.type} to=${record.toAddress.slice(0, 8)}… sessionId=${record.sessionId.slice(0, 8)} ts=${record.timestamp}`,
-    )
     this.writeQueue = this.writeQueue.then(async () => {
       const current = await this.readOwn()
       const filtered = current.records.filter(r => !(r.type === record.type && r.toAddress === record.toAddress))
       await this.writePayload({ records: [...filtered, record] })
+
+      console.debug(
+        `${TAG} writePayload — type=${record.type} to=${record.toAddress.slice(0, 8)}… sessionId=${record.sessionId.slice(0, 8)} ts=${record.timestamp}`,
+      )
     })
 
     return this.writeQueue
@@ -89,14 +90,16 @@ export class SwarmSignal {
    *  Enqueued so it never runs concurrently with writeRecord. */
   // eslint-disable-next-line require-await
   async clearOwn(): Promise<void> {
-    console.log(`${TAG} clearOwn: starting`)
     this.writeQueue = this.writeQueue.then(async () => {
       const current = await this.readOwn()
 
-      if (current.records.length === 0) return
+      if (current.records.length === 0) {
+        return
+      }
 
       await this.writePayload({ records: [] })
-      console.log(`${TAG} clearOwn: cleared ${current.records.length} stale record(s)`)
+
+      console.debug(`${TAG} clearOwn: cleared ${current.records.length} stale record(s)`)
     })
 
     return this.writeQueue
@@ -131,7 +134,7 @@ export class SwarmSignal {
         deferred: false,
       })
       this.currentIndex = nextIndex
-      console.log(`${TAG} writePayload ✓ index: ${nextIndex}`)
+      console.debug(`${TAG} writePayload ✓ index: ${nextIndex}`)
     } catch (err) {
       this.errorHandler.handleError(err, `${TAG}.writePayload`)
     }
diff --git a/src/lib/notification/wakuTransport.ts b/src/lib/notification/wakuTransport.ts
index 30678d5..4bbdf87 100644
--- a/src/lib/notification/wakuTransport.ts
+++ b/src/lib/notification/wakuTransport.ts
@@ -13,6 +13,7 @@ import { DOC_EVENTS } from '../doc/events'
 import type { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/docTransport'
 import type { NotificationHandler, NotificationPayload } from '../interfaces/notification'
 import { ErrorHandler } from '../utils/error'
+import { Logger } from '../utils/logger'
 
 const TAG = 'WakuTransport'
 
@@ -22,6 +23,7 @@ function contentTopicFor(topic: string): string {
 
 class WakuDocTransport implements DocTransport {
   private errorHandler = ErrorHandler.getInstance()
+  private logger = Logger.getInstance()
   private node: LightNode | null = null
   private stopped = false
 
@@ -91,7 +93,7 @@ class WakuDocTransport implements DocTransport {
     }
 
     this.node = node
-    console.log(`${TAG} node connected`)
+    this.logger.log(`${TAG} node connected`)
     this.deps.emitter.emit(DOC_EVENTS.PEERS_CONNECTED, true)
 
     if (this.pendingSubscription) {
@@ -152,18 +154,24 @@ class WakuDocTransport implements DocTransport {
     this.node.filter
       .subscribe([decoder], callback)
       .then(ok => {
-        console.log(`${TAG} subscribed to ${contentTopic} ok=${ok}`)
+        this.logger.log(`${TAG} subscribed to ${contentTopic} ok=${ok}`)
       })
       .catch(err => this.errorHandler.handleError(err, `${TAG}.subscribe`))
   }
 
   private async sendPayload(payload: NotificationPayload): Promise<void> {
-    if (!this.node || !this.encoder) return
+    if (!this.node || !this.encoder) {
+      return
+    }
 
     const bytes = new TextEncoder().encode(JSON.stringify(payload))
-    const result = await this.node.lightPush.send(this.encoder, { payload: bytes })
 
-    console.log(`${TAG} sent successes=${result.successes.length} failures=${result.failures.length}`)
+    try {
+      const result = await this.node.lightPush.send(this.encoder, { payload: bytes })
+      this.logger.debug(`${TAG} send successes=${result.successes.length} failures=${result.failures.length}`)
+    } catch (err: unknown) {
+      this.logger.error(`${TAG} unknown send error=${err}`)
+    }
   }
 }
 
diff --git a/src/lib/notification/yWebrtcTransport.ts b/src/lib/notification/yWebrtcTransport.ts
index c686f0a..98a639c 100644
--- a/src/lib/notification/yWebrtcTransport.ts
+++ b/src/lib/notification/yWebrtcTransport.ts
@@ -3,10 +3,12 @@ import { WebrtcProvider } from 'y-webrtc'
 import { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/docTransport'
 import type { NotificationHandler, NotificationPayload } from '../interfaces/notification'
 import { remove0x } from '../utils/common'
+import { Logger } from '../utils/logger'
 
 const TAG = 'YWebrtcTransport'
 
 class YWebrtcTransport implements DocTransport {
+  private logger = Logger.getInstance()
   private provider: WebrtcProvider | null = null
 
   constructor(
@@ -37,14 +39,14 @@ class YWebrtcTransport implements DocTransport {
         const address = userState?.address ? remove0x(userState.address.toLowerCase()) : null
 
         if (!isSelf && address && address !== this.deps.ownAddress && !this.deps.members.has(address)) {
-          console.log(`${TAG} awareness: new peer ${address.slice(0, 8)}…`)
+          this.logger.log(`${TAG} awareness: new peer ${address.slice(0, 8)}…`)
           // TODO: use username
           this.deps.onPeerDiscovered(address, 'unknown')
         }
       }
     })
 
-    console.log(`${TAG} started, room=${room}, signalingUrl=${this.signalingUrl}`)
+    this.logger.log(`${TAG} started, room=${room}, signalingUrl=${this.signalingUrl}`)
   }
 
   stop(): void {
diff --git a/src/lib/utils/constants.ts b/src/lib/utils/constants.ts
index efc01ba..bb33fa9 100644
--- a/src/lib/utils/constants.ts
+++ b/src/lib/utils/constants.ts
@@ -13,7 +13,5 @@ export const MEMBERS_FEED_SUFFIX = '_members'
 export const NOTIFY_FEED_SUFFIX = '_notify'
 /** Feed ID suffix for per-user WebRTC signaling feeds: `<topic>_signal`. */
 export const SIGNAL_FEED_SUFFIX = '_signal'
-/** Sentinel `feedIndex` value used in `NotificationPayload` to signal a peer join event. */
-export const JOIN_FEED_INDEX = -1n
 /** Fallback STUN server URL used alongside the primary STUN URL in `SwarmRtcTransport`. */
 export const FALLBACK_ICE_SERVER_URL = 'stun:stun.cloudflare.com:3478'

From 2c7a09642ab571a12d1016eb9e4f197a99b7cd39 Mon Sep 17 00:00:00 2001
From: Balint Ujvari <balint.ujvari@solarpunk.buzz>
Date: Tue, 12 May 2026 23:16:38 +0200
Subject: [PATCH 2/2] refactor: interfaces, logs and docs

---
 src/app/components/DocEditor/DocEditor.tsx    |  74 +++--------
 .../components/SessionView/SessionView.tsx    |   2 +-
 src/app/hooks/useSwarmDoc.tsx                 |   5 +-
 src/app/main.tsx                              |   4 +-
 src/app/pages/{TestPage.tsx => App.tsx}       |   4 +-
 src/app/utils/peerColor.ts                    |   7 --
 src/app/utils/peers.ts                        |  59 +++++++++
 src/lib/doc/doc.ts                            | 116 +++++-------------
 src/lib/doc/events.ts                         |   9 --
 src/lib/doc/members.ts                        |  54 ++------
 src/lib/index.ts                              |   9 +-
 src/lib/interfaces/doc.ts                     |  99 +++++++++++++++
 src/lib/interfaces/docTransport.ts            |  79 ------------
 src/lib/interfaces/index.ts                   |   3 +-
 src/lib/interfaces/members.ts                 |  38 ++++++
 src/lib/interfaces/notification.ts            |  46 ++-----
 src/lib/interfaces/settings.ts                |   9 +-
 src/lib/interfaces/signal.ts                  |  20 +++
 src/lib/notification/swarmPubSubTransport.ts  |  31 +++--
 src/lib/notification/swarmRtcTransport.ts     |  40 +++---
 src/lib/notification/swarmSignal.ts           |  39 ++----
 src/lib/notification/wakuTransport.ts         |  22 ++--
 src/lib/notification/yWebrtcTransport.ts      |  26 ++--
 src/lib/utils/common.ts                       |   6 -
 src/lib/utils/constants.ts                    |   2 -
 src/lib/utils/eventEmitter.ts                 |   1 -
 26 files changed, 357 insertions(+), 447 deletions(-)
 rename src/app/pages/{TestPage.tsx => App.tsx} (97%)
 delete mode 100644 src/app/utils/peerColor.ts
 create mode 100644 src/app/utils/peers.ts
 create mode 100644 src/lib/interfaces/doc.ts
 delete mode 100644 src/lib/interfaces/docTransport.ts
 create mode 100644 src/lib/interfaces/members.ts

diff --git a/src/app/components/DocEditor/DocEditor.tsx b/src/app/components/DocEditor/DocEditor.tsx
index ce46738..9755f94 100644
--- a/src/app/components/DocEditor/DocEditor.tsx
+++ b/src/app/components/DocEditor/DocEditor.tsx
@@ -2,64 +2,10 @@ import React, { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import * as Y from 'yjs'
 
 import { AwarenessState } from '../../hooks/useSwarmDoc'
-import { colorForAddress } from '../../utils/peerColor'
+import { colorForAddress, getCaretXY } from '../../utils/peers'
 
 import './DocEditor.scss'
 
-// Mirror-div technique: measure pixel coordinates of a character offset in a textarea.
-// Returns coordinates relative to the textarea's top-left padding origin.
-function getCaretXY(el: HTMLTextAreaElement, position: number): { top: number; left: number } {
-  const style = window.getComputedStyle(el)
-  const div = document.createElement('div')
-
-  const props = [
-    'boxSizing',
-    'width',
-    'paddingTop',
-    'paddingRight',
-    'paddingBottom',
-    'paddingLeft',
-    'borderTopWidth',
-    'borderRightWidth',
-    'borderBottomWidth',
-    'borderLeftWidth',
-    'fontFamily',
-    'fontSize',
-    'fontWeight',
-    'fontStyle',
-    'fontVariant',
-    'lineHeight',
-    'letterSpacing',
-    'wordSpacing',
-    'textTransform',
-    'textIndent',
-    'whiteSpace',
-    'wordBreak',
-    'wordWrap',
-    'tabSize',
-  ] as const
-
-  div.style.position = 'absolute'
-  div.style.visibility = 'hidden'
-  div.style.top = '-9999px'
-  div.style.left = '-9999px'
-  div.style.overflow = 'hidden'
-  props.forEach(p => {
-    div.style[p as never] = style[p as never]
-  })
-
-  const text = el.value.slice(0, position)
-  div.textContent = text || ' '
-  const span = document.createElement('span')
-  span.textContent = el.value[position] ?? ' '
-  div.appendChild(span)
-  document.body.appendChild(div)
-  const coords = { top: span.offsetTop, left: span.offsetLeft }
-  document.body.removeChild(div)
-
-  return coords
-}
-
 function commonPrefixLen(a: string, b: string): number {
   let i = 0
   while (i < a.length && i < b.length && a[i] === b[i]) i++
@@ -114,12 +60,17 @@ export const DocEditor: React.FC<DocEditorProps> = ({ doc, disabled = false, awa
   const [badges, setBadges] = useState<CursorBadge[]>([])
 
   useEffect(() => {
-    if (!doc) return
+    if (!doc) {
+      return
+    }
+
     const yText = doc.getText('content')
     yTextRef.current = yText
     const initial = yText.toString()
     prevContentRef.current = initial
+
     setContent(initial)
+
     const observer = () => {
       const text = yText.toString()
       prevContentRef.current = text
@@ -130,7 +81,6 @@ export const DocEditor: React.FC<DocEditorProps> = ({ doc, disabled = false, awa
     return () => yText.unobserve(observer)
   }, [doc])
 
-  // Recompute badge positions whenever awareness or content changes
   useLayoutEffect(() => {
     const el = textareaRef.current
 
@@ -165,12 +115,18 @@ export const DocEditor: React.FC<DocEditorProps> = ({ doc, disabled = false, awa
   const reportCursor = () => {
     const el = textareaRef.current
 
-    if (!el || !onCursorChange) return
+    if (!el || !onCursorChange) {
+      return
+    }
+
     onCursorChange({ anchor: el.selectionStart, head: el.selectionEnd })
   }
 
   const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-    if (!yTextRef.current || !doc) return
+    if (!yTextRef.current || !doc) {
+      return
+    }
+
     const newValue = e.target.value
     const oldValue = prevContentRef.current
     prevContentRef.current = newValue
diff --git a/src/app/components/SessionView/SessionView.tsx b/src/app/components/SessionView/SessionView.tsx
index 4587ab2..18c3f81 100644
--- a/src/app/components/SessionView/SessionView.tsx
+++ b/src/app/components/SessionView/SessionView.tsx
@@ -19,7 +19,7 @@ import {
   MUTABLE_STAMP_KEY,
   TOPIC_KEY,
 } from '../../utils/constants'
-import { colorForAddress } from '../../utils/peerColor'
+import { colorForAddress } from '../../utils/peers'
 import { Session, Transport, TRANSPORT_LABELS } from '../../utils/types'
 import { DocEditor } from '../DocEditor/DocEditor'
 
diff --git a/src/app/hooks/useSwarmDoc.tsx b/src/app/hooks/useSwarmDoc.tsx
index 2079f5a..6571725 100644
--- a/src/app/hooks/useSwarmDoc.tsx
+++ b/src/app/hooks/useSwarmDoc.tsx
@@ -1,7 +1,6 @@
-import { DOC_EVENTS, DocSettings, SwarmDoc } from 'lib'
+import { DOC_EVENTS, DocSettings, ISwarmDoc, SwarmDoc } from 'lib'
 import { useEffect, useRef, useState } from 'react'
 import * as Y from 'yjs'
-
 export interface AwarenessState {
   address: string
   username: string
@@ -20,7 +19,7 @@ export interface SwarmDocContext {
 }
 
 export const useSwarmDoc = ({ user, infra }: DocSettings): SwarmDocContext => {
-  const docRef = useRef<SwarmDoc | null>(null)
+  const docRef = useRef<ISwarmDoc | null>(null)
   const [doc, setDoc] = useState<Y.Doc | null>(null)
   const [{ error, members, connected }, setStatus] = useState<{
     error: Error | null
diff --git a/src/app/main.tsx b/src/app/main.tsx
index 8365939..23ff535 100644
--- a/src/app/main.tsx
+++ b/src/app/main.tsx
@@ -1,12 +1,12 @@
 import React from 'react'
 import { createRoot } from 'react-dom/client'
 
-import TestPage from './pages/TestPage'
+import App from './pages/App'
 
 // TODO: react strict mode closes the WS connection
 const root = createRoot(document.getElementById('root') as HTMLElement)
 root.render(
   // <React.StrictMode>
-  <TestPage />,
+  <App />,
   // </React.StrictMode>,
 )
diff --git a/src/app/pages/TestPage.tsx b/src/app/pages/App.tsx
similarity index 97%
rename from src/app/pages/TestPage.tsx
rename to src/app/pages/App.tsx
index 76355ac..4d9d140 100644
--- a/src/app/pages/TestPage.tsx
+++ b/src/app/pages/App.tsx
@@ -6,7 +6,7 @@ import { useSession } from '../hooks/useSession'
 import { DISABLE_UNTIL_CONNECTED_KEY, TOPIC_KEY, TRANSPORT_KEY } from '../utils/constants'
 import { loadBeeUrl, loadDisableUntilConnected, loadMutableStamp, loadTopic, loadUsername } from '../utils/localStorage'
 
-const TestPage: React.FC = () => {
+const App: React.FC = () => {
   const { session, login, logout } = useSession()
 
   const docIdParam = typeof window !== 'undefined' ? new URLSearchParams(window.location.search).get('doc') : null
@@ -71,4 +71,4 @@ const TestPage: React.FC = () => {
   )
 }
 
-export default TestPage
+export default App
diff --git a/src/app/utils/peerColor.ts b/src/app/utils/peerColor.ts
deleted file mode 100644
index 139335b..0000000
--- a/src/app/utils/peerColor.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-const CURSOR_COLORS = ['#e63946', '#2a9d8f', '#e9c46a', '#f4a261', '#a8dadc', '#457b9d', '#c77dff', '#06d6a0']
-
-export function colorForAddress(address: string): string {
-  const index = parseInt(address.slice(0, 8), 16) % CURSOR_COLORS.length
-
-  return CURSOR_COLORS[index]
-}
diff --git a/src/app/utils/peers.ts b/src/app/utils/peers.ts
new file mode 100644
index 0000000..0346fad
--- /dev/null
+++ b/src/app/utils/peers.ts
@@ -0,0 +1,59 @@
+export function getCaretXY(el: HTMLTextAreaElement, position: number): { top: number; left: number } {
+  const style = window.getComputedStyle(el)
+  const div = document.createElement('div')
+
+  const props = [
+    'boxSizing',
+    'width',
+    'paddingTop',
+    'paddingRight',
+    'paddingBottom',
+    'paddingLeft',
+    'borderTopWidth',
+    'borderRightWidth',
+    'borderBottomWidth',
+    'borderLeftWidth',
+    'fontFamily',
+    'fontSize',
+    'fontWeight',
+    'fontStyle',
+    'fontVariant',
+    'lineHeight',
+    'letterSpacing',
+    'wordSpacing',
+    'textTransform',
+    'textIndent',
+    'whiteSpace',
+    'wordBreak',
+    'wordWrap',
+    'tabSize',
+  ] as const
+
+  div.style.position = 'absolute'
+  div.style.visibility = 'hidden'
+  div.style.top = '-9999px'
+  div.style.left = '-9999px'
+  div.style.overflow = 'hidden'
+  props.forEach(p => {
+    div.style[p as never] = style[p as never]
+  })
+
+  const text = el.value.slice(0, position)
+  div.textContent = text || ' '
+  const span = document.createElement('span')
+  span.textContent = el.value[position] ?? ' '
+  div.appendChild(span)
+  document.body.appendChild(div)
+  const coords = { top: span.offsetTop, left: span.offsetLeft }
+  document.body.removeChild(div)
+
+  return coords
+}
+
+const CURSOR_COLORS = ['#e63946', '#2a9d8f', '#e9c46a', '#f4a261', '#a8dadc', '#457b9d', '#c77dff', '#06d6a0']
+
+export function colorForAddress(address: string): string {
+  const index = parseInt(address.slice(0, 8), 16) % CURSOR_COLORS.length
+
+  return CURSOR_COLORS[index]
+}
diff --git a/src/lib/doc/doc.ts b/src/lib/doc/doc.ts
index b72c1c6..9b405a4 100644
--- a/src/lib/doc/doc.ts
+++ b/src/lib/doc/doc.ts
@@ -8,12 +8,13 @@ import {
 } from '@solarpunkltd/comment-system'
 import * as Y from 'yjs'
 
-import { DocSettings, DocTransport, NotificationHandler, NotificationPayload } from '../interfaces'
+import { DocSettings, DocTransport, IMembers, ISwarmDoc, NotificationHandler, NotificationPayload } from '../interfaces'
 import { validateStamps } from '../utils/bee'
 import { decode, encode, indexStrToBigint, remove0x, retryAwaitableAsync, uuidV4 } from '../utils/common'
 import { API_VERSION, DOC_FEED_SUFFIX, PLACEHOLDER_STAMP } from '../utils/constants'
 import { ErrorHandler } from '../utils/error'
 import { EventEmitter } from '../utils/eventEmitter'
+import { Logger } from '../utils/logger'
 
 import { DOC_EVENTS } from './events'
 import { Members } from './members'
@@ -23,26 +24,8 @@ const DEBOUNCE_MS = 500
 const DEFAULT_MEMBER_LIST_POLL_INTERVAL_MS = 5000
 const MIN_TTL_WARN_DAYS = 2
 
-/**
- * Collaborative Yjs document backed by Swarm persistent storage.
- *
- * Each peer writes full Yjs state snapshots to their own per-user Swarm feed and
- * broadcasts incremental deltas to online peers via the configured `DocTransport`.
- * On startup, snapshots from all known peers are fetched and merged, so late-joining
- * peers converge to the same state without any central server.
- *
- * Lifecycle:
- * ```ts
- * const swarmDoc = new SwarmDoc(settings)
- * swarmDoc.start()                    // begins transport, snapshot fetch, member poll
- * // ... use swarmDoc.doc (Y.Doc) ...
- * swarmDoc.stop()                     // tears down transport and timers
- * ```
- */
-export class SwarmDoc {
-  /** The underlying Yjs document. Bind editors directly to this instance. */
+export class SwarmDoc implements ISwarmDoc {
   public readonly doc: Y.Doc
-
   private errorHandler = ErrorHandler.getInstance()
   private emitter: EventEmitter
   private signer: PrivateKey
@@ -54,7 +37,7 @@ export class SwarmDoc {
   private transport: DocTransport
   private beeApiUrl: string
   private mutableStampId: string
-  private members: Members
+  private members: IMembers
 
   private pendingUpdates: Uint8Array[] = []
   private debounceTimer: ReturnType<typeof setTimeout> | null = null
@@ -63,6 +46,7 @@ export class SwarmDoc {
   private memberListPollTimer: ReturnType<typeof setInterval> | null = null
   private localCursor: { anchor: number; head: number } | null = null
   private cursorTimer: ReturnType<typeof setInterval> | null = null
+  private readonly logger = Logger.getInstance()
 
   constructor(settings: DocSettings) {
     this.doc = new Y.Doc()
@@ -106,7 +90,6 @@ export class SwarmDoc {
     }
   }
 
-  // Derive comment-system options for own doc feed
   private ownFeedOptions(): Options {
     return {
       identifier: Topic.fromString(this.docFeedId + this.ownAddress).toString(),
@@ -117,7 +100,6 @@ export class SwarmDoc {
     }
   }
 
-  // Derive comment-system options for reading a peer's doc feed
   private memberFeedOptions(address: string): Options {
     return {
       identifier: Topic.fromString(this.docFeedId + address).toString(),
@@ -127,24 +109,18 @@ export class SwarmDoc {
     }
   }
 
-  // Register a peer address so we can read their doc feed. No-op if already registered.
   private registerMember(address: string, username: string): void {
     if (!this.members.register(address, username)) {
       return
     }
 
     this.transport.connectToPeer(address)
-    console.debug(`${TAG} registerMember: ${address.slice(0, 8)}…`)
+    this.logger.debug(`${TAG} registerMember: ${address.slice(0, 8)}…`)
   }
 
-  /**
-   * Starts the transport, subscribes to the doc topic, fetches peer snapshots,
-   * and begins the member-list poll. Call once after constructing `SwarmDoc`.
-   */
   public start(): void {
     this.transport.start()
 
-    // Collect incremental Yjs updates; debounce into a single publish.
     this.doc.on('update', (update: Uint8Array, origin: unknown) => {
       if (this.isRemoteOrigin(origin)) {
         return
@@ -170,22 +146,14 @@ export class SwarmDoc {
     this.startCursorBroadcast()
   }
 
-  /**
-   * Updates the local cursor position in the shared `Y.Text` and schedules a broadcast.
-   * Call this from the editor's selection-change handler.
-   *
-   * @param cursor Character index offsets `{ anchor, head }`, or `null` to clear.
-   */
   public updateCursor(cursor: { anchor: number; head: number } | null): void {
     this.localCursor = cursor
   }
 
-  // Returns true for any origin that should not trigger a Swarm publish or RTC forward.
   private isRemoteOrigin(origin: unknown): boolean {
     return origin === 'remote' || (this.transport.isRemoteOrigin(origin) ?? false)
   }
 
-  /** Stops the transport, clears all timers, and destroys the Yjs document. */
   public stop(): void {
     if (this.debounceTimer) clearTimeout(this.debounceTimer)
 
@@ -205,7 +173,6 @@ export class SwarmDoc {
     this.doc.destroy()
   }
 
-  /** Returns the event emitter. Subscribe to `DOC_EVENTS` constants for doc lifecycle events. */
   public getEmitter(): EventEmitter {
     return this.emitter
   }
@@ -213,7 +180,6 @@ export class SwarmDoc {
   private applyYjsBytes(b64: string, label: string): void {
     try {
       const bytes = decode(b64)
-      console.log(`${TAG} applyYjsBytes [${label}] bytes: ${bytes.length}`)
       Y.applyUpdate(this.doc, bytes, 'remote')
       this.emitter.emit(DOC_EVENTS.DOC_UPDATED, this.doc)
     } catch (err) {
@@ -228,8 +194,6 @@ export class SwarmDoc {
       return
     }
 
-    // Drain the pending queue atomically — snapshot is always full state,
-    // so accumulated updates only affect the delta sent to online peers.
     const allUpdates = [...capturedUpdates, ...this.pendingUpdates]
     this.pendingUpdates = []
     this.publishInFlight = true
@@ -239,11 +203,10 @@ export class SwarmDoc {
       const delta = encode(Y.mergeUpdates(allUpdates))
 
       const nextIndex = this.ownIndex === -1n ? 0n : this.ownIndex + 1n
-      console.log(
+      this.logger.debug(
         `${TAG} publishSnapshot → index: ${nextIndex}, snapshot: ${(snapshot.length * 0.75) | 0}B, delta: ${(delta.length * 0.75) | 0}B`,
       )
 
-      // TODO: sign messages
       const messageObj: MessageData = {
         id: uuidV4(),
         username: this.username,
@@ -258,7 +221,6 @@ export class SwarmDoc {
 
       await writeDoc(messageObj, FeedIndex.fromBigInt(nextIndex), this.ownFeedOptions())
       this.ownIndex = nextIndex
-      console.log(`${TAG} publishSnapshot ✓ index: ${this.ownIndex}`)
 
       const deltaBytes = decode(delta)
       const sig = this.signer.sign(deltaBytes).toHex()
@@ -279,7 +241,6 @@ export class SwarmDoc {
     } finally {
       this.publishInFlight = false
 
-      // If more updates arrived while we were publishing, flush them
       if (this.pendingUpdates.length > 0) {
         const next = [...this.pendingUpdates]
         this.pendingUpdates = []
@@ -289,10 +250,9 @@ export class SwarmDoc {
   }
 
   private async init(): Promise<void> {
-    console.log(`${TAG} init: starting`)
     try {
       await validateStamps(this.beeApiUrl, this.mutableStampId, MIN_TTL_WARN_DAYS, true, msg => {
-        console.warn(`${TAG} ${msg}`)
+        this.logger.warn(`${TAG} ${msg}`)
         this.emitter.emit(DOC_EVENTS.DOC_ERROR, new Error(msg))
       })
     } catch (err) {
@@ -302,37 +262,30 @@ export class SwarmDoc {
       return
     }
     await Promise.allSettled([this.initOwnIndex(), this.initMemberList()])
-    console.log(`${TAG} init: done — ownIndex: ${this.ownIndex}`)
+    this.logger.debug(`${TAG} init: done — ownIndex: ${this.ownIndex}`)
 
-    // No peers at init time — editor is immediately usable, no WebRTC handshake needed
     if (this.members.all().size === 0) {
       this.emitter.emit(DOC_EVENTS.PEERS_CONNECTED, true)
     }
   }
 
   private async initOwnIndex(): Promise<void> {
-    console.log(`${TAG} initOwnIndex: reading own feed`)
     const comment = await retryAwaitableAsync(() => readDoc(undefined, this.ownFeedOptions()), 5, 500)
 
     if (!comment) {
-      console.log(`${TAG} initOwnIndex: no previous writes, starting fresh`)
-
       return
     }
 
     const parsedIx = indexStrToBigint(comment.index)
-    console.log(`${TAG} initOwnIndex: latest index on Swarm = ${parsedIx ?? 'none'}`)
+    this.logger.debug(`${TAG} initOwnIndex: latest index on Swarm = ${parsedIx ?? 'none'}`)
 
     if (parsedIx !== undefined && !FeedIndex.fromBigInt(parsedIx).equals(FeedIndex.MINUS_ONE)) {
       this.ownIndex = parsedIx
-      console.log(`${TAG} initOwnIndex: restoring own snapshot at index ${parsedIx}`)
       this.applyYjsBytes(comment.message, `own idx=${parsedIx}`)
     }
   }
 
   private async initMemberList(): Promise<void> {
-    // Register own address in the consensus memberList, then fetch latest state
-    // from every peer listed there (merged with any statically configured members).
     const membersList = await this.members.add(this.ownAddress, this.username)
     for (const [addr, username] of membersList) {
       if (addr !== this.ownAddress) {
@@ -342,7 +295,6 @@ export class SwarmDoc {
 
     this.emitter.emit(DOC_EVENTS.MEMBERS_UPDATED, this.members.all())
 
-    // Announce presence to online peers
     this.transport.publish({
       type: 'join',
       v: API_VERSION,
@@ -350,19 +302,17 @@ export class SwarmDoc {
       author: this.ownAddress,
       username: this.username,
     })
-    console.log(`${TAG} initMemberList: join notification sent`)
 
     const members = this.members.all()
-    console.log(`${TAG} initMemberList: ${members.size} peer(s) to fetch`)
+    this.logger.debug(`${TAG} initMemberList: ${members.size} peer(s) to fetch`)
     const memberPromises: Promise<void>[] = []
     members.forEach((addr: string, _username: string) => memberPromises.push(this.fetchLatestFromMember(addr)))
     await Promise.allSettled(memberPromises)
   }
 
-  // Dispatcher: routes to the fast (delta) or slow (Swarm fetch) path.
   private async fetchLatestFromMember(memberAddress: string, targetIndex?: bigint, delta?: string): Promise<void> {
     if (!this.members.has(memberAddress)) {
-      console.log(`${TAG} fetchLatestFromMember: ${memberAddress.slice(0, 8)}… not registered, skipping`)
+      this.logger.debug(`${TAG} fetchLatestFromMember: ${memberAddress.slice(0, 8)}… not registered, skipping`)
 
       return
     }
@@ -380,12 +330,11 @@ export class SwarmDoc {
     }
   }
 
-  // Fast path: notification carries the delta — apply directly, no Swarm read needed.
   private applyDelta(memberAddress: string, targetIndex: bigint, delta: string): void {
     const lastKnown = this.members.lastIndex(memberAddress)
 
     if (targetIndex <= lastKnown) {
-      console.log(`${TAG} applyDelta: ${memberAddress.slice(0, 8)}… idx=${targetIndex} already applied`)
+      this.logger.debug(`${TAG} applyDelta: ${memberAddress.slice(0, 8)}… idx=${targetIndex} already applied`)
 
       return
     }
@@ -394,7 +343,6 @@ export class SwarmDoc {
     this.applyYjsBytes(delta, `${memberAddress.slice(0, 8)} delta idx=${targetIndex}`)
   }
 
-  // Slow path: read snapshot from Swarm (init phase, or notification had no delta).
   private async fetchSnapshot(memberAddress: string, targetIndex?: bigint): Promise<void> {
     const lastKnown = this.members.lastIndex(memberAddress)
     const options = this.memberFeedOptions(memberAddress)
@@ -404,11 +352,13 @@ export class SwarmDoc {
     if (targetIndex !== undefined) {
       if (targetIndex <= lastKnown) return
 
-      console.log(`${TAG} fetchSnapshot: ${memberAddress.slice(0, 8)}… waiting for idx=${targetIndex} on Swarm`)
+      this.logger.debug(`${TAG} fetchSnapshot: ${memberAddress.slice(0, 8)}… waiting for idx=${targetIndex} on Swarm`)
       comment = await retryAwaitableAsync(() => readDoc(FeedIndex.fromBigInt(targetIndex), options), 5, 500)
 
       if (!comment) {
-        console.log(`${TAG} fetchSnapshot: ${memberAddress.slice(0, 8)}… idx=${targetIndex} unavailable after retries`)
+        this.logger.warn(
+          `${TAG} fetchSnapshot: ${memberAddress.slice(0, 8)}… idx=${targetIndex} unavailable after retries`,
+        )
 
         return
       }
@@ -417,7 +367,7 @@ export class SwarmDoc {
     } else {
       comment = await retryAwaitableAsync(() => readDoc(undefined, options), 3, 500)
       const parsedIx = indexStrToBigint(comment?.index)
-      console.log(
+      this.logger.debug(
         `${TAG} fetchSnapshot: ${memberAddress.slice(0, 8)}… latestOnSwarm=${parsedIx ?? 'none'} lastKnown=${lastKnown}`,
       )
 
@@ -430,23 +380,16 @@ export class SwarmDoc {
     this.applyYjsBytes(comment.message, `${memberAddress.slice(0, 8)} snapshot idx=${targetIx}`)
   }
 
-  /**
-   * Reads the Swarm consensus member list and registers any newly discovered peers.
-   * Call this to proactively discover peers without waiting for the periodic poll.
-   */
   public async refreshMemberList(): Promise<void> {
     try {
       const members = await this.members.read()
 
-      console.log(`${TAG} refreshMemberList members: `, members)
-
       if (!members || members.size === 0 || Object.keys(members).length === 0) {
-        console.log(`${TAG} refreshMemberList: empty member list`)
+        this.logger.debug(`${TAG} refreshMemberList: empty member list`)
 
         return
       }
 
-      console.log(`${TAG} refreshMemberList: got [${Array.from(Object.keys(members)).join(', ')}]`)
       let changed = false
       for (const [addr, username] of members) {
         if (addr !== this.ownAddress && !this.members.has(addr)) {
@@ -458,8 +401,6 @@ export class SwarmDoc {
 
       if (changed) {
         this.emitter.emit(DOC_EVENTS.MEMBERS_UPDATED, this.members.all())
-      } else {
-        console.log(`${TAG} refreshMemberList: no new members`)
       }
     } catch (err) {
       this.errorHandler.handleError(err, `${TAG}.refreshMemberList`)
@@ -486,7 +427,7 @@ export class SwarmDoc {
 
         if (changed) this.emitter.emit(DOC_EVENTS.MEMBERS_UPDATED, this.members.all())
       } catch {
-        // silent — memberList unavailable is not fatal
+        // no-op
       }
     }, DEFAULT_MEMBER_LIST_POLL_INTERVAL_MS)
   }
@@ -496,8 +437,7 @@ export class SwarmDoc {
 
     this.fetchProcessRunning = true
 
-    console.log(`${TAG} subscribing to topic: ${this.docTopic}`)
-    console.log(`${TAG} known members: ${Array.from(Object.keys(this.members.all())).join(', ') || '(none)'}`)
+    this.logger.log(`${TAG} subscribing to topic: ${this.docTopic}`)
 
     const handler: NotificationHandler = (payload: NotificationPayload): void => {
       const author = remove0x(payload.author.toLowerCase())
@@ -505,7 +445,7 @@ export class SwarmDoc {
       if (author === this.ownAddress) return
 
       if (payload.type === 'join') {
-        console.log(`${TAG} notification: join from ${author.slice(0, 8)}…`)
+        this.logger.debug(`${TAG} notification: join from ${author.slice(0, 8)}…`)
         this.registerMember(author, payload.username)
         this.emitter.emit(DOC_EVENTS.MEMBERS_UPDATED, this.members.all())
         this.fetchLatestFromMember(author)
@@ -524,19 +464,19 @@ export class SwarmDoc {
       }
 
       if (payload.type !== 'doc') {
-        console.warn(`${TAG} unknown payload type from ${author.slice(0, 8)}…`)
+        this.logger.warn(`${TAG} unknown payload type from ${author.slice(0, 8)}…`)
 
         return
       }
 
       if (!payload.delta) {
-        console.warn(`${TAG} dropping message from ${author.slice(0, 8)}…, no delta provided`)
+        this.logger.warn(`${TAG} dropping message from ${author.slice(0, 8)}…, no delta provided`)
 
         return
       }
 
       if (!payload.sig) {
-        console.warn(`${TAG} dropping unsigned delta from ${author.slice(0, 8)}…`)
+        this.logger.warn(`${TAG} dropping unsigned delta from ${author.slice(0, 8)}…`)
 
         return
       }
@@ -545,17 +485,17 @@ export class SwarmDoc {
         const valid = new Signature(payload.sig).isValid(decode(payload.delta), author)
 
         if (!valid) {
-          console.warn(`${TAG} dropping delta with invalid signature from ${author.slice(0, 8)}…`)
+          this.logger.warn(`${TAG} dropping delta with invalid signature from ${author.slice(0, 8)}…`)
 
           return
         }
       } catch {
-        console.warn(`${TAG} signature verification error from ${author.slice(0, 8)}… — dropping`)
+        this.logger.warn(`${TAG} signature verification error from ${author.slice(0, 8)}… — dropping`)
 
         return
       }
 
-      console.log(
+      this.logger.debug(
         `${TAG} notification: author=${author.slice(0, 8)}…, feedIndex=${payload.feedIndex}, hasDelta=${Boolean(payload.delta)}`,
       )
       this.fetchLatestFromMember(author, BigInt(payload.feedIndex), payload.delta)
diff --git a/src/lib/doc/events.ts b/src/lib/doc/events.ts
index 3a3f6da..0d0274d 100644
--- a/src/lib/doc/events.ts
+++ b/src/lib/doc/events.ts
@@ -1,14 +1,5 @@
 /**
  * Event names emitted by `SwarmDoc.getEmitter()`.
- *
- * ```ts
- * swarmDoc.getEmitter().on(DOC_EVENTS.DOC_UPDATED, (doc: Y.Doc) => ...)
- * swarmDoc.getEmitter().on(DOC_EVENTS.DOC_ERROR,   (err: Error) => ...)
- * swarmDoc.getEmitter().on(DOC_EVENTS.MEMBERS_UPDATED, (members: Map<string, string>) => ...)
- * swarmDoc.getEmitter().on(DOC_EVENTS.PEERS_CONNECTED, (connected: true) => ...)
- * swarmDoc.getEmitter().on(DOC_EVENTS.AWARENESS_UPDATED,
- *   (update: { address: string; username: string; cursor: { anchor: number; head: number } | null }) => ...)
- * ```
  */
 export const DOC_EVENTS = {
   /** Fired after every remote update is applied to the Yjs doc. Payload: `Y.Doc`. */
diff --git a/src/lib/doc/members.ts b/src/lib/doc/members.ts
index eca0721..15494f1 100644
--- a/src/lib/doc/members.ts
+++ b/src/lib/doc/members.ts
@@ -1,38 +1,25 @@
 import { Bee, FeedIndex, PrivateKey, Topic } from '@ethersphere/bee-js'
 
+import { IMembers } from '../interfaces'
 import { getSigner, isNotFoundError } from '../utils/bee'
 import { remove0x, retryAwaitableAsync } from '../utils/common'
 import { MEMBERS_FEED_SUFFIX, PLACEHOLDER_STAMP } from '../utils/constants'
 import { ErrorHandler } from '../utils/error'
+import { Logger } from '../utils/logger'
 
 const TAG = 'Members'
 
-/**
- * Manages the set of known peers for a collaborative doc session.
- *
- * Two layers of state:
- * - **Local session** — in-memory set of registered peer addresses and their last known feed index.
- * - **Swarm consensus** — append-only feed written by all peers, providing persistent discovery
- *   so late-joining peers can find each other without out-of-band key sharing.
- *
- * The consensus signer is derived deterministically from the room topic,
- * so any peer who knows the topic can read and write the member list.
- * Last-write-wins; simultaneous join conflicts are acceptable.
- */
-export class Members {
+export class Members implements IMembers {
   private readonly bee: Bee
   private readonly signer: PrivateKey
   private readonly topic: Topic
   private readonly address: string
   private readonly stamp: string
   private readonly errorHandler = ErrorHandler.getInstance()
-
-  // Swarm consensus state
+  private readonly logger = Logger.getInstance()
   private currentIndex: bigint = -1n
-
-  // Local session tracking: address - username mapping
-  private readonly members: Map<string, string> = new Map<string, string>()
-  private readonly indices: Map<string, bigint> = new Map<string, bigint>()
+  private readonly members: Map<string, string> = new Map()
+  private readonly indices: Map<string, bigint> = new Map()
 
   constructor(rawTopic: string, beeUrl: string, stamp: string) {
     const memberFeedId = Topic.fromString(rawTopic + MEMBERS_FEED_SUFFIX).toString()
@@ -43,12 +30,6 @@ export class Members {
     this.stamp = stamp || PLACEHOLDER_STAMP
   }
 
-  // ── Local session tracking ────────────────────────────────────────────────
-
-  /**
-   * Adds `address` to the local peer set.
-   * @returns `true` if the address was newly added, `false` if already present.
-   */
   register(address: string, username: string): boolean {
     if (this.members.has(address)) return false
 
@@ -58,32 +39,22 @@ export class Members {
     return true
   }
 
-  /** Returns `true` if `address` is in the local peer set. */
   has(address: string): boolean {
     return this.members.has(address)
   }
 
-  /** Returns a shallow copy of the registered peer map.  */
   all(): ReadonlyMap<string, string> {
     return new Map(this.members)
   }
 
-  /** Returns the last feed index applied from this peer, or -1n if none yet. */
   lastIndex(address: string): bigint {
     return this.indices.get(address) ?? -1n
   }
 
-  /** Records the latest applied Swarm feed index for `address`. */
   setIndex(address: string, index: bigint): void {
     this.indices.set(address, index)
   }
 
-  // ── Swarm consensus feed ──────────────────────────────────────────────────
-
-  /**
-   * Reads the current member list from the Swarm consensus feed.
-   * @returns Map of Ethereum addresses and usernames or null if the feed does not exist yet.
-   */
   async read(): Promise<Map<string, string> | null> {
     try {
       const reader = this.bee.makeFeedReader(this.topic, this.address)
@@ -100,17 +71,12 @@ export class Members {
     }
   }
 
-  /**
-   * Adds `address` to the Swarm consensus member list.
-   * Verifies by reading back the specific index to detect last-write-wins conflicts.
-   * Returns the confirmed list, or the optimistic list if verification times out.
-   */
   async add(address: string, username: string): Promise<Map<string, string>> {
     const normalizedAddress = remove0x(address.toLowerCase())
     const reader = this.bee.makeFeedReader(this.topic, this.address)
 
     // Always read latest — another peer may have added a member since our last write
-    let members: Map<string, string> = new Map<string, string>()
+    let members: Map<string, string> = new Map()
     try {
       const result = await reader.downloadPayload()
 
@@ -125,7 +91,7 @@ export class Members {
     }
 
     if (members.has(normalizedAddress)) {
-      console.debug(`${TAG} add: ${normalizedAddress.slice(0, 8)}… already in list`)
+      this.logger.debug(`${TAG} add: ${normalizedAddress.slice(0, 8)}… already in list`)
 
       return members
     }
@@ -158,11 +124,11 @@ export class Members {
         3,
         500,
       )
-      console.debug(`${TAG} add: verified — ${Array.from(verified.keys()).join(', ')}`)
+      this.logger.debug(`${TAG} add: verified — ${Array.from(verified.keys()).join(', ')}`)
 
       return verified
     } catch {
-      console.debug(`${TAG} add: verify timed out, using optimistic list`)
+      this.logger.debug(`${TAG} add: verify timed out, using optimistic list`)
 
       return members
     }
diff --git a/src/lib/index.ts b/src/lib/index.ts
index aa12c4b..ed7b4f7 100644
--- a/src/lib/index.ts
+++ b/src/lib/index.ts
@@ -12,7 +12,14 @@ export { createSwarmPubSubTransport } from './notification/swarmPubSubTransport'
 export type { DocSettings } from './interfaces'
 export type { NotificationPayload, NotificationHandler, JoinPayload, DocPayload, CursorPayload } from './interfaces'
 export type { SignalRecord, SignalFeedPayload } from './interfaces'
-export type { DocTransport, DocTransportDeps, DocTransportFactory } from './interfaces'
+export type {
+  DocTransport,
+  DocTransportDeps,
+  DocTransportFactory,
+  ISwarmDoc,
+  IMembers,
+  ISwarmSignal,
+} from './interfaces'
 
 export { getSigner, validateStamps } from './utils/bee'
 export { indexStrToBigint, uuidV4 } from './utils/common'
diff --git a/src/lib/interfaces/doc.ts b/src/lib/interfaces/doc.ts
new file mode 100644
index 0000000..f4d9cd4
--- /dev/null
+++ b/src/lib/interfaces/doc.ts
@@ -0,0 +1,99 @@
+import type { PrivateKey } from '@ethersphere/bee-js'
+import * as Y from 'yjs'
+
+import { EventEmitter } from '../utils/eventEmitter'
+
+import type { NotificationHandler, NotificationPayload } from './notification'
+
+/**
+ * Collaborative Yjs document backed by Swarm persistent storage.
+ *
+ * Each peer writes full Yjs state snapshots to their own per-user Swarm feed and
+ * broadcasts incremental deltas to online peers via the configured `DocTransport`.
+ * On startup, snapshots from all known peers are fetched and merged, so late-joining
+ * peers converge to the same state without any central server.
+ *
+ */
+export interface ISwarmDoc {
+  /** The underlying Yjs document. Bind editors directly to this instance. */
+  readonly doc: Y.Doc
+
+  /** Starts the transport, fetches peer snapshots, and begins the member-list poll. Call once after constructing. */
+  start(): void
+
+  /** Stops the transport, clears all timers, and destroys the Yjs document. */
+  stop(): void
+
+  /**
+   * Updates the local cursor position and schedules a broadcast.
+   * Call from the editor's selection-change handler.
+   * @param cursor Character index offsets `{ anchor, head }`, or `null` to clear.
+   */
+  updateCursor(cursor: { anchor: number; head: number } | null): void
+
+  /** Returns the event emitter. Subscribe to `DOC_EVENTS` constants for doc lifecycle events. */
+  getEmitter(): EventEmitter
+
+  /** Reads the Swarm consensus member list and registers any newly discovered peers. */
+  refreshMemberList(): Promise<void>
+}
+
+/**
+ * Transport interface consumed by `SwarmDoc`. Implementations:
+ *   - `createSwarmPubSubTransport` — Swarm GSOC pubsub WebSocket
+ *   - `createSwarmRtcTransport` — WebRTC with Swarm-stored SDP signaling
+ *   - `createYWebrtcTransport` — WebRTC via y-webrtc signaling server
+ *   - `createWakuTransport` — libp2p gossipsub via Waku light node
+ */
+export interface DocTransport {
+  /** Called once by `SwarmDoc.start()`. */
+  start(): void
+  /** Tear down the transport and release all resources. Called by `SwarmDoc.stop()`. */
+  stop(): void
+  /** Begin receiving notifications, invoking `handler` on each message. No-op on WebRTC-only transports. */
+  subscribe(topic: string, handler: NotificationHandler): void
+  /** Publish an outgoing notification. No-op on WebRTC-only transports. */
+  publish(payload: NotificationPayload): void
+  /**
+   * Called when a peer is registered. WebRTC transports use this to initiate connections;
+   * pub/sub transports treat it as a no-op.
+   */
+  connectToPeer(address: string): void
+  /**
+   * Returns `true` if the Yjs update `origin` was applied by this transport.
+   * Prevents re-broadcasting updates that arrived from a remote peer.
+   */
+  isRemoteOrigin(origin: unknown): boolean
+}
+
+/** Dependencies injected into a `DocTransport` by `SwarmDoc` via the factory. */
+export interface DocTransportDeps {
+  /** The shared Yjs document being synchronised. */
+  doc: Y.Doc
+  /** Event emitter for surfacing `DOC_EVENTS` to the application layer. */
+  emitter: { emit(event: string, ...args: unknown[]): void }
+  /** Accessor for the current peer set. */
+  members: {
+    /** Returns all registered peers (address → username). */
+    all(): ReadonlyMap<string, string>
+    /** Returns `true` if `address` is in the registered set. */
+    has(address: string): boolean
+  }
+  /** Ethereum address of the local user (hex, no 0x prefix). */
+  ownAddress: string
+  /** Display name of the local user. */
+  nickname: string
+  /** Called when the transport discovers a peer not yet in the member set. */
+  onPeerDiscovered: (address: string, username: string) => void
+  /** Topic namespace used to derive per-user Swarm feed identifiers. */
+  docFeedId: string
+  /** Bee node HTTP API URL. */
+  beeApiUrl: string
+  /** secp256k1 private key for signing Swarm feed writes. */
+  signer: PrivateKey
+  /** Mutable postage batch ID for snapshot and signal writes. */
+  mutableStampId: string
+}
+
+/** Called once in the `SwarmDoc` constructor with resolved dependencies. Returns the transport instance. */
+export type DocTransportFactory = (deps: DocTransportDeps) => DocTransport
diff --git a/src/lib/interfaces/docTransport.ts b/src/lib/interfaces/docTransport.ts
deleted file mode 100644
index 8f24e00..0000000
--- a/src/lib/interfaces/docTransport.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-import type { PrivateKey } from '@ethersphere/bee-js'
-import * as Y from 'yjs'
-
-import type { NotificationHandler, NotificationPayload } from './notification'
-
-/**
- * Unified transport interface consumed by `SwarmDoc`.
- *
- * Combines notification delivery (subscribe/publish) with peer connection management.
- * Built-in implementations:
- *   - `createSwarmFeedTransport` — polling over Swarm mutable feeds
- *   - `createBroadcastChannelTransport` — same-origin tab broadcast (dev/testing)
- *   - `createYWebrtcTransport` — WebRTC via y-webrtc signaling server
- *   - `createSwarmRtcTransport` — WebRTC with Swarm-stored SDP signaling
- *   - `createWakuTransport` — libp2p gossipsub via Waku light node
- */
-export interface DocTransport {
-  /** Initialise the transport. Called once by `SwarmDoc.start()`. */
-  start(): void
-  /** Tear down the transport and release all resources. Called by `SwarmDoc.stop()`. */
-  stop(): void
-  /** Begin receiving notifications for `topic`, invoking `handler` on each message. */
-  subscribe(topic: string, handler: NotificationHandler): void
-  /** Publish an outgoing notification. No-op on WebRTC-only transports. */
-  publish(payload: NotificationPayload): void
-  /**
-   * Called when a peer is registered. Transports that manage direct connections
-   * (WebRTC) use this to initiate them; others may treat it as a no-op.
-   * @param address Ethereum address of the peer (hex, no 0x prefix).
-   */
-  connectToPeer(address: string): void
-  /**
-   * Returns `true` if the given Yjs update `origin` was applied by this transport.
-   * Prevents re-broadcasting updates that arrived from a remote peer.
-   */
-  isRemoteOrigin(origin: unknown): boolean
-}
-
-/** Dependencies injected into a `DocTransport` by `SwarmDoc` via the factory. */
-export interface DocTransportDeps {
-  /** The shared Yjs document being synchronised. */
-  doc: Y.Doc
-  /** Event emitter for surfacing `DOC_EVENTS` to the application layer. */
-  emitter: { emit(event: string, ...args: unknown[]): void }
-  /** Read-only accessor for the current peer set and per-peer feed index state. */
-  members: {
-    /** Returns all registered peer addresses. */
-    all(): ReadonlyMap<string, string>
-    /** Returns `true` if `address` is in the registered set. */
-    has(address: string): boolean
-    /** Returns the last Swarm feed index applied from `address`, or `-1n` if none. */
-    lastIndex(address: string): bigint
-    /** Records the latest applied feed index for `address`. */
-    setIndex(address: string, index: bigint): void
-  }
-  /** Ethereum address of the local user (hex, no 0x prefix). */
-  ownAddress: string
-  /** Display name of the local user. */
-  nickname: string
-  /**
-   * Called when the transport discovers a peer not yet in the member set.
-   * The transport should invoke this on awareness events or similar peer-discovery signals.
-   */
-  onPeerDiscovered: (address: string, username: string) => void
-  /** Topic namespace used to derive per-user Swarm feed identifiers. Swarm transports only. */
-  docFeedId: string
-  /** Bee node HTTP API URL. Swarm transports only. */
-  beeApiUrl: string
-  /** secp256k1 private key for signing Swarm feed writes. Swarm transports only. */
-  signer: PrivateKey
-  /** Mutable postage batch ID for snapshot and signal writes. Swarm transports only. */
-  mutableStampId: string
-}
-
-/**
- * Factory function signature. Called once in the `SwarmDoc` constructor with
- * fully resolved dependencies. Returns the `DocTransport` instance to use.
- */
-export type DocTransportFactory = (deps: DocTransportDeps) => DocTransport
diff --git a/src/lib/interfaces/index.ts b/src/lib/interfaces/index.ts
index 6ebb4d1..30a2b56 100644
--- a/src/lib/interfaces/index.ts
+++ b/src/lib/interfaces/index.ts
@@ -1,4 +1,5 @@
 export * from './settings'
 export * from './notification'
 export * from './signal'
-export * from './docTransport'
+export * from './doc'
+export * from './members'
diff --git a/src/lib/interfaces/members.ts b/src/lib/interfaces/members.ts
new file mode 100644
index 0000000..96ced18
--- /dev/null
+++ b/src/lib/interfaces/members.ts
@@ -0,0 +1,38 @@
+/**
+ * Manages the set of known peers for a collaborative doc session.
+ *
+ * Two layers of state:
+ * - **Local session** — in-memory set of registered peer addresses and their last known feed index.
+ * - **Swarm consensus** — append-only feed written by all peers, providing persistent discovery
+ *   so late-joining peers can find each other without out-of-band key sharing.
+ *
+ * The consensus signer is derived deterministically from the room topic,
+ * so any peer who knows the topic can read and write the member list.
+ * Last-write-wins; simultaneous join conflicts are acceptable.
+ */
+export interface IMembers {
+  /** Adds `address` to the local peer set. Returns `true` if newly added, `false` if already present. */
+  register(address: string, username: string): boolean
+
+  /** Returns `true` if `address` is in the local peer set. */
+  has(address: string): boolean
+
+  /** Returns a shallow copy of the registered peer map. */
+  all(): ReadonlyMap<string, string>
+
+  /** Returns the last feed index applied from this peer, or `-1n` if none yet. */
+  lastIndex(address: string): bigint
+
+  /** Records the latest applied Swarm feed index for `address`. */
+  setIndex(address: string, index: bigint): void
+
+  /** Reads the current member list from the Swarm consensus feed. Returns `null` if the feed does not exist yet. */
+  read(): Promise<Map<string, string> | null>
+
+  /**
+   * Adds `address` to the Swarm consensus member list.
+   * Reads back the written index to detect last-write-wins conflicts.
+   * Returns the confirmed list, or the optimistic list if verification times out.
+   */
+  add(address: string, username: string): Promise<Map<string, string>>
+}
diff --git a/src/lib/interfaces/notification.ts b/src/lib/interfaces/notification.ts
index aa71f99..2036639 100644
--- a/src/lib/interfaces/notification.ts
+++ b/src/lib/interfaces/notification.ts
@@ -1,6 +1,6 @@
 /** Fields shared by every notification payload variant. */
 interface BasePayload {
-  /** Protocol version string (e.g. `"v1"`). Used to detect incompatible clients. */
+  /** Protocol version string (e.g. `"v1"`). */
   v: string
   /** Swarm feed topic identifier for the collaborative document. */
   topic: string
@@ -10,46 +10,29 @@ interface BasePayload {
   username: string
 }
 
-/**
- * Peer-join announcement. Signals that a new peer has joined the session and
- * that receivers should fetch the peer's latest snapshot from their Swarm feed.
- * Carries no document data.
- */
+/** Peer-join announcement. Receivers fetch the peer's latest snapshot from their Swarm feed. */
 export interface JoinPayload extends BasePayload {
   type: 'join'
 }
 
 /**
- * Incremental document update from a peer. Contains the Swarm doc-feed index
- * written by the author and an optional base64 Yjs delta for fast-path application.
- * The delta MUST be accompanied by a secp256k1 signature; unsigned deltas are dropped.
+ * Incremental document update. The delta MUST be accompanied by a secp256k1 signature;
+ * unsigned or invalid deltas are dropped by receivers.
  */
 export interface DocPayload extends BasePayload {
   type: 'doc'
   /** Swarm doc-feed index written by the author for this update. */
   feedIndex: number
-  /**
-   * Base64-encoded Yjs incremental update for peers already online.
-   * Absent when only a snapshot was written (e.g. retry after a missed delta).
-   */
+  /** Base64-encoded Yjs incremental update for peers already online. */
   delta?: string
-  /**
-   * Hex-encoded secp256k1 signature of the raw delta bytes (before base64 encoding).
-   * Required when `delta` is present. Receivers MUST verify and drop invalid signatures.
-   */
+  /** Hex-encoded secp256k1 signature of the raw delta bytes. Required when `delta` is present. */
   sig?: string
 }
 
-/**
- * Cursor-only awareness update. Sent on a ~500ms timer independent of doc edits.
- * Carries no document data and requires no signature.
- */
+/** Cursor-only awareness update. Sent on a ~500 ms timer, independent of doc edits. */
 export interface CursorPayload extends BasePayload {
   type: 'cursor'
-  /**
-   * Current cursor position in the shared `Y.Text` (character index offsets).
-   * `null` signals the peer has deselected or disconnected.
-   */
+  /** Character index offsets in the shared `Y.Text`. `null` means deselected or disconnected. */
   cursor: { anchor: number; head: number } | null
 }
 
@@ -58,16 +41,3 @@ export type NotificationPayload = JoinPayload | DocPayload | CursorPayload
 
 /** Callback invoked whenever a notification arrives on the subscribed topic. */
 export type NotificationHandler = (payload: NotificationPayload) => void
-
-/**
- * Low-level interface for pluggable notification channels.
- * Used internally by `SwarmFeedNotificationProvider`.
- * Prefer the higher-level `DocTransport` interface for new transports.
- */
-export interface NotificationProvider {
-  subscribe(topic: string, handler: NotificationHandler): void
-  publish(payload: NotificationPayload): void
-  unsubscribe(): void
-  /** Register a peer address so this provider polls their notification feed. */
-  addMember?(address: string): void
-}
diff --git a/src/lib/interfaces/settings.ts b/src/lib/interfaces/settings.ts
index a6f8813..5c54ab5 100644
--- a/src/lib/interfaces/settings.ts
+++ b/src/lib/interfaces/settings.ts
@@ -1,4 +1,4 @@
-import { DocTransportFactory } from './docTransport'
+import { DocTransportFactory } from './doc'
 
 /** Configuration passed to the `SwarmDoc` constructor. */
 export interface DocSettings {
@@ -25,10 +25,9 @@ export interface DocSettings {
     /** Pre-seeded peer Ethereum addresses with usernames. Merged with the Swarm consensus member list at init. */
     members?: Map<string, string>
     /**
-     * Transport factory. Determines how peers exchange notifications and/or sync state.
-     * Use one of the built-in factories:
-     * `createSwarmFeedTransport`, `createYWebrtcTransport`, `createSwarmRtcTransport`,
-     * `createWakuTransport`, `createBroadcastChannelTransport`.
+     * Transport factory. Determines how peers exchange notifications and sync state.
+     * Built-in options: `createSwarmPubSubTransport`, `createSwarmRtcTransport`,
+     * `createYWebrtcTransport`, `createWakuTransport`.
      */
     transport: DocTransportFactory
   }
diff --git a/src/lib/interfaces/signal.ts b/src/lib/interfaces/signal.ts
index a10d10e..e34e197 100644
--- a/src/lib/interfaces/signal.ts
+++ b/src/lib/interfaces/signal.ts
@@ -25,3 +25,23 @@ export interface SignalRecord {
 export interface SignalFeedPayload {
   records: SignalRecord[]
 }
+
+/**
+ * Reads and writes WebRTC signaling records to a per-user Swarm mutable feed.
+ *
+ * Writes are serialised to prevent index conflicts when `clearOwn` and `writeRecord` run concurrently.
+ * Used exclusively by `SwarmRtcTransport`.
+ */
+export interface ISwarmSignal {
+  /** Reads the signal feed for any peer. Returns `null` if the feed doesn't exist or has no new data. */
+  read(peerAddress: string): Promise<SignalFeedPayload | null>
+
+  /**
+   * Appends or replaces a signal record in own feed.
+   * Deduplication key: `type + toAddress` — only one active offer/answer per peer.
+   */
+  writeRecord(record: SignalRecord): Promise<void>
+
+  /** Writes an empty payload to own feed, clearing all records from the previous session. */
+  clearOwn(): Promise<void>
+}
diff --git a/src/lib/notification/swarmPubSubTransport.ts b/src/lib/notification/swarmPubSubTransport.ts
index cd7a7c7..bf599c1 100644
--- a/src/lib/notification/swarmPubSubTransport.ts
+++ b/src/lib/notification/swarmPubSubTransport.ts
@@ -1,7 +1,7 @@
 import { Bee, PubsubMode, PubsubSubscription } from '@ethersphere/bee-js'
 
 import { DOC_EVENTS } from '../doc/events'
-import type { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/docTransport'
+import type { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/doc'
 import type { NotificationHandler, NotificationPayload } from '../interfaces/notification'
 import { ErrorHandler } from '../utils/error'
 import { Logger } from '../utils/logger'
@@ -57,7 +57,9 @@ class SwarmPubSubDocTransport implements DocTransport {
   }
 
   private connect(): void {
-    if (this.stopped || this.isConnecting) return
+    if (this.stopped || this.isConnecting) {
+      return
+    }
 
     this.isConnecting = true
 
@@ -72,14 +74,15 @@ class SwarmPubSubDocTransport implements DocTransport {
           this.deps.emitter.emit(DOC_EVENTS.PEERS_CONNECTED, true)
           this.logger.log(`${TAG} connected, docFeedId=${this.deps.docFeedId}`)
 
-          // Drain buffered publishes now that the WebSocket is open
           const toSend = this.pendingPublishes.splice(0)
           for (const payload of toSend) {
             this.sendPayload(payload).catch(err => this.errorHandler.handleError(err, `${TAG}.sendPayload`))
           }
         },
         onMessage: (message, _sub) => {
-          if (!this.handler) return
+          if (!this.handler) {
+            return
+          }
 
           try {
             const text = new TextDecoder().decode(message.toUint8Array())
@@ -114,7 +117,9 @@ class SwarmPubSubDocTransport implements DocTransport {
   }
 
   private async sendPayload(payload: NotificationPayload): Promise<void> {
-    if (!this.subscription) return
+    if (!this.subscription) {
+      return
+    }
 
     const text = JSON.stringify(payload)
     await this.subscription.send(text)
@@ -122,20 +127,14 @@ class SwarmPubSubDocTransport implements DocTransport {
 }
 
 /**
- * Creates a `DocTransportFactory` using Swarm's GSOC pubsub for real-time notifications.
- *
- * Connects to the local Bee node's pubsub WebSocket endpoint and subscribes to a
- * content topic derived deterministically from the doc's feed ID using
- * `PubsubMode.GSOC_EPHEMERAL` (keccak256 of the topic string → ephemeral key → SOC address).
- * All peers using the same topic string subscribe to the same address, enabling
- * bidirectional push delivery without polling.
+ * Creates a `DocTransportFactory` using Swarm GSOC pubsub for real-time notifications.
  *
- * Connection is established immediately in `start()`. If the WebSocket closes unexpectedly
- * it reconnects automatically after 3 seconds. `subscribe` and `publish` calls made before
- * the connection is ready are buffered and drained on connect.
+ * Subscribes to a content address derived from the doc's feed ID via
+ * `PubsubMode.GSOC_EPHEMERAL` — all peers on the same topic reach the same address.
+ * Reconnects automatically after 10 s if the WebSocket closes unexpectedly.
+ * Publishes buffered during connect are drained on open.
  *
  * @param brokerPeer Multiaddress of the Bee node acting as the GSOC pubsub broker.
- *   Example: `/ip4/1.2.3.4/tcp/1634/p2p/QmXxxx…`
  */
 export function createSwarmPubSubTransport(brokerPeer: string): DocTransportFactory {
   return (deps: DocTransportDeps) => new SwarmPubSubDocTransport(deps, brokerPeer)
diff --git a/src/lib/notification/swarmRtcTransport.ts b/src/lib/notification/swarmRtcTransport.ts
index d458ee1..aa2d9db 100644
--- a/src/lib/notification/swarmRtcTransport.ts
+++ b/src/lib/notification/swarmRtcTransport.ts
@@ -1,8 +1,8 @@
 import * as Y from 'yjs'
 
 import { DOC_EVENTS } from '../doc/events'
-import { SignalRecord, SignalType } from '../interfaces'
-import { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/docTransport'
+import { ISwarmSignal, SignalRecord, SignalType } from '../interfaces'
+import { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/doc'
 import type { NotificationHandler, NotificationPayload } from '../interfaces/notification'
 import { uuidV4 } from '../utils/common'
 import { FALLBACK_ICE_SERVER_URL } from '../utils/constants'
@@ -21,9 +21,11 @@ class SwarmRtcTransport implements DocTransport {
   private errorHandler = ErrorHandler.getInstance()
   private logger = Logger.getInstance()
 
-  private swarmSignal: SwarmSignal
+  private swarmSignal: ISwarmSignal
   private swarmRtcPeers = new Map<string, RTCPeerConnection>()
+  /** sessionId per peer for correlating incoming answers to our outstanding offer. */
   private pendingOfferSessions = new Map<string, string>()
+  /** `"peerAddress:sessionId"` keys already answered — prevents double-answering the same offer. */
   private sentAnswerKeys = new Set<string>()
   private signalPollTimer: ReturnType<typeof setInterval> | null = null
   private signalCheckInFlight = false
@@ -66,7 +68,7 @@ class SwarmRtcTransport implements DocTransport {
     return origin === 'swarm-rtc'
   }
 
-  // Swarm-signaled WebRTC uses data channels for sync — no notification channel needed
+  // Yjs sync runs over data channels — subscribe/publish are unused
   subscribe(_topic: string, _handler: NotificationHandler): void {
     /** no-op */
   }
@@ -74,7 +76,6 @@ class SwarmRtcTransport implements DocTransport {
     /** no-op */
   }
 
-  /** Decides whether to initiate a WebRTC connection to a newly discovered peer. */
   connectToPeer(address: string): void {
     if (this.swarmRtcPeers.has(address)) {
       this.logger.debug(`${TAG} connectToPeer ${address.slice(0, 8)}… skipped — already connected`)
@@ -91,12 +92,11 @@ class SwarmRtcTransport implements DocTransport {
     // Answerers wait — startSignalPoll() will pick up the initiator's offer
   }
 
-  /** Deterministic role: lower address is always the initiator. Prevents duplicate connections. */
+  // Lower address is always the initiator — deterministic assignment prevents both peers from sending offers simultaneously.
   private isInitiatorFor(peerAddress: string): boolean {
     return this.deps.ownAddress < peerAddress
   }
 
-  /** Creates an RTCPeerConnection as the initiator, gathers ICE, publishes offer to signal feed. */
   private async initiateConnectionTo(peerAddress: string): Promise<void> {
     if (this.swarmRtcPeers.has(peerAddress)) {
       return
@@ -183,7 +183,6 @@ class SwarmRtcTransport implements DocTransport {
     this.logger.debug(`${TAG} offer written → ${peerAddress.slice(0, 8)}… sessionId=${sessionId.slice(0, 8)}`)
   }
 
-  /** Receives a peer's offer, creates an answer, publishes it to own signal feed. */
   private async answerPeerOffer(peerAddress: string, offer: SignalRecord): Promise<void> {
     if (this.swarmRtcPeers.has(peerAddress)) return
 
@@ -262,7 +261,6 @@ class SwarmRtcTransport implements DocTransport {
     this.logger.debug(`${TAG} answer written → ${peerAddress.slice(0, 8)}… sessionId=${offer.sessionId.slice(0, 8)}`)
   }
 
-  /** Polls each known peer's signal feed for offers (to answer) and answers (to finalise). */
   private startSignalPoll(): void {
     this.logger.debug(`${TAG} signal poll started (interval=${SIGNAL_POLL_INTERVAL_MS}ms)`)
     this.checkSignals()
@@ -295,11 +293,15 @@ class SwarmRtcTransport implements DocTransport {
   }
 
   private async checkPeerSignals(peerAddress: string): Promise<void> {
-    if (peerAddress === this.deps.ownAddress) return
+    if (peerAddress === this.deps.ownAddress) {
+      return
+    }
 
     const pc = this.swarmRtcPeers.get(peerAddress)
 
-    if (pc?.connectionState === 'connected') return
+    if (pc?.connectionState === 'connected') {
+      return
+    }
 
     const payload = await this.swarmSignal.read(peerAddress)
 
@@ -393,7 +395,6 @@ class SwarmRtcTransport implements DocTransport {
     }
   }
 
-  /** Sets up Yjs sync over an open WebRTC data channel. */
   private setupDataChannel(peerAddress: string, channel: RTCDataChannel): void {
     this.logger.debug(`${TAG} channel OPEN with ${peerAddress.slice(0, 8)}…`)
     this.deps.emitter.emit(DOC_EVENTS.PEERS_CONNECTED, true)
@@ -456,17 +457,14 @@ class SwarmRtcTransport implements DocTransport {
 /**
  * Creates a `DocTransportFactory` using Swarm-signaled WebRTC for peer-to-peer sync.
  *
- * WebRTC SDP offer/answer records are written to and read from each peer's
- * `<topic>_signal` Swarm mutable feed, eliminating the need for a central signaling server.
- * ICE gathering runs to completion before the SDP is written, so candidates are embedded
- * in the SDP itself rather than sent incrementally.
+ * SDP offer/answer records are written to each peer's `_signal` Swarm mutable feed,
+ * eliminating the need for a central signaling server. ICE gathering completes before
+ * the SDP is written, so candidates are embedded rather than sent incrementally.
  *
- * Role assignment is deterministic: the peer with the lower Ethereum address always
- * acts as the WebRTC initiator, preventing duplicate connection attempts.
+ * Role assignment is deterministic: the peer with the lower Ethereum address is always
+ * the initiator, preventing duplicate connections.
  *
- * `subscribe` and `publish` are no-ops: Yjs updates flow over WebRTC data channels.
- * A `NotificationPayload` transport (e.g. `createSwarmFeedTransport`) should be used
- * alongside this to handle join notifications and snapshot hints for offline peers.
+ * `subscribe` and `publish` are no-ops — Yjs updates flow directly over WebRTC data channels.
  *
  * @param stunUrl Primary STUN server URL (e.g. `"stun:stun.l.google.com:19302"`).
  * @param iceServers Optional full ICE server list. Overrides the default STUN pair when provided.
diff --git a/src/lib/notification/swarmSignal.ts b/src/lib/notification/swarmSignal.ts
index ac12db1..328ebe6 100644
--- a/src/lib/notification/swarmSignal.ts
+++ b/src/lib/notification/swarmSignal.ts
@@ -1,22 +1,14 @@
 import { Bee, EthAddress, FeedIndex, PrivateKey, Topic } from '@ethersphere/bee-js'
 
-import { SignalFeedPayload, SignalRecord } from '../interfaces'
+import { ISwarmSignal, SignalFeedPayload, SignalRecord } from '../interfaces'
 import { isNotFoundError } from '../utils/bee'
 import { PLACEHOLDER_STAMP, SIGNAL_FEED_SUFFIX } from '../utils/constants'
 import { ErrorHandler } from '../utils/error'
+import { Logger } from '../utils/logger'
 
 const TAG = 'SwarmSignal'
 
-/**
- * Reads and writes WebRTC signaling records to a per-user Swarm mutable feed.
- *
- * Each peer maintains a single feed index storing a `SignalFeedPayload` (a list of
- * `SignalRecord` objects). Writes are serialised via an internal queue to prevent
- * index conflicts when `clearOwn` and `writeRecord` run concurrently.
- *
- * Used exclusively by `SwarmRtcTransport`.
- */
-export class SwarmSignal {
+export class SwarmSignal implements ISwarmSignal {
   private readonly bee: Bee
   private readonly ownSigner: PrivateKey
   private readonly ownAddress: string
@@ -25,7 +17,7 @@ export class SwarmSignal {
   private currentIndex: bigint = -1n
   private readonly peerLastIndexes: Map<string, bigint> = new Map()
   private readonly errorHandler = ErrorHandler.getInstance()
-  // Ensures clearOwn and writeRecord never run concurrently (prevents double-writes at same index)
+  private readonly logger = Logger.getInstance()
   private writeQueue: Promise<void> = Promise.resolve()
 
   constructor(rawTopic: string, beeUrl: string, ownSigner: PrivateKey, stamp: string) {
@@ -37,10 +29,6 @@ export class SwarmSignal {
     this.stamp = stamp || PLACEHOLDER_STAMP
   }
 
-  // ── Read ──────────────────────────────────────────────────────────────────
-
-  /** Reads the signal feed of any peer. Returns null if the feed doesn't exist yet or has no new data.
-   *  After the first read, uses forward-indexed lookup (lastIndex + 1) to bypass Bee node "latest" cache. */
   async read(peerAddress: string): Promise<SignalFeedPayload | null> {
     const reader = this.bee.makeFeedReader(this.topic, new EthAddress(peerAddress))
     const lastIndex = this.peerLastIndexes.get(peerAddress)
@@ -62,13 +50,6 @@ export class SwarmSignal {
     }
   }
 
-  // ── Write ─────────────────────────────────────────────────────────────────
-
-  /**
-   * Appends (or replaces) a signal record in own feed.
-   * Deduplication key: type + toAddress — only one active offer/answer per peer.
-   * Enqueued so it never runs concurrently with clearOwn.
-   */
   // eslint-disable-next-line require-await
   async writeRecord(record: SignalRecord): Promise<void> {
     this.writeQueue = this.writeQueue.then(async () => {
@@ -76,18 +57,14 @@ export class SwarmSignal {
       const filtered = current.records.filter(r => !(r.type === record.type && r.toAddress === record.toAddress))
       await this.writePayload({ records: [...filtered, record] })
 
-      console.debug(
-        `${TAG} writePayload — type=${record.type} to=${record.toAddress.slice(0, 8)}… sessionId=${record.sessionId.slice(0, 8)} ts=${record.timestamp}`,
+      this.logger.debug(
+        `${TAG} writeRecord type=${record.type} to=${record.toAddress.slice(0, 8)}… sessionId=${record.sessionId.slice(0, 8)}`,
       )
     })
 
     return this.writeQueue
   }
 
-  // ── Internal ──────────────────────────────────────────────────────────────
-
-  /** Writes an empty payload to own feed, removing all stale records from the previous session.
-   *  Enqueued so it never runs concurrently with writeRecord. */
   // eslint-disable-next-line require-await
   async clearOwn(): Promise<void> {
     this.writeQueue = this.writeQueue.then(async () => {
@@ -99,7 +76,7 @@ export class SwarmSignal {
 
       await this.writePayload({ records: [] })
 
-      console.debug(`${TAG} clearOwn: cleared ${current.records.length} stale record(s)`)
+      this.logger.debug(`${TAG} clearOwn: cleared ${current.records.length} stale record(s)`)
     })
 
     return this.writeQueue
@@ -134,7 +111,7 @@ export class SwarmSignal {
         deferred: false,
       })
       this.currentIndex = nextIndex
-      console.debug(`${TAG} writePayload ✓ index: ${nextIndex}`)
+      this.logger.debug(`${TAG} writePayload ✓ index: ${nextIndex}`)
     } catch (err) {
       this.errorHandler.handleError(err, `${TAG}.writePayload`)
     }
diff --git a/src/lib/notification/wakuTransport.ts b/src/lib/notification/wakuTransport.ts
index 4bbdf87..a90ccaf 100644
--- a/src/lib/notification/wakuTransport.ts
+++ b/src/lib/notification/wakuTransport.ts
@@ -10,7 +10,7 @@ import {
 } from '@waku/sdk'
 
 import { DOC_EVENTS } from '../doc/events'
-import type { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/docTransport'
+import type { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/doc'
 import type { NotificationHandler, NotificationPayload } from '../interfaces/notification'
 import { ErrorHandler } from '../utils/error'
 import { Logger } from '../utils/logger'
@@ -26,12 +26,8 @@ class WakuDocTransport implements DocTransport {
   private logger = Logger.getInstance()
   private node: LightNode | null = null
   private stopped = false
-
-  // Buffered until node is ready
   private pendingSubscription: { topic: string; handler: NotificationHandler } | null = null
   private pendingPublishes: NotificationPayload[] = []
-
-  // Set once subscription is established; reused for all sends
   private encoder: ReturnType<typeof createEncoder> | null = null
 
   constructor(
@@ -70,7 +66,7 @@ class WakuDocTransport implements DocTransport {
     }
   }
 
-  // Waku handles peer routing — no per-peer setup needed
+  // Waku handles peer routing internally
   connectToPeer(_address: string): void {}
 
   isRemoteOrigin(_origin: unknown): boolean {
@@ -178,16 +174,12 @@ class WakuDocTransport implements DocTransport {
 /**
  * Creates a `DocTransportFactory` using the Waku network for real-time notifications.
  *
- * Spins up a Waku light node that connects to the decentralised Waku network via
- * libp2p gossipsub. Outgoing payloads are sent with LightPush; incoming messages are
- * received via the Filter protocol (push-based, low latency).
- *
- * Node initialisation is asynchronous. `subscribe` and `publish` calls made before
- * the node is ready are buffered and drained automatically once the node connects.
- * `DOC_EVENTS.PEERS_CONNECTED` is emitted when the node reaches a healthy state.
+ * Spins up a Waku light node connected to the decentralised network via libp2p gossipsub.
+ * Outgoing payloads use LightPush; incoming messages arrive via the Filter protocol.
+ * `subscribe` and `publish` calls made before the node is ready are buffered and drained
+ * automatically. `DOC_EVENTS.PEERS_CONNECTED` is emitted once the node is healthy.
  *
- * @param bootstrapPeers Optional list of libp2p multiaddr bootstrap peers.
- *   When omitted, the Waku default bootstrap set is used (`defaultBootstrap: true`).
+ * @param bootstrapPeers Optional libp2p multiaddr bootstrap peers. Defaults to Waku's public bootstrap set.
  */
 export function createWakuTransport(bootstrapPeers?: string[]): DocTransportFactory {
   return (deps: DocTransportDeps) => new WakuDocTransport(deps, bootstrapPeers)
diff --git a/src/lib/notification/yWebrtcTransport.ts b/src/lib/notification/yWebrtcTransport.ts
index 98a639c..7447d95 100644
--- a/src/lib/notification/yWebrtcTransport.ts
+++ b/src/lib/notification/yWebrtcTransport.ts
@@ -1,6 +1,6 @@
 import { WebrtcProvider } from 'y-webrtc'
 
-import { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/docTransport'
+import { DocTransport, DocTransportDeps, DocTransportFactory } from '../interfaces/doc'
 import type { NotificationHandler, NotificationPayload } from '../interfaces/notification'
 import { remove0x } from '../utils/common'
 import { Logger } from '../utils/logger'
@@ -57,13 +57,9 @@ class YWebrtcTransport implements DocTransport {
   // y-webrtc manages peer connections automatically via the signaling server
   connectToPeer(_address: string): void {}
 
-  // y-webrtc propagates updates via data channels — no notification publish needed
-  subscribe(_topic: string, _handler: NotificationHandler): void {
-    /** no-op */
-  }
-  publish(_payload: NotificationPayload): void {
-    /** no-op */
-  }
+  // y-webrtc propagates updates via data channels — subscribe/publish are unused
+  subscribe(_topic: string, _handler: NotificationHandler): void {}
+  publish(_payload: NotificationPayload): void {}
 
   isRemoteOrigin(origin: unknown): boolean {
     return this.provider !== null && origin === this.provider
@@ -73,15 +69,13 @@ class YWebrtcTransport implements DocTransport {
 /**
  * Creates a `DocTransportFactory` using y-webrtc for real-time peer-to-peer sync.
  *
- * Establishes WebRTC data channels through a WebSocket signaling server (e.g. a
- * y-webrtc-compatible relay). Peer discovery is automatic via the `awareness` protocol —
- * no explicit `connectToPeer` calls are needed.
- *
- * Newly discovered peers are surfaced via `deps.onPeerDiscovered`, triggering a Swarm
- * snapshot fetch so document history written while the peer was offline is recovered.
+ * Establishes WebRTC data channels via a WebSocket signaling server. Peer discovery
+ * is automatic via the y-webrtc `awareness` protocol — no explicit `connectToPeer`
+ * calls are needed. New peers are surfaced via `deps.onPeerDiscovered`, triggering a
+ * Swarm snapshot fetch for any history written while the peer was offline.
  *
- * `subscribe` and `publish` are no-ops: y-webrtc propagates Yjs updates over data channels
- * internally and also handles cross-tab sync via its built-in BroadcastChannel.
+ * `subscribe` and `publish` are no-ops — y-webrtc handles Yjs sync and cross-tab
+ * BroadcastChannel internally.
  *
  * @param signalingUrl WebSocket URL of the signaling server.
  * @param iceServers Optional custom ICE server list. Falls back to public STUN if omitted.
diff --git a/src/lib/utils/common.ts b/src/lib/utils/common.ts
index 1178cf5..91974ee 100644
--- a/src/lib/utils/common.ts
+++ b/src/lib/utils/common.ts
@@ -12,11 +12,6 @@ export function remove0x(hex: string): string {
   return (hex.startsWith('0x') ? hex.slice(2) : hex).toLowerCase()
 }
 
-/**
- * Retries an async function with exponential backoff.
- * Delays double on each attempt: baseDelay, baseDelay*2, baseDelay*4, …
- * Throws (and logs) after all retries are exhausted.
- */
 export async function retryAwaitableAsync<T>(fn: () => Promise<T>, retries = 3, baseDelay = 250): Promise<T> {
   try {
     return await fn()
@@ -32,7 +27,6 @@ export async function retryAwaitableAsync<T>(fn: () => Promise<T>, retries = 3,
   }
 }
 
-// Safely parse an index string that may be decimal or hex (legacy compatibility)
 export const indexStrToBigint = (indexStr?: string): bigint | undefined => {
   if (!indexStr) return undefined
 
diff --git a/src/lib/utils/constants.ts b/src/lib/utils/constants.ts
index bb33fa9..973e321 100644
--- a/src/lib/utils/constants.ts
+++ b/src/lib/utils/constants.ts
@@ -1,8 +1,6 @@
 import { FeedIndex } from '@ethersphere/bee-js'
 
-/** Current protocol version string included in every `NotificationPayload`. */
 export const API_VERSION = 'v1'
-/** Placeholder postage batch ID used in test/dev environments where stamps are not required. */
 export const PLACEHOLDER_STAMP = '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
 export const FEED_INDEX_ZERO = FeedIndex.fromBigInt(0n)
 /** Feed ID suffix for per-user document snapshot feeds: `<topic>_doc<address>`. */
diff --git a/src/lib/utils/eventEmitter.ts b/src/lib/utils/eventEmitter.ts
index ce096e5..2c9a1a4 100644
--- a/src/lib/utils/eventEmitter.ts
+++ b/src/lib/utils/eventEmitter.ts
@@ -4,7 +4,6 @@ interface Events {
   [key: string]: Listener<any>[]
 }
 
-/** Minimal typed event emitter used internally by `SwarmDoc` to surface lifecycle events. */
 export class EventEmitter {
   private events: Events = {}