Clarion Call: Beats, Pulses, and a Beat-Aware Future for PulseCam

[horner]

📣 Clarion Call: Beats, Pulses, and a Beat-Aware, Threaded Future for PulseCam

This issue captures a directional shift in how we think about PulseCam’s data model and long-term evolution — while preserving everything that makes PulseCam fast, intuitive, and export-friendly today.

PulseCam remains a push-to-record short creator.
What changes is how deeply structured that content can become.

---

🧭 Original Intent (Reaffirmed)

PulseCam excels at:

• Capturing many small recording moments
• Minimizing traditional editing friction
• Exporting finished shorts to TikTok, YouTube Shorts, and Instagram

All of that stays.

This proposal extends PulseCam so that the same recordings can also participate in:

• Beat-level navigation
• Replies and threading
• Private or hosted environments
• Rich metadata and transcripts

---

🧠 Core Vocabulary

Clip (existing, internal)

• A raw video file captured on-device
• May be long
• Edited today via non-destructive time offsets

Beat (new, first-class concept)

A beat is a privacy-final, addressable unit of intent.

• Represents exactly what the user intends to be seen
• Has its own UUID
• Has a title
• May include:
  • A high-precision transcript (e.g., Whisper-class)
  • Word-level timing offsets
• Is safe to:
  • Share
  • Link to
  • Reply to
  • Embed in transcripts or timelines

Not every clip is a beat.
A beat is what survives finalization.

---

Pulse

• An ordered collection of beats
• Conceptually what we “send”
• A pulse can always be flattened into a traditional short
• Pulses may themselves be replies to other pulses

---

🔀 Draft vs Finalized (Privacy Boundary)

Draft Phase

• Clips may be long
• Editing is non-destructive
• Timelines reference clips + offsets
• Clips may sync across devices
• Privacy is not yet finalized

Finalized Phase (Beat Creation)

• Beats are materialized as trimmed video assets
• Each beat gets a new UUID
• No beat references unseen footage
• Previously uploaded raw material is invalidated/deleted
• Pulses reference beats only

This boundary is non-negotiable and defines trust.

---

🔗 Replies, Hyperlinks, and Threading (Key Expansion)

PulseCam must support replies at multiple levels:

• Reply to an entire pulse
• Reply to a single beat
• Reply to multiple beats

Beat Ancestry

• Every beat may reference one or more parent beats
• This creates a navigable reply graph (not just a flat stitch)

Player Implications

When watching a beat:

• The player may display a subtle watermark or affordance indicating:
  • “This beat is a reply to…”
• Users can tap to:
  • View the referenced beat(s)
  • Jump into their parent pulse
  • Zoom out into a threaded view

Explicit goal:
Even deep reply chains should never feel disorienting.

---

🧵 Threaded Views (Conceptual Goal)

Future UI (not specified here) should allow:

• Navigating reply trees of beats
• Understanding where a beat sits in the broader conversation
• Moving fluidly between:
  • Beat
  • Pulse
  • Thread

This is a deliberate improvement over stitch-based models where context is easily lost.

---

🏷️ Beat Titles & External Timelines

Each beat has a title, which enables:

• Timeline chapter markers when exporting to platforms like YouTube
• Human-readable navigation within pulses
• Alignment between:
  • Video
  • Timeline
  • Transcript

A pulse exported as a short can surface beat titles as chapter cards automatically.

---

📝 Transcripts as a First-Class Surface

Beats may include high-quality transcripts with word-level timing.

Long-term vision:

• Transcripts are not just captions
• They are a navigational and compositional surface

Copy / Paste as Media Transport

In the future:

• Copying annotated transcript text is like copying rich text
• Pasted text retains:
  • Beat UUID references
  • Word timing offsets
  • URLs back to the beat
• Clicking text can:
  • Play the corresponding beat
  • Reveal its context

Copying text carries the video with it.

This enables entirely new workflows:

• Re-quoting video by text
• Reassembling pulses via transcript
• Turning conversations into editable media graphs

---

🌐 PulseCam + PulseVault (Forward-Looking)

PulseVault (separate repo/app) may:

• Store beats and pulses
• Enable private sharing, replies, and voting
• Be self-hosted

PulseCam should be able to:

• Operate fully standalone
• Or become beat-aware when connected to a vault

This ticket does not design PulseVault — it ensures compatibility.

---

🧪 Open Experiment: OpenTimelineIO (OTIO)

For draft timelines and interchange:

• Investigate OpenTimelineIO (OTIO) as an editorial representation
• Possible mappings:
  • Clips → OTIO media references
  • Edits → time ranges
  • Beat boundaries → markers / cuts

This is an experiment, not a mandate.
The goal is leverage and interoperability.

---

🚫 Non-Goals (For This Ticket)

• UI implementation details
• Thread visualization design
• Storage schemas
• Permissions / ACLs
• Streaming optimizations

This ticket defines conceptual ground truth.

---

✅ Success Criteria

This issue succeeds when:

• Beats are understood as:
  • Addressable
  • Titled
  • Transcribed
  • Replyable
• Pulses are understood as compositions, not files
• Replies are understood as beat-linked, not just video-linked
• Privacy boundaries are clear
• Future tickets can build confidently on this model

---

🏁 Closing

This is not just a video editor.
It’s a structured, conversational media system.

Getting the primitives right now unlocks everything that follows.

[horner]

Let’s talk about OTIO and the format. How would we map our vocabulary to vocabulary that priority exists within that format?

This is exactly the right moment to slow down and map concepts cleanly, because OTIO is powerful precisely because it doesn’t force semantics you don’t want — but that also means you need to be deliberate about how you layer meaning on top of it.

I’ll do this in four passes:

1. Quick OTIO mental model (plain English)
2. Direct vocabulary mapping: PulseCam ↔ OTIO
3. How replies, beat titles, and transcripts fit without fighting OTIO
4. What NOT to overload OTIO with (important)

No hype, no abstraction hand-waving.

---

1️⃣ OTIO mental model (what it actually is)

OpenTimelineIO (OTIO) is:

• A timeline interchange format
• Describes how media is assembled, not how it is stored or played
• Explicitly avoids defining:
  • Rendering
  • UI
  • Storage
  • Networking

At its core, OTIO answers:

“Given these media references, in what order and at what ranges do we play them?”

Key primitives:

OTIO Concept	Plain meaning
Timeline	A named edit
Track	An ordered list of things
Clip	A reference to media
ExternalReference	“This clip lives at this URL/path”
TimeRange	In/out within the media
Marker	Annotated time point or range
Metadata	Arbitrary structured data

OTIO is deliberately extensible via metadata — that’s where PulseCam fits.

---

2️⃣ Core vocabulary mapping (clean and intentional)

Here’s the recommended mapping, optimized for clarity and future interoperability, not cleverness.

PulseCam → OTIO mapping

PulseCam concept	OTIO representation	Notes
Pulse	Timeline	One pulse = one OTIO timeline
Beat (draft)	Clip with ExternalReference + TimeRange	Points into raw clip
Beat (finalized)	Clip with ExternalReference to trimmed asset	No offsets
Clip (raw capture)	Media file referenced by ExternalReference	Internal / draft only
Pulse order	Track ordering	Likely a single video track
Beat title	Clip.name or metadata	name is human-readable
Beat UUID	Metadata on Clip	OTIO doesn’t care about IDs
Beat boundaries	Clip edges (preferred) or Markers	Clip edges are cleaner

🔑 Important principle:
A Beat should map to exactly one OTIO Clip.

This keeps mental models aligned.

---

3️⃣ Draft vs Finalized in OTIO terms

This maps beautifully to OTIO.

Draft Timeline (pre-privacy)

Timeline
 └── Track
      ├── Clip (ExternalReference → raw_clip_A.mp4)
      │     source_range: 00:00–00:30
      ├── Clip (ExternalReference → raw_clip_B.mp4)
      │     source_range: 00:05–00:12

• Multiple OTIO clips may reference the same raw media
• Edits are non-destructive
• Multi-device safe
• Not privacy-final

---

Finalized Timeline (beats materialized)

Timeline
 └── Track
      ├── Clip (ExternalReference → beat_123.mp4)
      ├── Clip (ExternalReference → beat_124.mp4)

• Each clip references a trimmed beat asset
• No source_range (or full-range only)
• Privacy boundary enforced
• PulseVault-safe

OTIO stays the same.
Only the meaning of the referenced media changes.

That’s a huge win.

---

4️⃣ Replies & beat ancestry (OTIO does not fight you here)

OTIO does not have opinions about replies, threads, or social graphs — which is good.

Beat → Beat reply links

Use OTIO metadata:

{
  "metadata": {
    "pulse": {
      "beat_uuid": "beat-456",
      "reply_to": ["beat-123", "beat-124"],
      "reply_type": "beat"
    }
  }
}

This keeps:

• OTIO semantics intact
• Social semantics layered cleanly

---

Pulse → Pulse replies

Store at the Timeline level:

{
  "metadata": {
    "pulse": {
      "pulse_uuid": "pulse-789",
      "reply_to_pulse": "pulse-456"
    }
  }
}

OTIO timelines already support arbitrary metadata — you’re just using it.

---

5️⃣ Beat titles & chapters (first-class, no hacks)

OTIO already supports names and markers.

Beat titles

Use:

• Clip.name → beat title (human-facing)
• metadata.pulse.beat_title → canonical title if needed

This maps directly to:

• YouTube chapter titles
• Timeline labels
• Transcript headers

---

6️⃣ Transcripts & word-level timing (OTIO-friendly)

OTIO does not define transcript structures — and that’s good.

Recommended pattern:

{
  "metadata": {
    "pulse": {
      "transcript": {
        "engine": "whisper",
        "language": "en",
        "segments": [
          {
            "start": 0.42,
            "end": 1.98,
            "text": "This is the beat",
            "word_offsets": [...]
          }
        ]
      }
    }
  }
}

Why this works:

• OTIO stays editorial
• Transcript data remains portable
• Text ↔ beat ↔ video linkage is explicit

Copy/paste semantics live above OTIO, not inside it.

---

7️⃣ What NOT to force into OTIO (important)

OTIO should not be responsible for:

❌ Streaming behavior
❌ Fetch order
❌ Player buffering
❌ Permissions / ACLs
❌ Beat deletion semantics
❌ Privacy enforcement

Those belong to:

• PulseCam runtime
• PulseVault backend
• Player logic

OTIO is the map, not the territory.

---

8️⃣ Why this mapping is the right long-term bet

This approach gives you:

• ✅ Open, interoperable timelines
• ✅ Clean draft → finalize boundary
• ✅ Beat-first without breaking editors
• ✅ A future where:
  • Other tools can import/export pulses
  • PulseVault can have multiple implementations
  • Beats become linkable media atoms

And critically:

You are not inventing a video format.
You are inventing a media conversation model on top of an existing editorial standard.

[horner]

How can we define a cut/copy/paste clipboard format for transcript text that’s interoperable across apps, where the pasted content can preserve references to beats (by UUID/URL) — potentially even across users — and where beats might be fetchable without authentication because the UUID itself acts like an unguessable secret?”

---

Define a clipboard format that is interoperable by putting multiple representations of the same copied transcript onto the clipboard:

1. Plain/Markdown-friendly text that pastes well everywhere and preserves beat references as links.
2. HTML that embeds beat metadata (beat UUID/token, optional word offsets, titles) so Pulse-aware apps can rehydrate rich structure.

This works across apps because:

• Most paste targets understand plain text (and many understand Markdown-like links).
• Many preserve HTML and allow apps to reconstruct structured spans.
• Beat references can be capability URLs (“unguessable secret links”) so pastes can remain functional even across users and apps without requiring credentials.

---

What goes on the clipboard (the interoperable contract)

A) Text layer (Markdown-friendly)

Put into text/plain something that:

• Reads naturally
• Preserves beat references as Markdown links
• Degrades gracefully if the target doesn’t render Markdown (still shows the URL)

Two good patterns:

Pattern 1: Inline links on the exact quoted text (best for “quote/reply”)

I think we should ship this. [“Let’s make beats first-class.”](https://vault.example/b/<token>#t=12.40,18.20)

Pattern 2: Clean transcript + footnotes (best for longer passages)

We should treat beats as first-class, not just offsets.¹

¹ https://vault.example/b/<token>#w=120-137

Footnotes are extremely robust across:

• Slack / email / docs
• Markdown renderers
• Plain text only environments

You can standardize your query params:

• #t=start,end for time range
• #w=wordStart-wordEnd for transcript range
• (and/or ?pulse=<id>&beat=<id> if you prefer)

B) HTML layer (Pulse-aware richness)

Put into text/html the same text, but wrapped in spans that carry your semantics:

<span data-pulse-schema="1"
      data-pulse-beat="b_7Hk2...9Q"
      data-pulse-ws="120"
      data-pulse-we="137"
      data-pulse-href="https://vault.example/b/b_7Hk2...9Q#t=12.4,18.2">
  Let’s make beats first-class.
</span>

This enables:

• Beat-level highlighting after paste (Pulse-aware targets)
• Click-to-play
• Recovering beat/thread context
• Keeping word offsets for future transcript-aware operations

If a target strips data-*, the text still pastes fine, and the Markdown/plain link still works.

---

How “UUID as secret” fits safely into this

Treat the beat reference as a capability link:

• The URL contains a high-entropy token (not a guessable ID)
• Anyone with the link can fetch the beat (no login required)
• That makes copy/paste “just work” across users/apps

But design for reality:

• Add revocation (rotate token / delete beat / finalize-only publish)
• Keep drafts private (don’t generate capability links until finalized)
• Optionally support authenticated URLs later without changing the clipboard format

Your clipboard format shouldn’t assume public access—it just carries an href.

---

Why this is the best interoperability shape

• Every app can accept the text/plain version.
• Many apps will preserve enough structure in text/html for Pulse-aware paste.
• You avoid relying on custom clipboard MIME types that are inconsistent, especially on mobile Safari.
• You get future-proofing: the HTML is your “rich text,” and the Markdown-friendly text is your “universal fallback.”

---

The “Markdown-friendly” rule of thumb

When copying, default to producing text that is valid Markdown but also readable as plain text:

• Prefer [label](url) for short selections / quotes
• Prefer footnote-style links for long transcript blocks
• Avoid exotic Markdown extensions (tables, HTML-in-Markdown), because they don’t round-trip well

---

One concrete default behavior (recommended)

Copy Transcript Selection writes:

text/plain

• Selected text
• Footnote links per beat referenced

text/html

• Same text
• data-pulse-* spans for beat UUID/token + word offsets + href

This gives you:

• universal pasting
• link preservation
• rich rehydration when possible

---

We ahoulf draft a tiny “Pulse Clipboard v1 spec” (1 page) with:

• required fields and attribute names
• the canonical URL format (/b/<token>#t=… and/or #w=…)
• examples for: single beat, multi-beat selection, cross-beat paragraph
• rules for how selection maps to word offsets and beat spans

[horner]

Below is a ready-to-implement, versioned “Pulse Clipboard v1” spec optimized for:

• Copy/paste across apps + browsers
• Works in Chrome and degrades cleanly elsewhere
• Works with native → web and web → native
• Plays nicely with Markdown-ish environments
• Doesn’t rely on custom clipboard MIME types (which are inconsistent, especially on mobile Safari)
• Allows optional OTIO embedding inside HTML (not as a MIME type)

---

Pulse Clipboard v1 — Specification

0. Goals

Pulse Clipboard v1 defines how to copy transcript text such that:

1. Every paste target gets usable text.
2. Pulse-aware targets can reconstruct beat-linked transcript spans.
3. References to beats remain portable across users/apps via URLs or capability tokens.
4. The payload is safe to strip/sanitize: if metadata is removed, meaning remains.

---

1. Clipboard “Flavors” (MIME types)

REQUIRED

Pulse Clipboard v1 MUST write both:

• text/plain — Markdown-friendly text with beat links (or footnotes)
• text/html — HTML embedding beat metadata using data-pulse-* attributes

OPTIONAL (NOT REQUIRED for v1)

Pulse Clipboard v1 MAY include additional platform-specific rich formats when available (native attributed strings), but these are not part of the normative spec.

Note: v1 intentionally does not require custom MIME types like application/vnd.pulse+json because cross-app/browser support is inconsistent.

---

2. Canonical Beat Reference

A beat reference MUST be representable as a URL (href) that can be pasted anywhere.

Canonical form

https://<host>/b/<beatTokenOrUUID>

Optional fragment/query conventions

Pulse-aware systems SHOULD support the following optional parameters:

• Time range:
  • #t=<startSeconds>,<endSeconds> (floating seconds allowed)
• Word range:
  • #w=<wordStart>-<wordEnd> (integers in transcript word index space)
• Optional pulse context (if helpful, not required):
  • ?p=<pulseId>
• Optional selection id (for analytics/debug, not required):
  • ?sel=<id>

Example

https://vault.example/b/b_7Hk2...9Q#t=12.4,18.2
https://vault.example/b/b_7Hk2...9Q#w=120-137

Capability access

If using “unguessable secret” access, beatTokenOrUUID MUST be high entropy (capability token). v1 does not mandate the token scheme, only that it is stable and URL-safe.

---

3. text/plain Format (Markdown-friendly)

text/plain MUST be valid plain text and SHOULD be Markdown-friendly.

3.1 Default structure: transcript with footnote links

When the selection includes one or more beat spans, text/plain SHOULD be:

• the selected transcript text (no markup required)
• followed by one footnote per beat reference included

Example

We should treat beats as first-class, not just offsets. That’s the key.

¹ Beat: https://vault.example/b/b_7Hk2...9Q#w=120-137
² Beat: https://vault.example/b/b_A91x...Lm#t=4.2,9.0

3.2 Alternative: inline Markdown links (allowed)

If the selection is short (e.g., a quote), implementations MAY produce inline links:

[“Let’s make beats first-class.”](https://vault.example/b/b_7Hk2...9Q#t=12.4,18.2)

3.3 Human readability requirements

• The text MUST remain readable even if the paste target does not render Markdown.
• Links MUST be present as raw URLs somewhere in the text output (inline or footnote).

---

4. text/html Format (Beat-annotated HTML)

text/html MUST contain the human-visible transcript content and SHOULD embed beat metadata via data-* attributes.

4.1 Schema marker

Every beat-annotated region MUST include:

• data-pulse-schema="1"

4.2 Beat span

A beat-linked text run MUST be wrapped in an element (typically span) that includes:

REQUIRED attributes

• data-pulse-schema="1"
• data-pulse-beat="<beatTokenOrUUID>"

OPTIONAL but RECOMMENDED attributes

• data-pulse-href="<canonical beat url>"
• data-pulse-ws="<wordStart>"
• data-pulse-we="<wordEnd>"
• data-pulse-ts="<startSeconds>"
• data-pulse-te="<endSeconds>"
• data-pulse-title="<beat title>"

Example

<p>
  <span data-pulse-schema="1"
        data-pulse-beat="b_7Hk2...9Q"
        data-pulse-href="https://vault.example/b/b_7Hk2...9Q#w=120-137"
        data-pulse-ws="120"
        data-pulse-we="137"
        data-pulse-title="Beat: Why beats matter">
    We should treat beats as first-class, not just offsets.
  </span>
</p>

4.3 Multi-beat selections

If a selection spans multiple beats, the HTML SHOULD preserve boundaries by using multiple spans.

<p>
  <span data-pulse-schema="1" data-pulse-beat="b1">…text…</span>
  <span data-pulse-schema="1" data-pulse-beat="b2">…text…</span>
</p>

4.4 Reply/thread metadata (optional in v1)

If present, reply metadata SHOULD be attached to the beat span as:

• data-pulse-reply-to="<comma-separated beat ids>"
  or multiple attributes:
• data-pulse-reply-to="b_abc,b_def"

This is optional in v1 and may be standardized further in v2.

---

5. Paste/Rehydration Rules (Pulse-aware targets)

A Pulse-aware paste target SHOULD attempt:

1. Parse text/html if available.
2. Extract all nodes with [data-pulse-schema="1"][data-pulse-beat].
3. Build an internal model:

TranscriptFragment model (conceptual)

• spans[] where each span includes:
  • text
  • optional beatId
  • optional offsets/timing/title/href

4. If HTML is missing beat attrs but includes recognizable beat links:
   • parse URLs matching /b/<token> and treat them as beat references
5. Otherwise fall back to plain text.

---

6. Optional: OTIO Embedding (Experimental, HTML-only)

Because clipboard custom MIME types are unreliable cross-app, OTIO (or an OTIO subtree) MAY be embedded inside the HTML for Pulse-aware apps.

6.1 OTIO embedding mechanism (choose one)

Preferred v1 approach: HTML comment

<!-- data-pulse-otio:BASE64URL(<otio json UTF-8 bytes>) -->

Alternative: hidden element (less robust to sanitizers)

<span data-pulse-otio="BASE64URL(...)"></span>

6.2 Scope

The OTIO payload SHOULD represent only the copied selection as an OTIO subtree (e.g., a sequence of Clips in a Track), not the entire project.

6.3 Non-normative

OTIO embedding is explicitly non-normative in v1. Implementations MUST NOT depend on OTIO being present.

---

7. Security & Privacy Considerations (Normative)

• Clipboard data may sync to cloud clipboards (OS features). Treat beat URLs/tokens as potentially shareable.
• Draft clips SHOULD NOT be referenced by capability URLs.
• Beat URLs SHOULD reference finalized, privacy-safe beat media only.
• If beat tokens are revocable, the server SHOULD support deletion/rotation.

---

8. Versioning

• data-pulse-schema="1" identifies this spec version.
• Future versions MUST remain backward-compatible where possible:
  • v2+ readers SHOULD accept v1 spans.

---

9. Conformance Checklist

A conforming Pulse Clipboard v1 writer:

• Writes text/plain with readable transcript + raw URLs
• Writes text/html with data-pulse-schema="1" and data-pulse-beat for beat-linked spans
• Does not rely on custom MIME types
• Produces correct canonical beat URLs

A conforming Pulse Clipboard v1 reader:

• Parses beat spans from HTML when present
• Falls back to plain text gracefully
• Accepts that sanitizers may remove attributes

---

10. Minimal Example (Complete)

text/plain

We should treat beats as first-class, not just offsets.

¹ Beat: https://vault.example/b/b_7Hk2...9Q#w=120-137

text/html

<p>
  <span data-pulse-schema="1"
        data-pulse-beat="b_7Hk2...9Q"
        data-pulse-href="https://vault.example/b/b_7Hk2...9Q#w=120-137"
        data-pulse-ws="120"
        data-pulse-we="137"
        data-pulse-title="Beats as primitives">
    We should treat beats as first-class, not just offsets.
  </span>
</p>

---

Here’s a Chrome-ready reference implementation for Pulse Clipboard v1 (HTML + Markdown-friendly plain text) that works in two modes:

1. Natural copy: user highlights transcript text and presses Ctrl/Cmd+C → we override clipboard payloads.
2. Copy button: (recommended for mobile Safari later) → uses Async Clipboard API when available.

This example assumes your transcript is rendered with beat/word metadata in the DOM.

---

1) Markup convention in your transcript DOM

Render each word (or small token span) with beat + word index. Word-level is the most reliable way to preserve partial selections.

<div id="transcript" data-pulse-transcript>
  <span class="w" data-beat="b_7Hk2...9Q" data-wi="120">We</span>
  <span class="w" data-beat="b_7Hk2...9Q" data-wi="121">should</span>
  <span class="w" data-beat="b_7Hk2...9Q" data-wi="122">treat</span>
  <span class="w" data-beat="b_7Hk2...9Q" data-wi="123">beats</span>
  <span class="w" data-beat="b_7Hk2...9Q" data-wi="124">as</span>
  <span class="w" data-beat="b_7Hk2...9Q" data-wi="125">first-class,</span>
  <!-- ... -->
</div>

You can also attach optional data-title, data-ts, data-te at a beat container level (or per word if you prefer).

---

2) Copy override (Ctrl/Cmd+C)

This intercepts the copy event and writes both text/plain and text/html.

(function pulseClipboardV1() {
  // Configure these for your environment
  const beatHref = (beatId) => `https://vault.example/b/${encodeURIComponent(beatId)}`;

  // Utility: find all .w nodes that intersect the current selection
  function getSelectedWordNodes(selection, root) {
    if (!selection || selection.isCollapsed) return [];

    const range = selection.getRangeAt(0);
    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, {
      acceptNode(node) {
        if (!(node instanceof HTMLElement)) return NodeFilter.FILTER_SKIP;
        if (!node.classList.contains("w")) return NodeFilter.FILTER_SKIP;

        // Check intersection with the selection range
        const nodeRange = document.createRange();
        nodeRange.selectNodeContents(node);
        const intersects =
          range.compareBoundaryPoints(Range.END_TO_START, nodeRange) < 0 &&
          range.compareBoundaryPoints(Range.START_TO_END, nodeRange) > 0;

        return intersects ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
      },
    });

    const nodes = [];
    while (walker.nextNode()) nodes.push(walker.currentNode);
    return nodes;
  }

  // Group selected words into beat runs with min/max word indices
  function groupByBeat(wordNodes) {
    const runs = [];
    let current = null;

    for (const n of wordNodes) {
      const beat = n.getAttribute("data-beat") || "";
      const wi = parseInt(n.getAttribute("data-wi") || "-1", 10);
      const text = n.textContent || "";

      if (!beat || wi < 0) continue;

      if (!current || current.beat !== beat || wi !== current.lastWi + 1) {
        // Start a new run
        current = {
          beat,
          ws: wi,
          we: wi,
          lastWi: wi,
          parts: [text],
        };
        runs.push(current);
      } else {
        // Extend current run
        current.we = wi;
        current.lastWi = wi;
        current.parts.push(text);
      }
    }

    // Clean up
    for (const r of runs) delete r.lastWi;
    return runs;
  }

  // Turn runs into Pulse Clipboard v1 plain text (Markdown-friendly with footnotes)
  function buildPlainText(runs) {
    const transcript = runs.map(r => r.parts.join(" ")).join(" ").replace(/\s+/g, " ").trim();

    // Footnotes (unique beats, preserve first occurrence order)
    const seen = new Set();
    const footnotes = [];
    let idx = 1;

    for (const r of runs) {
      const key = `${r.beat}|${r.ws}-${r.we}`;
      if (seen.has(key)) continue;
      seen.add(key);

      const url = `${beatHref(r.beat)}#w=${r.ws}-${r.we}`;
      footnotes.push(`${idx}. Beat: ${url}`);
      idx++;
    }

    if (!footnotes.length) return transcript;
    return `${transcript}\n\n${footnotes.join("\n")}\n`;
  }

  // Turn runs into Pulse Clipboard v1 HTML
  function buildHtml(runs) {
    // Minimal HTML; you can add <p> boundaries if you track them in your DOM
    const spans = runs.map(r => {
      const text = escapeHtml(r.parts.join(" ").replace(/\s+/g, " ").trim());
      const href = `${beatHref(r.beat)}#w=${r.ws}-${r.we}`;
      return `<span data-pulse-schema="1" data-pulse-beat="${escapeAttr(r.beat)}" ` +
             `data-pulse-ws="${r.ws}" data-pulse-we="${r.we}" data-pulse-href="${escapeAttr(href)}">` +
             `${text}</span>`;
    });

    return `<p>${spans.join(" ")}</p>`;
  }

  function escapeHtml(s) {
    return s.replace(/[&<>"']/g, c => ({
      "&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"
    }[c]));
  }
  function escapeAttr(s) {
    return escapeHtml(String(s));
  }

  function selectionIsWithinPulseTranscript(sel, root) {
    if (!sel || sel.rangeCount === 0) return false;
    const range = sel.getRangeAt(0);
    const c1 = range.startContainer.nodeType === 1 ? range.startContainer : range.startContainer.parentElement;
    const c2 = range.endContainer.nodeType === 1 ? range.endContainer : range.endContainer.parentElement;
    return !!(c1 && c2 && root.contains(c1) && root.contains(c2));
  }

  document.addEventListener("copy", (e) => {
    const root = document.querySelector("[data-pulse-transcript]");
    if (!root) return;

    const sel = window.getSelection();
    if (!sel || sel.isCollapsed) return;
    if (!selectionIsWithinPulseTranscript(sel, root)) return;

    const wordNodes = getSelectedWordNodes(sel, root);
    if (!wordNodes.length) return;

    const runs = groupByBeat(wordNodes);
    if (!runs.length) return;

    const plain = buildPlainText(runs);
    const html = buildHtml(runs);

    e.clipboardData.setData("text/plain", plain);
    e.clipboardData.setData("text/html", html);
    e.preventDefault();
  });
})();

What this gives you

• Copying any selected transcript region produces:
  • Plain text with beat links as footnotes (Markdown-friendly)
  • HTML with data-pulse-* spans (Pulse-aware richness)

---

3) Paste handler (rehydrate beat spans)

In your Pulse-aware editor/composer, parse text/html if present:

document.addEventListener("paste", (e) => {
  const html = e.clipboardData.getData("text/html");
  const text = e.clipboardData.getData("text/plain");

  if (!html) {
    console.log("Plain paste:", text);
    return;
  }

  const doc = new DOMParser().parseFromString(html, "text/html");
  const nodes = [...doc.querySelectorAll('[data-pulse-schema="1"][data-pulse-beat]')];

  if (!nodes.length) {
    console.log("HTML paste without Pulse spans:", text);
    return;
  }

  const spans = nodes.map(n => ({
    text: n.textContent || "",
    beat: n.getAttribute("data-pulse-beat"),
    ws: n.getAttribute("data-pulse-ws"),
    we: n.getAttribute("data-pulse-we"),
    href: n.getAttribute("data-pulse-href"),
  }));

  console.log("Pulse spans:", spans);

  // TODO: convert spans into your internal model / compose UI.
  // e.g. create a “quoted beats” object for reply composition.
});

---

4) Optional “Copy” button using Async Clipboard API (great for future Safari strategy)

Chrome supports multi-format writes from a click:

async function copyPulsePayload({ plainText, htmlText }) {
  const item = new ClipboardItem({
    "text/plain": new Blob([plainText], { type: "text/plain" }),
    "text/html": new Blob([htmlText], { type: "text/html" }),
  });
  await navigator.clipboard.write([item]);
}

You can reuse the same buildPlainText(runs) and buildHtml(runs) outputs.

---

Notes you’ll care about soon

• Selection fidelity: word-level spans are best. If you only wrap by beat, partial selections inside a beat get ambiguous.
• Sanitization: some paste targets will strip data-*. That’s OK because text/plain already contains URLs.
• Link style: footnotes are the most robust “Markdown-friendly” representation across Slack/GDocs/email.