Connect pointers to an application

Use scoped awareness

Add Pointers().bind("peers", "remote_pointers") to the page. Handle pointer-change with SetField to write local pointer state. Configure Wire.awareness with an Awareness(local="activity", peers="remote_activity") scope, and map each {peer, state} entry to {peer, pointer: state.pointer, label, color} in remote_pointers.

Keep the local peer out of this list. Choose labels and colors in your application. Reuse the page’s managed connection so reconnect and page lifecycle events also manage awareness. The example includes this setup.

Adapt a virtualized component

Set the browser element’s adapter property after mounting it:

pointers.adapter = {
  hitTest: (x, y) => tree.getItemAtPoint(x, y) ?? null,
  resolve: (id) => {
    const geometry = tree.getItemBounds(id);
    return geometry && {
      ...geometry,
      hit: (x, y) => tree.getItemAtPoint(x, y) === id,
    };
  },
  roots: () => [tree],
};

Use stable record IDs, including a field ID when appropriate. Return undefined for deleted, collapsed, or unmounted targets. Provide visibleBounds for clipped rows, and reject obscured points in hit. Dispatch a bubbling viewport-change event when internal layout changes cannot be observed from the supplied roots.

Track pointers outside component targets

Run python -m spaday_collab.example and leave Share my pointer across the page checked. The checkbox controls local sharing; remote pointers remain visible when it is unchecked.

The example’s js/examples/page-pointers.js wraps a PointerAdapter:

pointers.adapter = pageTargets(componentAdapter, true);

A component target takes priority. Otherwise, the wrapper uses a normalized viewport position. Target IDs are prefixed to distinguish component targets from the page fallback. This helper is example code, not a package export; copy it into your application and wrap the same adapter used for table rows, tree items, or ordinary HTML.

Viewport positions show approximate activity when users have different page layouts or scroll positions. Component positions identify the same content. If a component target is missing or off-screen in the receiving browser, its pointer stays hidden; the example does not reinterpret it as a page position. Blur, leaving the page, and awareness disconnects still withdraw pointers.

Show focus and editing activity

Run the local example in two browsers. Focus the shared note as Alice: Bob sees “Alice: Focused” beside it. Type to show “Alice: Editing”; after 1.5 seconds without input, the label returns to “Focused”. Press Tab to move the focus indicator to the review section. Moving the pointer does not change keyboard focus.

To adapt this behavior, copy js/examples/focus.js and the awareness mapping in js/examples/example.js. The helper reports {target, editing, selection?} or null, using the focused HTML element’s nearest data-collab-target. Keep this state alongside the pointer in one awareness value so updating either field preserves the other. Use SetField("pointer", event_value("pointer")) for pointer events, then compose the awareness value in the store subscription as the example does.

Render each remote target’s labels through ordinary Python components and textContent bindings. Clear focus on window blur, hidden pages, and navigation. Disconnect the helper when removing the page integration. The managed awareness connection removes disconnected peers and republishes current local state after reconnect.

The helper and its timeout are example policy, not package exports. For virtualized rows or shadow components, map the component’s focus/selection events to stable record or field IDs in your adapter; do not use DOM row indices as shared identities. Keep editor text anchors in the editor’s existing collaboration API. Focus labels communicate activity and do not lock fields or grant permission.

Show a textarea selection

Select text in Alice’s shared note to show a colored highlight in Bob’s textarea. Collapse the selection to show a caret; a backward selection places that caret at its active end. Each browser uses its own wrapping, textarea size, and scroll position. The overlay ignores pointer input.

The example helper js/examples/text-selection.js measures text in a hidden mirror of the textarea and draws the remote ranges above it. Focus changes publish the textarea’s UTF-16 anchor and head offsets along with the exact text snapshot. Only matching snapshots render, so a model update arriving before its awareness update hides stale marks. Empty text and trailing newlines still have caret positions. Blur, target changes, and disconnected peers remove the marks.

This small-note example includes the note text in awareness to validate offsets. It does not transform selections through concurrent edits or turn the textarea into a text CRDT. Use spaday-codemirror’s anchored selections for collaborative code editing; keep this mirror and snapshot policy in example code.

Share other page activity

Use Share my activity in the local example to control each outgoing signal independently:

Control

Default

Remote display

Page-text selections

On

Selected text highlighted in matching content.

Focus and textarea selections

On

Focus/editing labels and textarea ranges/carets.

Click indicators

Off

A colored marker that fades after 800 ms.

Viewport position

Off

A percentage showing approximate progress down the page.

Turning a control off withdraws that local state. It does not hide incoming activity. The pointer checkbox remains independent. All signals use the same awareness connection.

For ordinary text, mark static, non-overlapping blocks with unique data-collab-text IDs. The js/examples/page-selection.js helper splits a native selection across those blocks and sends exact text snapshots plus UTF-16 offsets. The receiver resolves its own text nodes, rejects mismatched snapshots, and uses the CSS Custom Highlight API to paint ranges without replacing its local selection. Keep form controls, private text, and presence labels outside these opted-in blocks. Browsers without that API omit the page highlights.

js/examples/page-activity.js demonstrates click and viewport sharing. Clicks use the existing geometry adapter; keyboard activation uses the activated element’s center. Receiving a click only paints a marker and never activates a control. Markers expire, ignore duplicate deliveries, and clear on scroll or disconnect. Viewport progress is approximate when layouts differ. It never scrolls the receiving page; a scrollbar overlay or minimap can be added by the application if useful.

These helpers and defaults are example policy, not public library APIs. Dispose the helpers when removing the integration; blur, hidden pages, and page lifecycle events withdraw local activity.

Replace the renderer

Import connectPointers from /components/collab/cdn/index.js. Pass a geometry adapter, a callback for local state, and a callback for projected remote coordinates. Call render(remotePeers) when awareness changes and disconnect() when removing the integration. No Pointers element is required.

Style pointers

Set --spa-collab-accent, --spa-collab-label-text, or --spa-collab-z-index on the page or component. A peer’s explicit color overrides the default accent. Use spaday-pointers::part(cursor), ::part(label), and ::part(hover) for additional styling.

Mount the overlay outside transformed or clipped containers so fixed positioning uses the page viewport.