playhtml

A critical error occurs when a reactive subscription (like a React useEffect) both depends on shared data and writes to it. Because setData with the replacement form (e.g., setData({ entries: [...] })) on an array is not idempotent, concurrent writes can cause the loop to never converge, leading to massive document growth.

The Fix:

1. Use a keyed map instead of an array: Store collections as objects keyed by ID. This allows for idempotent 'upsert' operations.
2. Use the mutator form: Use setData((draft) => { ... }) to update specific keys. This is merge-safe and idempotent.
3. Decouple dependencies: Use a ref to read the data inside your effect so the effect only triggers on the specific inputs that should cause a write (like a user's local identity), not on every change to the shared collection.

// The strongest fix: Keyed map + mutator write
const Roster = withSharedState({ defaultData: { entries: {} } }, ({ data, setData }) => {
  const me = useMe(); // { id, name }
  const ref = useRef(data.entries);
  ref.current = data.entries;

  useEffect(() => {
    const existing = ref.current[me.id];
    if (existing && existing.name === me.name) return;

    // Keyed mutator write is idempotent and merge-safe
    setData((draft) => { draft.entries[me.id] = me; });
  }, [me.id, me.name]); // Depends on local identity, NOT on data.entries
  return <div />;
});

Every capability in playhtml is implemented as a single HTML attribute. When you apply a can-* attribute to an element, the library automatically handles state synchronization, persistence, and event wiring across all users.

Requirements for Syncing

• Stable IDs: Every interactive element must have a stable id (e.g., id="my-lamp"). This id is the key used to store and sync data. If omitted, playhtml falls back to hashing the HTML, which can break sync across different browsers.
• Many-of-a-kind elements: For groups of similar elements (like a list of magnets), instead of unique IDs, use the selector-id attribute. Playhtml will index matches by position (the N-th match gets the N-th state slot).

Resetting State

Built-in interactive capabilities (can-move, can-spin, can-toggle, and can-grow) support shift-clicking an element to reset it to its default state. This reset is synchronized for all users in the session.

Shared elements allow you to synchronize state and data between different pages on the same site or across different domains. You define a source element on one page and reference it on consumer pages. The consumer can use entirely different markup, styles, or layouts while still participating in the shared state via specific capabilities.

Core Requirements for Consumers

To successfully consume a shared element, the consumer must provide:

1. data-source: A string in the format domain/path#elementId (e.g., thissite.com/blog/post#counter). The part after # is the shared ID.
2. Matching Capability: The consumer must include a capability tag (e.g., can-move, can-toggle, can-grow) that matches the capability declared on the source.

Permissions and Read-Only Modes

• Source Permissions:
  • shared or shared="read-write" (default): Allows both reading and writing state.
  • shared="read-only" or shared="ro": The source only broadcasts updates; consumers cannot write back to it.
• Consumer Permissions:
  • Add data-source-read-only to a consumer to force local read-only behavior, even if the source is configured for read-write. PlayHTML will automatically apply a not-allowed cursor to these elements.

Combining Capabilities

Consumers can include additional capabilities that are local-only. Only the capabilities declared on the source are synchronized. For example, if a source has can-move, a consumer can have can-move (synchronized) and can-toggle (local-only).

<!-- Vanilla HTML Example -->
<!-- Source page (thissite.com) -->
<div id="couch" shared can-move style="font-size: 80px">🛋</div>

<!-- Consumer page (anothersite.com) -->
<div data-source="thissite.com#couch" can-move>🪑</div>

PlayHTML provides different primitives for moving state between readers. Selection should be based on lifetime (should it survive a page reload?) and scope (does it belong to one element, the whole page, or a single user?).

Decision Guide

Key Rules

• Persistence: If a new reader opening the page should see the state, use persistent data (Element or Page data). If they shouldn't, use presence or an event.
• User Preferences: If you want state to survive a reload but not sync to other users (e.g., personal settings), use localStorage instead of PlayHTML primitives.

The most dangerous bug in PlayHTML is a reactive callback (like a React useEffect or a vanilla updateElement) that both reads shared data and writes it. This creates an infinite loop: the write changes the data $\rightarrow$ the dependency re-fires $\rightarrow$ it writes again. Because PlayHTML uses CRDTs, these loops can grow the document size exponentially and crash the room.

The Solution

1. Prefer Keyed Maps: Instead of arrays, model collections as keyed maps (e.g., { [id: string]: Value }). Keyed writes are idempotent and merge-safe.
2. Use Refs for Dependencies: When using useEffect, read the data through a useRef so the effect depends on a local identity rather than the shared collection itself.
3. Event-Driven Writes: Always prefer writing shared data from explicit user events (like onClick) rather than reactive callbacks.

// DANGER — infinite write loop
useEffect(() => {
  setData({ entries: [...data.entries, me] }); // writes entries...
}, [data.entries]);                            // ...re-runs because entries changed

// FIX: Use a keyed map and a ref to avoid the loop
const ref = useRef(data.entries);
ref.current = data.entries;

useEffect(() => {
  if (ref.current[me.id]?.name === me.name) return;       // already correct
  setData((draft) => { draft.entries[me.id] = me; });      // keyed, idempotent, merge-safe
}, [me.id, me.name]); // local identity only — NOT data.entries