Interface: Room\<TPresence\>
@roomful/core / Room
Interface: Room<TPresence>
Section titled “Interface: Room<TPresence>”Defined in: packages/core/src/types.ts:2558
Exposes the public room API.
Type Parameters
Section titled “Type Parameters”TPresence
Section titled “TPresence”TPresence extends PresenceData = PresenceData
The custom peer presence shape.
Properties
Section titled “Properties”
readonlyid:string
Defined in: packages/core/src/types.ts:2562
Identifies the room.
peerCount
Section titled “peerCount”
readonlypeerCount:number
Defined in: packages/core/src/types.ts:2582
Reports the current peer count.
peerId
Section titled “peerId”
readonlypeerId:string
Defined in: packages/core/src/types.ts:2567
Identifies the local peer.
readonlypeers:Peer<TPresence>[]
Defined in: packages/core/src/types.ts:2577
Exposes the latest known peer list.
status
Section titled “status”
readonlystatus:RoomStatus
Defined in: packages/core/src/types.ts:2572
Reports the current room status.
Methods
Section titled “Methods”applyReplaySignal()
Section titled “applyReplaySignal()”applyReplaySignal(
signal):void
Defined in: packages/core/src/types.ts:2744
Applies a previously recorded wire signal to this room’s engines, as if it
had just arrived — reconstructing presence, cursors, and shared state from
a RecordingFrame’s signal. Feed a recording’s frames in order
(e.g. from a ReplaySession) into a throwaway offline room to replay
a session visually. Not for live use.
Parameters
Section titled “Parameters”signal
Section titled “signal”PeerWireMessage
The recorded wire signal to apply.
Returns
Section titled “Returns”void
Nothing.
connect()
Section titled “connect()”connect():
Promise<void>
Defined in: packages/core/src/types.ts:2589
Connects the room to its transport.
Returns
Section titled “Returns”Promise<void>
A promise that resolves when connection startup completes.
disconnect()
Section titled “disconnect()”disconnect():
Promise<void>
Defined in: packages/core/src/types.ts:2596
Disconnects the room from its transport.
Returns
Section titled “Returns”Promise<void>
A promise that resolves when disconnect teardown completes.
getDiagnostics()
Section titled “getDiagnostics()”getDiagnostics():
Promise<RoomDiagnostics>
Defined in: packages/core/src/types.ts:2603
Produces a diagnostics snapshot for the room.
Returns
Section titled “Returns”Promise<RoomDiagnostics>
A promise that resolves to the current diagnostics snapshot.
getRemainingTime()
Section titled “getRemainingTime()”getRemainingTime():
number|null
Defined in: packages/core/src/types.ts:2617
Returns the remaining TTL in ms for an ephemeral room, or null when not applicable.
Returns
Section titled “Returns”number | null
Milliseconds until auto-disconnect, or null.
getUsageMetrics()
Section titled “getUsageMetrics()”getUsageMetrics():
UsageMetrics
Defined in: packages/core/src/types.ts:2610
Returns cumulative usage metrics for the room session, for telemetry/analytics.
Returns
Section titled “Returns”The current usage metrics.
getYDoc()
Section titled “getYDoc()”getYDoc():
Doc
Defined in: packages/core/src/types.ts:2759
Exposes the underlying Yjs document for CRDT integrations.
Returns
Section titled “Returns”Doc
The shared Yjs document.
getYProvider()
Section titled “getYProvider()”getYProvider():
RoomfulYjsProvider
Defined in: packages/core/src/types.ts:2766
Exposes the underlying Yjs provider for CRDT integrations.
Returns
Section titled “Returns”The Yjs provider.
off<
TEvent>(event,cb):void
Defined in: packages/core/src/types.ts:2789
Removes a built-in room lifecycle listener.
Type Parameters
Section titled “Type Parameters”TEvent
Section titled “TEvent”TEvent extends RoomEventName
The built-in event name being removed.
Parameters
Section titled “Parameters”TEvent
The event name to unsubscribe from.
RoomEventHandler<TPresence, TEvent>
The callback to remove.
Returns
Section titled “Returns”void
Nothing.
on<
TEvent>(event,cb):Unsubscribe
Defined in: packages/core/src/types.ts:2776
Subscribes to a built-in room lifecycle event.
Type Parameters
Section titled “Type Parameters”TEvent
Section titled “TEvent”TEvent extends RoomEventName
The built-in event name to subscribe to.
Parameters
Section titled “Parameters”TEvent
The event name to observe.
RoomEventHandler<TPresence, TEvent>
The callback invoked with the matching payload.
Returns
Section titled “Returns”A function that removes the listener.
useActivity()
Section titled “useActivity()”useActivity(
options?):ActivityEngine
Defined in: packages/core/src/types.ts:2690
Accesses the room activity feed engine.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional feed configuration (retention limit).
Returns
Section titled “Returns”The activity engine.
useAgentApprovals()
Section titled “useAgentApprovals()”useAgentApprovals(
options?):AgentApprovalEngine
Defined in: packages/core/src/types.ts:2699
Accesses the agent-approval engine: the human-in-the-loop workflow where agents propose actions and humans approve or reject them.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional configuration (permission hook).
Returns
Section titled “Returns”The agent-approval engine.
useAuditLog()
Section titled “useAuditLog()”useAuditLog():
AuditLog
Defined in: packages/core/src/types.ts:2714
Accesses the tamper-evident audit log for this room.
Entries are hash-chained; call verify() to detect tampering.
Returns
Section titled “Returns”The audit log.
useAwareness()
Section titled “useAwareness()”useAwareness():
AwarenessEngine
Defined in: packages/core/src/types.ts:2651
Accesses the awareness engine for this room.
Returns
Section titled “Returns”The awareness engine.
useComments()
Section titled “useComments()”useComments(
options?):CommentsEngine
Defined in: packages/core/src/types.ts:2682
Accesses the collaborative comments engine for this room.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional storage backend configuration.
Returns
Section titled “Returns”The comments engine.
useCursors()
Section titled “useCursors()”useCursors<
TCursor>(options?):CursorEngine<TCursor>
Defined in: packages/core/src/types.ts:2633
Accesses the cursor engine for this room.
Type Parameters
Section titled “Type Parameters”TCursor
Section titled “TCursor”TCursor extends CursorData = CursorData
The custom cursor payload shape.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional cursor tracking configuration.
Returns
Section titled “Returns”CursorEngine<TCursor>
The cursor engine.
useEvents()
Section titled “useEvents()”useEvents(
options?):EventEngine<TPresence>
Defined in: packages/core/src/types.ts:2752
Accesses the custom event engine for this room.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional custom event behavior overrides.
Returns
Section titled “Returns”EventEngine<TPresence>
The event engine.
useFieldPresence()
Section titled “useFieldPresence()”useFieldPresence():
FieldPresenceEngine
Defined in: packages/core/src/types.ts:2706
Accesses the field-presence engine: which remote peers are active on which field.
Returns
Section titled “Returns”The field-presence engine.
useHistory()
Section titled “useHistory()”useHistory(
options?):HistoryEngine
Defined in: packages/core/src/types.ts:2723
Accesses the collaborative history (undo/redo plus shared timeline) engine for this room.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional history configuration.
Returns
Section titled “Returns”The history engine.
useLocks()
Section titled “useLocks()”useLocks():
LockEngine
Defined in: packages/core/src/types.ts:2674
Accesses the distributed advisory lock engine for this room.
Returns
Section titled “Returns”The lock engine.
usePointer()
Section titled “usePointer()”usePointer(
options?):PointerEngine
Defined in: packages/core/src/types.ts:2667
Accesses the laser-pointer engine for this room.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional pointer tracking configuration.
Returns
Section titled “Returns”The pointer engine.
usePresence()
Section titled “usePresence()”usePresence():
PresenceEngine<TPresence>
Defined in: packages/core/src/types.ts:2624
Accesses the presence engine for this room.
Returns
Section titled “Returns”PresenceEngine<TPresence>
The presence engine.
useRecording()
Section titled “useRecording()”useRecording(
options?):RecordingEngine
Defined in: packages/core/src/types.ts:2732
Accesses the session-recording engine for this room: capture the room’s wire signals, then export or replay them. Local to this peer.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional configuration, including a redact privacy hook.
Returns
Section titled “Returns”The recording engine.
useState()
Section titled “useState()”useState<
T>(options):StateEngine<T>
Defined in: packages/core/src/types.ts:2644
Accesses the shared-state engine for this room.
Type Parameters
Section titled “Type Parameters”T
The shared state value type.
Parameters
Section titled “Parameters”options
Section titled “options”StateOptions<T>
The shared-state configuration.
Returns
Section titled “Returns”StateEngine<T>
The state engine.
useViewport()
Section titled “useViewport()”useViewport(
options?):ViewportEngine
Defined in: packages/core/src/types.ts:2659
Accesses the viewport synchronization engine for this room.
Parameters
Section titled “Parameters”options?
Section titled “options?”Optional viewport tracking configuration.
Returns
Section titled “Returns”The viewport engine.