Topic Core Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build Topic anchoring, render-map translation, server-side highlight resolution, the Topic HTTP API, and the minimal selection/sidebar UI for collaborative annotations.

Architecture: internal/collab owns anchor JSON types plus typed storage reads/writes; internal/render owns source-position metadata, render maps, and server-side anchor resolution; internal/server wires those pieces into JSON APIs and the iframe/sidebar UI. The implementation keeps #4 Incorporation out of scope while preserving the re-anchor contract by making every open non-global Topic resolvable as pre-marker or marker.

Tech Stack: Go 1.26, database/sql with modernc.org/sqlite, github.com/google/uuid, goldmark, golang.org/x/net/html, net/http, vanilla JavaScript, existing templates/static assets.

Reference spec: docs/superpowers/specs/2026-05-11-topic-core-design.html. Also check docs/superpowers/specs/2026-05-10-collaborative-annotations-decisions.md for rationale.

File Structure

internal/collab/
├── anchor.go             # Anchor JSON model, validation, marshal/unmarshal helpers
├── anchor_test.go
├── mutators.go           # MODIFIED: require non-null valid anchors; validate message kinds/body;
│                         #   add InsertTopicWithFirstMessage (single transaction)
├── mutators_test.go      # MODIFIED: anchor and message validation tests; atomicity test
├── migrate.go            # MODIFIED: backfill NULL topics.anchor → '{"kind":"global"}' on startup
├── reader.go             # Read APIs for sidebar/API: open topics and message threads
└── reader_test.go

internal/render/
├── render.go             # MODIFIED: Document gains RenderMap field
├── markdown.go           # MODIFIED: NodeRenderer wrapper emits data-source-* and BlockMaps
├── html.go               # MODIFIED: html.Tokenizer pass over authored HTML; same shape
├── cache.go              # MODIFIED: cache keys include git blob SHA supplied by server
├── rendermap.go          # RenderMap types and translation helpers
├── rendermap_test.go
├── sourcepos.go          # Source-position helpers shared by markdown.go and html.go
├── sourcepos_test.go
├── resolver.go           # HTML-parser-based resolver; emits wb-anchor marks with overlap support
└── resolver_test.go

internal/server/
├── server.go             # MODIFIED: Deps gains Collab store and OperatorUserID
├── handler_content.go    # MODIFIED: render .html through render.Cache; compute SourceSHA via
│                         #   collab.SourceSHA; apply resolver for active topics
├── handler_doc.go        # MODIFIED: shell receives current source path for topics sidebar
├── handler_doc_test.go   # MODIFIED: test server opens collab store
├── topics.go             # Topic JSON API handlers (uses collab.SourceSHA for staleness;
│                         #   InsertTopicWithFirstMessage for atomic create)
├── topics_test.go
├── embed.go              # MODIFIED: ContentMDData gains SourceSHA
├── templates/content_md.html  # MODIFIED: source SHA meta and topics script hook
├── templates/shell.html       # MODIFIED: sidebar pane next to iframe (iframe column first)
├── templates_test.go          # MODIFIED: template assertions
├── static/content.js          # MODIFIED: selection capture inside iframe
├── static/chrome.js           # MODIFIED: sidebar API calls and message handling
├── static/chrome.css          # MODIFIED: topic sidebar layout
└── static/prose.css           # MODIFIED: wb-anchor highlight styling

cmd/wiki-browser/main.go  # MODIFIED: pass Collab and operator into server.Deps

# Playwright-cli smoke script (not committed code; verification only)
docs/superpowers/plans/2026-05-11-topic-core-smoke.sh  # OPTIONAL: scripted playwright-cli smoke

The first four tasks are backend-only and can be reviewed without browser work. Tasks 5-7 wire those primitives into HTTP rendering and JSON endpoints. Task 8 adds the minimal UI and a browser smoke test.

Task 1: Anchor JSON Types and Mutator Validation

Files:

• Create: internal/collab/anchor.go

• Create: internal/collab/anchor_test.go

• Modify: internal/collab/mutators.go

• Modify: internal/collab/mutators_test.go

• Step 1: Write the failing anchor tests

Create internal/collab/anchor_test.go:

package collab_test

import (
	"encoding/json"
	"strings"
	"testing"

	"github.com/getorcha/wiki-browser/internal/collab"
)

func TestAnchor_roundTrip(t *testing.T) {
	cases := []collab.Anchor{
		collab.PreMarkerAnchor{SourceSHA: strings.Repeat("a", 40), Start: 12, End: 18, Quote: "alpha"},
		collab.MarkerAnchor{},
		collab.GlobalAnchor{},
	}
	for _, in := range cases {
		raw, err := collab.MarshalAnchor(in)
		if err != nil {
			t.Fatalf("MarshalAnchor(%T): %v", in, err)
		}
		out, err := collab.UnmarshalAnchor(raw)
		if err != nil {
			t.Fatalf("UnmarshalAnchor(%s): %v", raw, err)
		}
		raw2, err := collab.MarshalAnchor(out)
		if err != nil {
			t.Fatalf("MarshalAnchor(second): %v", err)
		}
		if string(raw2) != string(raw) {
			t.Errorf("round trip %T = %s, want %s", in, raw2, raw)
		}
	}
}

func TestAnchor_validation(t *testing.T) {
	for name, a := range map[string]collab.Anchor{
		"pre-marker sha":   collab.PreMarkerAnchor{SourceSHA: "short", Start: 1, End: 2, Quote: "q"},
		"pre-marker range": collab.PreMarkerAnchor{SourceSHA: strings.Repeat("a", 40), Start: 2, End: 2, Quote: "q"},
		"pre-marker quote": collab.PreMarkerAnchor{SourceSHA: strings.Repeat("a", 40), Start: 1, End: 2},
	} {
		if err := collab.ValidateAnchor(a); err == nil {
			t.Errorf("%s: expected validation error", name)
		}
	}
}

func TestUnmarshalAnchor_rejectsUnknownKindAndExtraFields(t *testing.T) {
	for _, raw := range []string{
		`{"kind":"lost"}`,
		`{"kind":"marker","start":1}`,
		`{"kind":"global","quote":"x"}`,
		`{"kind":"pre-marker","source_sha":"` + strings.Repeat("a", 40) + `","start":1,"end":2}`,
	} {
		if _, err := collab.UnmarshalAnchor(json.RawMessage(raw)); err == nil {
			t.Errorf("UnmarshalAnchor(%s) succeeded, want error", raw)
		}
	}
}

• Step 2: Add mutator validation tests

Append to internal/collab/mutators_test.go:

func TestInsertTopic_requiresValidAnchor(t *testing.T) {
	s := openStore(t)
	if _, err := s.InsertTopic(collab.NewTopic{ID: "missing", SourcePath: "a.md", CreatedBy: "alice"}); err == nil {
		t.Fatal("InsertTopic without anchor succeeded, want error")
	}

	raw, err := collab.MarshalAnchor(collab.GlobalAnchor{})
	if err != nil {
		t.Fatal(err)
	}
	if _, err := s.InsertTopic(collab.NewTopic{
		ID: "global", SourcePath: "a.md", Anchor: raw, CreatedBy: "alice",
	}); err != nil {
		t.Fatalf("InsertTopic with global anchor: %v", err)
	}
}

func TestInsertMessage_validatesKindAndBody(t *testing.T) {
	s := openStore(t)
	raw, err := collab.MarshalAnchor(collab.GlobalAnchor{})
	if err != nil {
		t.Fatal(err)
	}
	if _, err := s.InsertTopic(collab.NewTopic{ID: "t1", SourcePath: "a.md", Anchor: raw, CreatedBy: "alice"}); err != nil {
		t.Fatal(err)
	}

	for _, m := range []collab.NewMessage{
		{ID: "empty", TopicID: "t1", Kind: "human", AuthorUserID: ptr("alice")},
		{ID: "bad-kind", TopicID: "t1", Kind: "system", Body: "body", AuthorUserID: ptr("alice")},
		{ID: "bad-human", TopicID: "t1", Kind: "human", Body: "body"},
		{ID: "bad-proposal", TopicID: "t1", Kind: "agent-proposal", Body: "body", AuthorUserID: ptr("alice")},
	} {
		if _, err := s.InsertMessage(m); err == nil {
			t.Errorf("InsertMessage(%s) succeeded, want error", m.ID)
		}
	}
}

func TestInsertTopicWithFirstMessage_atomic(t *testing.T) {
	s := openStore(t)
	in := collab.NewTopicWithFirstMessage{
		TopicID: "t1", SourcePath: "a.md", Anchor: globalAnchor(t), CreatedBy: "alice",
		FirstMessageID: "m1", FirstMessageBody: "first",
	}
	if err := s.InsertTopicWithFirstMessage(in); err != nil {
		t.Fatalf("InsertTopicWithFirstMessage: %v", err)
	}

	// A failure after the topic insert must roll back the topic too. Reuse
	// an existing message ID so the topic insert succeeds and the message
	// insert fails on the topic_messages primary key.
	bad := in
	bad.TopicID = "t2"
	bad.FirstMessageID = "m1"
	bad.FirstMessageBody = "second"
	if err := s.InsertTopicWithFirstMessage(bad); err == nil {
		t.Fatal("expected error for duplicate first message ID")
	}
	row := s.RawDBForTest().QueryRow(`SELECT COUNT(*) FROM topics WHERE id = ?`, "t2")
	var n int
	if err := row.Scan(&n); err != nil {
		t.Fatal(err)
	}
	if n != 0 {
		t.Errorf("rolled-back topic still present: count=%d", n)
	}
}

• Step 3: Run tests to verify they fail

Run: go test ./internal/collab/... -run 'TestAnchor|TestInsertTopic_requiresValidAnchor|TestInsertMessage_validatesKindAndBody' -v

Expected: FAIL because Anchor, MarshalAnchor, UnmarshalAnchor, ValidateAnchor, and stricter mutator validation do not exist.

• Step 4: Implement anchor.go

Create internal/collab/anchor.go:

package collab

import (
	"bytes"
	"encoding/json"
	"fmt"
)

type Anchor interface {
	AnchorKind() string
}

type PreMarkerAnchor struct {
	SourceSHA string `json:"source_sha"`
	Start     int    `json:"start"`
	End       int    `json:"end"`
	Quote     string `json:"quote"`
}

func (PreMarkerAnchor) AnchorKind() string { return "pre-marker" }

type MarkerAnchor struct{}

func (MarkerAnchor) AnchorKind() string { return "marker" }

type GlobalAnchor struct{}

func (GlobalAnchor) AnchorKind() string { return "global" }

func MarshalAnchor(a Anchor) (json.RawMessage, error) {
	if err := ValidateAnchor(a); err != nil {
		return nil, err
	}
	switch v := a.(type) {
	case PreMarkerAnchor:
		return json.Marshal(struct {
			Kind string `json:"kind"`
			PreMarkerAnchor
		}{Kind: v.AnchorKind(), PreMarkerAnchor: v})
	case MarkerAnchor:
		return json.Marshal(struct {
			Kind string `json:"kind"`
		}{Kind: v.AnchorKind()})
	case GlobalAnchor:
		return json.Marshal(struct {
			Kind string `json:"kind"`
		}{Kind: v.AnchorKind()})
	default:
		return nil, fmt.Errorf("collab anchor: unsupported type %T", a)
	}
}

func UnmarshalAnchor(raw json.RawMessage) (Anchor, error) {
	dec := json.NewDecoder(bytes.NewReader(raw))
	dec.DisallowUnknownFields()
	var head struct {
		Kind string `json:"kind"`
	}
	if err := json.Unmarshal(raw, &head); err != nil {
		return nil, fmt.Errorf("collab anchor: decode kind: %w", err)
	}
	switch head.Kind {
	case "pre-marker":
		var v struct {
			Kind      string `json:"kind"`
			SourceSHA string `json:"source_sha"`
			Start     int    `json:"start"`
			End       int    `json:"end"`
			Quote     string `json:"quote"`
		}
		if err := dec.Decode(&v); err != nil {
			return nil, fmt.Errorf("collab anchor: decode pre-marker: %w", err)
		}
		a := PreMarkerAnchor{SourceSHA: v.SourceSHA, Start: v.Start, End: v.End, Quote: v.Quote}
		return a, ValidateAnchor(a)
	case "marker":
		var v struct {
			Kind string `json:"kind"`
		}
		if err := dec.Decode(&v); err != nil {
			return nil, fmt.Errorf("collab anchor: decode marker: %w", err)
		}
		return MarkerAnchor{}, nil
	case "global":
		var v struct {
			Kind string `json:"kind"`
		}
		if err := dec.Decode(&v); err != nil {
			return nil, fmt.Errorf("collab anchor: decode global: %w", err)
		}
		return GlobalAnchor{}, nil
	default:
		return nil, fmt.Errorf("collab anchor: unknown kind %q", head.Kind)
	}
}

func ValidateAnchor(a Anchor) error {
	switch v := a.(type) {
	case PreMarkerAnchor:
		if len(v.SourceSHA) != 40 {
			return fmt.Errorf("collab anchor: pre-marker source_sha must be 40 chars")
		}
		if v.Start < 0 || v.End <= v.Start {
			return fmt.Errorf("collab anchor: pre-marker range must be non-empty")
		}
		if v.Quote == "" {
			return fmt.Errorf("collab anchor: pre-marker quote required")
		}
		return nil
	case MarkerAnchor:
		return nil
	case GlobalAnchor:
		return nil
	case nil:
		return fmt.Errorf("collab anchor: required")
	default:
		return fmt.Errorf("collab anchor: unsupported type %T", a)
	}
}

• Step 5: Update mutator inputs and validation

In internal/collab/mutators.go, change NewTopic.Anchor from *string to json.RawMessage and import encoding/json plus strings.

Replace the start of InsertTopic validation with:

	if t.ID == "" || t.SourcePath == "" || t.CreatedBy == "" {
		return "", fmt.Errorf("collab.InsertTopic: id/source_path/created_by required")
	}
	if len(t.Anchor) == 0 {
		return "", fmt.Errorf("collab.InsertTopic: anchor required")
	}
	if _, err := UnmarshalAnchor(t.Anchor); err != nil {
		return "", fmt.Errorf("collab.InsertTopic: %w", err)
	}

In the SQL insert, pass string(t.Anchor) instead of t.Anchor.

Add this helper near InsertMessage:

const maxMessageBodyBytes = 64 << 10

func validateMessage(m NewMessage) error {
	if m.ID == "" || m.TopicID == "" || m.Kind == "" {
		return fmt.Errorf("collab.InsertMessage: id/topic_id/kind required")
	}
	if strings.TrimSpace(m.Body) == "" {
		return fmt.Errorf("collab.InsertMessage: body required")
	}
	if len([]byte(m.Body)) > maxMessageBodyBytes {
		return fmt.Errorf("collab.InsertMessage: body exceeds 64 KiB")
	}
	switch m.Kind {
	case "human":
		if m.AuthorUserID == nil || *m.AuthorUserID == "" || m.ProposalID != nil {
			return fmt.Errorf("collab.InsertMessage: human messages require author_user_id and no proposal_id")
		}
	case "agent-proposal":
		if m.AuthorUserID != nil || m.ProposalID == nil || *m.ProposalID == "" {
			return fmt.Errorf("collab.InsertMessage: agent-proposal messages require proposal_id and no author_user_id")
		}
	default:
		return fmt.Errorf("collab.InsertMessage: unsupported kind %q", m.Kind)
	}
	return nil
}

Replace the first validation block in InsertMessage with:

	if err := validateMessage(m); err != nil {
		return "", err
	}

• Step 6: Add InsertTopicWithFirstMessage (single transaction)

Topic creation must be atomic — a Topic without its required first message is an invariant violation (sidebar previews assume one exists). Add this to internal/collab/mutators.go:

// NewTopicWithFirstMessage creates a Topic and its first message in one
// transaction so a partial failure leaves no rows behind.
type NewTopicWithFirstMessage struct {
	TopicID          string
	SourcePath       string
	Anchor           json.RawMessage
	CreatedBy        string
	FirstMessageID   string
	FirstMessageBody string
}

func (s *Store) InsertTopicWithFirstMessage(in NewTopicWithFirstMessage) error {
	if in.TopicID == "" || in.SourcePath == "" || in.CreatedBy == "" ||
		in.FirstMessageID == "" {
		return fmt.Errorf("collab.InsertTopicWithFirstMessage: required fields missing")
	}
	if len(in.Anchor) == 0 {
		return fmt.Errorf("collab.InsertTopicWithFirstMessage: anchor required")
	}
	if _, err := UnmarshalAnchor(in.Anchor); err != nil {
		return fmt.Errorf("collab.InsertTopicWithFirstMessage: %w", err)
	}
	if _, err := ValidateSourcePath(in.SourcePath); err != nil {
		return fmt.Errorf("collab.InsertTopicWithFirstMessage: %w", err)
	}
	createdBy := in.CreatedBy
	msg := NewMessage{
		ID: in.FirstMessageID, TopicID: in.TopicID, Kind: "human",
		Body: in.FirstMessageBody, AuthorUserID: &createdBy,
	}
	if err := validateMessage(msg); err != nil {
		return err
	}

	return s.send(func(db *sql.DB) error {
		tx, err := db.Begin()
		if err != nil {
			return err
		}
		if _, err := tx.Exec(
			`INSERT INTO topics(id, source_path, anchor, created_at, created_by, updated_at)
			 VALUES (?, ?, ?, unixepoch(), ?, unixepoch())`,
			in.TopicID, in.SourcePath, string(in.Anchor), in.CreatedBy,
		); err != nil {
			_ = tx.Rollback()
			return fmt.Errorf("insert topic: %w", err)
		}
		if _, err := tx.Exec(
			`INSERT INTO topic_messages(
			   id, topic_id, kind, body, author_user_id, proposal_id, sequence, created_at
			 ) VALUES (?, ?, 'human', ?, ?, NULL, 1, unixepoch())`,
			msg.ID, msg.TopicID, msg.Body, msg.AuthorUserID,
		); err != nil {
			_ = tx.Rollback()
			return fmt.Errorf("insert first message: %w", err)
		}
		return tx.Commit()
	})
}

The sequence is hard-coded to 1 because this is by definition the first message; the funnel ensures no other writer can interleave.

• Step 7: Backfill NULL anchors on startup

Pre-existing dev databases may have rows with topics.anchor = NULL. After the validation tightening, the reader API in Task 2 will error on those rows. Add an idempotent backfill in internal/collab/collab.go, called from Open after Migrate:

// backfillNullAnchors converts legacy rows with anchor IS NULL to a
// '{"kind":"global"}' anchor so the typed reader never sees NULL.
func backfillNullAnchors(db *sql.DB) error {
	_, err := db.Exec(
		`UPDATE topics
		   SET anchor = '{"kind":"global"}'
		 WHERE anchor IS NULL`)
	return err
}

Call it in Open right after bootstrapOperator(...):

	if err := backfillNullAnchors(db); err != nil {
		_ = db.Close()
		return nil, fmt.Errorf("backfill anchors: %w", err)
	}

• Step 8: Update existing tests that create topics

In every internal/collab/*_test.go call to InsertTopic, create a valid anchor first:

func globalAnchor(t *testing.T) json.RawMessage {
	t.Helper()
	raw, err := collab.MarshalAnchor(collab.GlobalAnchor{})
	if err != nil {
		t.Fatal(err)
	}
	return raw
}

Use Anchor: globalAnchor(t) for topics whose anchor is irrelevant to the test. Put this helper in internal/collab/mutators_test.go; if another test file needs it, keep package collab_test and call it directly.

• Step 9: Run tests to verify they pass

Run: go test ./internal/collab/... -v

Expected: PASS for all internal/collab tests, including TestInsertTopicWithFirstMessage_atomic.

• Step 10: Commit

git add internal/collab/anchor.go internal/collab/anchor_test.go internal/collab/mutators.go internal/collab/mutators_test.go internal/collab/collab.go internal/collab/*_test.go
git commit -m "wiki-browser: collab — validate topic anchors and atomic topic+message insert"

Task 2: Read APIs for Topics and Messages

Files:

• Create: internal/collab/reader.go

• Create: internal/collab/reader_test.go

• Step 1: Write the failing reader tests

Create internal/collab/reader_test.go:

package collab_test

import (
	"testing"

	"github.com/getorcha/wiki-browser/internal/collab"
)

func TestListOpenTopicsForSource(t *testing.T) {
	s := openStore(t)
	global := globalAnchor(t)
	if _, err := s.InsertTopic(collab.NewTopic{ID: "t1", SourcePath: "a.md", Anchor: global, CreatedBy: "alice"}); err != nil {
		t.Fatal(err)
	}
	if _, err := s.InsertTopic(collab.NewTopic{ID: "t2", SourcePath: "b.md", Anchor: global, CreatedBy: "alice"}); err != nil {
		t.Fatal(err)
	}
	if _, err := s.InsertMessage(collab.NewMessage{ID: "m1", TopicID: "t1", Kind: "human", Body: "first message", AuthorUserID: ptr("alice")}); err != nil {
		t.Fatal(err)
	}
	got, err := s.ListOpenTopicsForSource("a.md")
	if err != nil {
		t.Fatal(err)
	}
	if len(got) != 1 {
		t.Fatalf("len = %d, want 1: %#v", len(got), got)
	}
	if got[0].ID != "t1" || got[0].FirstMessagePreview != "first message" || got[0].MessageCount != 1 {
		t.Errorf("topic = %#v", got[0])
	}
}

func TestListMessagesOrdersBySequence(t *testing.T) {
	s := openStore(t)
	if _, err := s.InsertTopic(collab.NewTopic{ID: "t1", SourcePath: "a.md", Anchor: globalAnchor(t), CreatedBy: "alice"}); err != nil {
		t.Fatal(err)
	}
	for _, body := range []string{"one", "two"} {
		if _, err := s.InsertMessage(collab.NewMessage{ID: "m-" + body, TopicID: "t1", Kind: "human", Body: body, AuthorUserID: ptr("alice")}); err != nil {
			t.Fatal(err)
		}
	}
	got, err := s.ListMessages("t1")
	if err != nil {
		t.Fatal(err)
	}
	if len(got) != 2 || got[0].Body != "one" || got[1].Body != "two" {
		t.Errorf("messages = %#v", got)
	}
}

• Step 2: Run tests to verify they fail

Run: go test ./internal/collab/... -run 'TestListOpenTopicsForSource|TestListMessagesOrdersBySequence' -v

Expected: FAIL because ListOpenTopicsForSource and ListMessages do not exist.

• Step 3: Implement reader.go

Create internal/collab/reader.go:

package collab

import (
	"encoding/json"
	"fmt"
)

type TopicSummary struct {
	ID                  string          `json:"id"`
	SourcePath          string          `json:"source_path"`
	Anchor              json.RawMessage `json:"anchor"`
	CreatedBy           string          `json:"created_by"`
	CreatedAt           int64           `json:"created_at"`
	UpdatedAt           int64           `json:"updated_at"`
	FirstMessagePreview string          `json:"first_message_preview"`
	MessageCount         int             `json:"message_count"`
}

type TopicMessage struct {
	ID           string  `json:"id"`
	TopicID      string  `json:"topic_id"`
	Kind         string  `json:"kind"`
	Body         string  `json:"body"`
	AuthorUserID *string `json:"author_user_id,omitempty"`
	ProposalID   *string `json:"proposal_id,omitempty"`
	Sequence     int     `json:"sequence"`
	CreatedAt    int64   `json:"created_at"`
}

func (s *Store) ListOpenTopicsForSource(sourcePath string) ([]TopicSummary, error) {
	if _, err := ValidateSourcePath(sourcePath); err != nil {
		return nil, fmt.Errorf("collab.ListOpenTopicsForSource: %w", err)
	}
	rows, err := s.db.Query(
		`SELECT t.id, t.source_path, t.anchor, t.created_by, t.created_at, t.updated_at,
		        COALESCE((SELECT m.body FROM topic_messages m WHERE m.topic_id = t.id ORDER BY m.sequence LIMIT 1), ''),
		        (SELECT COUNT(*) FROM topic_messages m WHERE m.topic_id = t.id)
		   FROM topics t
		  WHERE t.source_path = ?
		    AND t.incorporated_at IS NULL
		    AND t.discarded_at IS NULL
		  ORDER BY t.updated_at DESC, t.created_at DESC, t.id`,
		sourcePath,
	)
	if err != nil {
		return nil, err
	}
	defer rows.Close()
	var out []TopicSummary
	for rows.Next() {
		var raw string
		var t TopicSummary
		if err := rows.Scan(&t.ID, &t.SourcePath, &raw, &t.CreatedBy, &t.CreatedAt, &t.UpdatedAt, &t.FirstMessagePreview, &t.MessageCount); err != nil {
			return nil, err
		}
		if _, err := UnmarshalAnchor(json.RawMessage(raw)); err != nil {
			return nil, fmt.Errorf("collab.ListOpenTopicsForSource: topic %s: %w", t.ID, err)
		}
		t.Anchor = json.RawMessage(raw)
		out = append(out, t)
	}
	return out, rows.Err()
}

func (s *Store) ListMessages(topicID string) ([]TopicMessage, error) {
	if topicID == "" {
		return nil, fmt.Errorf("collab.ListMessages: topic id required")
	}
	rows, err := s.db.Query(
		`SELECT id, topic_id, kind, body, author_user_id, proposal_id, sequence, created_at
		   FROM topic_messages
		  WHERE topic_id = ?
		  ORDER BY sequence`,
		topicID,
	)
	if err != nil {
		return nil, err
	}
	defer rows.Close()
	var out []TopicMessage
	for rows.Next() {
		var m TopicMessage
		if err := rows.Scan(&m.ID, &m.TopicID, &m.Kind, &m.Body, &m.AuthorUserID, &m.ProposalID, &m.Sequence, &m.CreatedAt); err != nil {
			return nil, err
		}
		out = append(out, m)
	}
	return out, rows.Err()
}

• Step 4: Run tests to verify they pass

Run: go test ./internal/collab/... -run 'TestListOpenTopicsForSource|TestListMessagesOrdersBySequence' -v

Expected: PASS.

• Step 5: Commit

git add internal/collab/reader.go internal/collab/reader_test.go
git commit -m "wiki-browser: collab — add topic read APIs"

Task 3: RenderMap Translation Helpers

Files:

• Create: internal/render/rendermap.go

• Create: internal/render/rendermap_test.go

• Modify: internal/render/render.go

• Step 1: Write the failing tests

Create internal/render/rendermap_test.go:

package render_test

import (
	"testing"

	"github.com/getorcha/wiki-browser/internal/render"
)

func TestRenderedToSource_linearAndEntityExpansion(t *testing.T) {
	m := render.RenderMap{Blocks: []render.BlockMap{{
		SourceStart: 10,
		SourceEnd:   30,
		Segments: []render.Segment{
			{RenderedStart: 0, RenderedEnd: 5, SourceStart: 10, SourceEnd: 15},
			{RenderedStart: 5, RenderedEnd: 6, SourceStart: 15, SourceEnd: 20},
			{RenderedStart: 6, RenderedEnd: 10, SourceStart: 20, SourceEnd: 24},
		},
	}}}
	got, err := m.RenderedToSource(10, 30, 4, 7)
	if err != nil {
		t.Fatal(err)
	}
	if got.Start != 14 || got.End != 21 {
		t.Errorf("range = %#v, want [14,21)", got)
	}
}

func TestRenderedToSource_rejectsNonSource(t *testing.T) {
	m := render.RenderMap{Blocks: []render.BlockMap{{
		SourceStart: 0,
		SourceEnd:   10,
		Segments: []render.Segment{
			{RenderedStart: 0, RenderedEnd: 2, SourceStart: 0, SourceEnd: 2},
			{RenderedStart: 2, RenderedEnd: 4, NonSource: true},
		},
	}}}
	if _, err := m.RenderedToSource(0, 10, 1, 3); err != render.ErrNonSourceSelection {
		t.Fatalf("err = %v, want ErrNonSourceSelection", err)
	}
}

func TestSourceToRendered(t *testing.T) {
	m := render.RenderMap{Blocks: []render.BlockMap{{
		SourceStart: 10,
		SourceEnd:   30,
		Segments: []render.Segment{
			{RenderedStart: 0, RenderedEnd: 5, SourceStart: 10, SourceEnd: 15},
			{RenderedStart: 5, RenderedEnd: 6, SourceStart: 15, SourceEnd: 20},
			{RenderedStart: 6, RenderedEnd: 10, SourceStart: 20, SourceEnd: 24},
		},
	}}}
	got := m.SourceToRendered(14, 21)
	if len(got) != 1 {
		t.Fatalf("len = %d, want 1: %#v", len(got), got)
	}
	if got[0].RenderedStart != 4 || got[0].RenderedEnd != 7 {
		t.Errorf("interval = %#v, want rendered [4,7)", got[0])
	}
}

• Step 2: Run tests to verify they fail

Run: go test ./internal/render/... -run 'TestRenderedToSource|TestSourceToRendered' -v

Expected: FAIL because render-map types and helpers do not exist.

• Step 3: Implement rendermap.go and extend Document

Create internal/render/rendermap.go:

package render

import (
	"errors"
	"fmt"
)

var (
	ErrUnknownBlock        = errors.New("render: unknown block")
	ErrNonSourceSelection  = errors.New("render: selection overlaps non-source content")
	ErrInvalidRenderedRange = errors.New("render: invalid rendered range")
)

type RenderMap struct {
	Blocks []BlockMap
}

type BlockMap struct {
	SourceStart int
	SourceEnd   int
	Segments    []Segment
}

type Segment struct {
	RenderedStart int
	RenderedEnd   int
	SourceStart   int
	SourceEnd     int
	NonSource     bool
}

type SourceRange struct {
	Start int
	End   int
}

type RenderedInterval struct {
	BlockSourceStart int
	BlockSourceEnd   int
	RenderedStart    int
	RenderedEnd      int
}

func (m RenderMap) Block(sourceStart, sourceEnd int) (*BlockMap, bool) {
	for i := range m.Blocks {
		b := &m.Blocks[i]
		if b.SourceStart == sourceStart && b.SourceEnd == sourceEnd {
			return b, true
		}
	}
	return nil, false
}

func (m RenderMap) RenderedToSource(blockStart, blockEnd, renderedStart, renderedEnd int) (SourceRange, error) {
	if renderedStart < 0 || renderedEnd <= renderedStart {
		return SourceRange{}, ErrInvalidRenderedRange
	}
	b, ok := m.Block(blockStart, blockEnd)
	if !ok {
		return SourceRange{}, ErrUnknownBlock
	}
	var out SourceRange
	have := false
	for _, s := range b.Segments {
		if renderedEnd <= s.RenderedStart || renderedStart >= s.RenderedEnd {
			continue
		}
		if s.NonSource {
			return SourceRange{}, ErrNonSourceSelection
		}
		partStart := maxInt(renderedStart, s.RenderedStart)
		partEnd := minInt(renderedEnd, s.RenderedEnd)
		srcStart, srcEnd := segmentRenderedToSource(s, partStart, partEnd)
		if !have {
			out = SourceRange{Start: srcStart, End: srcEnd}
			have = true
		} else {
			out.Start = minInt(out.Start, srcStart)
			out.End = maxInt(out.End, srcEnd)
		}
	}
	if !have {
		return SourceRange{}, ErrInvalidRenderedRange
	}
	return out, nil
}

func (m RenderMap) SourceToRendered(sourceStart, sourceEnd int) []RenderedInterval {
	var out []RenderedInterval
	for _, b := range m.Blocks {
		for _, s := range b.Segments {
			if s.NonSource || sourceEnd <= s.SourceStart || sourceStart >= s.SourceEnd {
				continue
			}
			partStart := maxInt(sourceStart, s.SourceStart)
			partEnd := minInt(sourceEnd, s.SourceEnd)
			rs, re := segmentSourceToRendered(s, partStart, partEnd)
			out = append(out, RenderedInterval{
				BlockSourceStart: b.SourceStart,
				BlockSourceEnd:   b.SourceEnd,
				RenderedStart:    rs,
				RenderedEnd:      re,
			})
		}
	}
	return out
}

func segmentRenderedToSource(s Segment, renderedStart, renderedEnd int) (int, int) {
	renderedLen := s.RenderedEnd - s.RenderedStart
	sourceLen := s.SourceEnd - s.SourceStart
	if renderedLen == sourceLen {
		return s.SourceStart + (renderedStart - s.RenderedStart), s.SourceStart + (renderedEnd - s.RenderedStart)
	}
	return s.SourceStart, s.SourceEnd
}

func segmentSourceToRendered(s Segment, sourceStart, sourceEnd int) (int, int) {
	renderedLen := s.RenderedEnd - s.RenderedStart
	sourceLen := s.SourceEnd - s.SourceStart
	if renderedLen == sourceLen {
		return s.RenderedStart + (sourceStart - s.SourceStart), s.RenderedStart + (sourceEnd - s.SourceStart)
	}
	return s.RenderedStart, s.RenderedEnd
}

func (m RenderMap) Validate() error {
	for _, b := range m.Blocks {
		if b.SourceEnd <= b.SourceStart {
			return fmt.Errorf("render map: invalid block range [%d,%d)", b.SourceStart, b.SourceEnd)
		}
	}
	return nil
}

func minInt(a, b int) int {
	if a < b {
		return a
	}
	return b
}

func maxInt(a, b int) int {
	if a > b {
		return a
	}
	return b
}

All rendered offsets in RenderMap are UTF-8 byte counts of rendered text, not Go runes and not JavaScript UTF-16 code units. That keeps them directly comparable with Source byte offsets and avoids drift for non-ASCII text. The browser must compute rendered offsets with TextEncoder, and tests must include at least one selection containing non-ASCII text.

In internal/render/render.go, extend Document:

type Document struct {
	HTML       string
	PlainText  string
	Title      string
	HasMermaid bool
	RenderMap  RenderMap
}

SourceSHA is deliberately not on Document. The hash is the git blob SHA (see internal/collab/hashes.go), and the handler computes it via collab.SourceSHA(d.Root, relPath) where the repo root is available for .gitattributes lookup. The render cache still must key entries by this SHA: the current mtime+size cache key can miss same-second resaves, and serving a stale RenderMap with a fresh source_sha would create anchors against the wrong source bytes.

• Step 4: Run tests to verify they pass

Run: go test ./internal/render/... -run 'TestRenderedToSource|TestSourceToRendered' -v

Expected: PASS.

• Step 5: Commit

git add internal/render/render.go internal/render/rendermap.go internal/render/rendermap_test.go
git commit -m "wiki-browser: render — add render map translation helpers"

Task 4: Source-Position Metadata in Rendered Documents

Files:

• Create: internal/render/sourcepos.go
• Create: internal/render/sourcepos_test.go
• Modify: internal/render/markdown.go
• Modify: internal/render/html.go
• Modify: internal/render/render.go
• Modify: internal/render/cache.go
• Modify: internal/render/cache_test.go
• Modify: internal/server/handler_content.go
• Modify: internal/server/handler_content_test.go
• Modify: internal/server/embed.go
• Modify: internal/server/templates/content_md.html

The previous version of this task used regexes over the rendered output to inject data-source-* attributes and to build the render map. That can't recognize fenced code blocks, setext headings, lists, tables, blockquotes, or HTML blocks, and the per-block rendered/source mapping drifted from goldmark's actual output. This task uses the spec's approach instead: a goldmark NodeRenderer wrapper that reads each block node's Lines() segments, and an x/net/html Tokenizer pass over authored HTML.

• Step 1: Write source-position tests

Create internal/render/sourcepos_test.go:

package render_test

import (
	"os"
	"path/filepath"
	"strings"
	"testing"

	"github.com/getorcha/wiki-browser/internal/render"
)

func TestRenderMarkdown_emitsSourcePositionsAndMap(t *testing.T) {
	dir := t.TempDir()
	p := filepath.Join(dir, "a.md")
	src := "# Title\n\nAlpha & beta\n\n- one\n- two\n"
	if err := os.WriteFile(p, []byte(src), 0o644); err != nil {
		t.Fatal(err)
	}
	doc, err := render.Render(p)
	if err != nil {
		t.Fatal(err)
	}

	// Heading is the first source block and its rendered <h1> must carry
	// matching data-source-* attributes anchored at offset 0.
	if !strings.Contains(doc.HTML, `data-source-start="0"`) {
		t.Fatalf("missing data-source-start in HTML: %s", doc.HTML)
	}

	// Heading + paragraph + list = at least 3 block maps. The list itself
	// counts as one block; list items aren't a separate block map.
	if len(doc.RenderMap.Blocks) < 3 {
		t.Fatalf("render map blocks = %d, want at least 3", len(doc.RenderMap.Blocks))
	}

	// Each BlockMap's SourceStart/SourceEnd must match an attribute pair
	// in the rendered HTML — the resolver relies on that correspondence.
	for _, b := range doc.RenderMap.Blocks {
		want := `data-source-start="` + itoa(b.SourceStart) + `" data-source-end="` + itoa(b.SourceEnd) + `"`
		if !strings.Contains(doc.HTML, want) {
			t.Errorf("BlockMap [%d,%d) has no matching HTML attrs", b.SourceStart, b.SourceEnd)
		}
	}
}

func TestRenderMarkdown_renderMapMapsSelectionToSource(t *testing.T) {
	// End-to-end: real renderer + real RenderMap.RenderedToSource on a known
	// phrase. Catches drift between segments stored in the map and goldmark's
	// actual rendered output.
	dir := t.TempDir()
	src := "Alpha bravo charlie\n"
	p := filepath.Join(dir, "a.md")
	if err := os.WriteFile(p, []byte(src), 0o644); err != nil {
		t.Fatal(err)
	}
	doc, err := render.Render(p)
	if err != nil {
		t.Fatal(err)
	}
	if len(doc.RenderMap.Blocks) == 0 {
		t.Fatal("no blocks")
	}
	b := doc.RenderMap.Blocks[0]
	// "bravo" lives at rendered offset 6..11 inside the paragraph.
	got, err := doc.RenderMap.RenderedToSource(b.SourceStart, b.SourceEnd, 6, 11)
	if err != nil {
		t.Fatal(err)
	}
	if string(readSlice(t, p, got.Start, got.End)) != "bravo" {
		t.Errorf("got source slice %q, want %q", readSlice(t, p, got.Start, got.End), "bravo")
	}
}

func TestRenderMarkdown_renderMapUsesUTF8ByteOffsets(t *testing.T) {
	dir := t.TempDir()
	src := "éclair bravo\n"
	p := filepath.Join(dir, "unicode.md")
	if err := os.WriteFile(p, []byte(src), 0o644); err != nil {
		t.Fatal(err)
	}
	doc, err := render.Render(p)
	if err != nil {
		t.Fatal(err)
	}
	b := doc.RenderMap.Blocks[0]
	// Rendered offsets are UTF-8 byte offsets. "éclair " is 8 bytes.
	got, err := doc.RenderMap.RenderedToSource(b.SourceStart, b.SourceEnd, 8, 13)
	if err != nil {
		t.Fatal(err)
	}
	if string(readSlice(t, p, got.Start, got.End)) != "bravo" {
		t.Errorf("got source slice %q, want bravo", readSlice(t, p, got.Start, got.End))
	}
}

func TestRenderHTML_emitsSourcePositionsAndMap(t *testing.T) {
	dir := t.TempDir()
	p := filepath.Join(dir, "a.html")
	src := "<!doctype html><html><head><title>T</title></head><body><h1>Title</h1><p>A &amp; B</p></body></html>"
	if err := os.WriteFile(p, []byte(src), 0o644); err != nil {
		t.Fatal(err)
	}
	doc, err := render.Render(p)
	if err != nil {
		t.Fatal(err)
	}
	if !strings.Contains(doc.HTML, `data-source-start=`) || !strings.Contains(doc.HTML, `data-source-end=`) {
		t.Fatalf("missing source attrs: %s", doc.HTML)
	}
	if len(doc.RenderMap.Blocks) < 2 {
		t.Fatalf("render map blocks = %d, want at least 2", len(doc.RenderMap.Blocks))
	}
}

func itoa(n int) string { return strconv.Itoa(n) } // add strconv import
func readSlice(t *testing.T, path string, start, end int) []byte {
	t.Helper()
	b, err := os.ReadFile(path)
	if err != nil {
		t.Fatal(err)
	}
	return b[start:end]
}

Add a cache regression test in internal/render/cache_test.go:

func TestCacheGetForSourceMissesWhenSourceSHAChanges(t *testing.T) {
	dir := t.TempDir()
	p := filepath.Join(dir, "a.md")
	if err := os.WriteFile(p, []byte("# One\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	c := render.NewCache(4 << 20)
	first, err := c.GetForSource(p, strings.Repeat("1", 40))
	if err != nil {
		t.Fatal(err)
	}
	if err := os.WriteFile(p, []byte("# Two\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	second, err := c.GetForSource(p, strings.Repeat("2", 40))
	if err != nil {
		t.Fatal(err)
	}
	if first == second || second.Title != "Two" {
		t.Fatalf("cache reused stale document: first=%q second=%q", first.Title, second.Title)
	}
}

Modify internal/server/handler_content_test.go by replacing TestContentHTML_servesByteIdentical with:

func TestContentHTML_rendersThroughPipeline(t *testing.T) {
	ts, root := newTestServer(t)
	authored := "<!doctype html><html><body><h1>hi</h1></body></html>"
	p := filepath.Join(root, "raw.html")
	if err := os.WriteFile(p, []byte(authored), 0o644); err != nil {
		t.Fatal(err)
	}
	resp, err := http.Get(ts.URL + "/content/raw.html")
	if err != nil {
		t.Fatal(err)
	}
	defer resp.Body.Close()
	body := readAll(t, resp)
	if !strings.Contains(body, `data-source-start=`) {
		t.Errorf("authored HTML should pass through render pipeline; body=%s", body)
	}
}

func TestContentHTML_rawStillByteIdentical(t *testing.T) {
	// ?raw=1 keeps the existing contract: byte-identical raw source.
	ts, _ := newTestServer(t)
	resp, err := http.Get(ts.URL + "/content/raw.html?raw=1")
	if err != nil {
		t.Fatal(err)
	}
	defer resp.Body.Close()
	body := readAll(t, resp)
	if strings.Contains(body, `data-source-start=`) {
		t.Errorf("raw served output should not be annotated: %s", body)
	}
}

• Step 2: Run tests to verify they fail

Run: go test ./internal/render/... ./internal/server/... -run 'TestRenderMarkdown_emitsSourcePositionsAndMap|TestRenderMarkdown_renderMapMapsSelectionToSource|TestRenderMarkdown_renderMapUsesUTF8ByteOffsets|TestRenderHTML_emitsSourcePositionsAndMap|TestCacheGetForSourceMissesWhenSourceSHAChanges|TestContentHTML_rendersThroughPipeline' -v

Expected: FAIL because source-position injection is absent and .html content is still streamed raw.

• Step 3: Implement the markdown source-position renderer

Create internal/render/sourcepos.go. The markdown half wraps goldmark's html.Renderer with per-node hooks that emit data-source-* from node.Lines() and accumulate BlockMap entries:

package render

import (
	"strconv"

	"github.com/yuin/goldmark/ast"
	"github.com/yuin/goldmark/renderer"
	gmhtml "github.com/yuin/goldmark/renderer/html"
	"github.com/yuin/goldmark/util"
)

// blockSpanCollector accumulates BlockMaps for the blocks emitted by the
// goldmark NodeRenderer. It runs alongside the rendering pass and is
// drained after Render() returns.
type blockSpanCollector struct {
	src    []byte
	blocks []BlockMap
}

// nodeSpan returns the [start,end) Source byte range covering all the
// Lines() segments on a block-level node, or false when the node has no
// segments (e.g., a List wraps ListItems without a Lines() of its own).
func nodeSpan(n ast.Node) (int, int, bool) {
	segs := n.Lines()
	if segs == nil || segs.Len() == 0 {
		// Fall back to scanning children: the outermost block range covers
		// the first leaf's Start to the last leaf's Stop.
		var start, end int
		have := false
		for c := n.FirstChild(); c != nil; c = c.NextSibling() {
			cs, ce, ok := nodeSpan(c)
			if !ok {
				continue
			}
			if !have {
				start, end, have = cs, ce, true
			} else {
				if cs < start {
					start = cs
				}
				if ce > end {
					end = ce
				}
			}
		}
		return start, end, have
	}
	first := segs.At(0)
	last := segs.At(segs.Len() - 1)
	return first.Start, last.Stop, true
}

// renderedTextLen returns the UTF-8 byte length of the rendered text content
// under n. It walks n's descendants, decodes entity text to the same visible
// string the browser selection sees, and counts len([]byte(visibleText)).
// Container tags such as Emphasis and Link do not count toward rendered-text
// offsets because selection offsets count text, not markup bytes.
func renderedTextLen(n ast.Node, src []byte) int

In internal/render/markdown.go, register a custom NodeRenderer at goldmark construction time. The simplest pattern is to pre-walk the AST in a single pass to build the RenderMap and a parallel map[ast.Node]SourceRange, then post-process the rendered HTML by replacing each block-opening tag with one that carries data-source-* attributes. Because the post-process walks the rendered HTML through x/net/html and the AST in lock-step (both are deterministic for a fixed input), the indices line up reliably — unlike the regex approach.

Concretely:

type rmBuilder struct {
	src    []byte
	blocks []BlockMap
	byNode map[ast.Node]SourceRange
}

func buildRenderMap(root ast.Node, src []byte) (*rmBuilder, error) {
	b := &rmBuilder{src: src, byNode: make(map[ast.Node]SourceRange)}
	err := ast.Walk(root, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
		if !entering || !isBlockNode(n) {
			return ast.WalkContinue, nil
		}
		start, end, ok := nodeSpan(n)
		if !ok {
			return ast.WalkContinue, nil
		}
		r := SourceRange{Start: start, End: end}
		b.byNode[n] = r

		// One Segment per direct inline text child. RenderedStart/End are
		// computed by accumulating renderedTextLen across the block's
		// children; SourceStart/End come from each text child's Lines().
		segs := segmentsForBlock(n, src)
		b.blocks = append(b.blocks, BlockMap{
			SourceStart: r.Start, SourceEnd: r.End, Segments: segs,
		})
		return ast.WalkContinue, nil
	})
	return b, err
}

// isBlockNode is true for nodes whose rendered tag we want to annotate.
// Matches the spec's block-level scope.
func isBlockNode(n ast.Node) bool {
	switch n.Kind() {
	case ast.KindHeading, ast.KindParagraph, ast.KindList, ast.KindListItem,
		ast.KindBlockquote, ast.KindCodeBlock, ast.KindFencedCodeBlock,
		ast.KindHTMLBlock, ast.KindThematicBreak:
		return true
	}
	// Extension nodes (table, mermaid) match by tag-name kind if needed.
	return false
}

// segmentsForBlock returns the rendered/source Segment list for the
// block's inline text content. For paragraphs and headings this is a
// linear sequence over the inline text children; for code blocks the
// whole literal contributes one Segment; for lists it is empty (children
// have their own BlockMaps).
func segmentsForBlock(n ast.Node, src []byte) []Segment

segmentsForBlock is not optional pseudocode. Implement it with these cases before moving on:

• Paragraphs/headings: walk inline descendants in render order, add a source-backed Segment for each text/string node, and add NonSource gaps only for generated visible text such as list markers.
• Fenced/code blocks: one source-backed Segment for literal code text; syntax-highlighting wrapper tags do not contribute rendered-text offsets.
• Lists/list items: list item text is mapped by the item/paragraph children; marker glyphs are NonSource when they appear in rendered text.
• HTML blocks: map decoded text tokens from the HTML tokenizer back to their source byte ranges.

Do not leave return 0, return nil, or /* implementation */ bodies in the committed code.

Then, after goldmark renders, post-process with x/net/html.Tokenizer instead of regex: walk the tokens, and on each block-level start tag, pop the next AST node from byNode (matched by tag name + ordinal). Emit the same token plus the data-source-* pair. This keeps the rendered output identical except for the injected attributes, and uses the real parser to handle nested structures and attributes correctly.

Note for the implementer. goldmark's html.Renderer uses fixed per-node render functions. An alternative to the post-process pass is to register a custom NodeRenderer via renderer.WithNodeRenderers(util.Prioritized(myRenderer, 100)) that delegates to the default but overrides the opening tag emission for each block kind. Either works. The post-process pass is simpler to get right because it leaves the inline path untouched; the NodeRenderer override is more efficient. Pick whichever is easier to test against the spec's golden fixtures.

Required test coverage in sourcepos_test.go (TestRenderMarkdown_emitsSourcePositionsAndMap already covers heading + paragraph + list; add fixtures for fenced code, blockquote, and an HTML block) demonstrates the new path actually produces correct attribute ranges before we move on.

• Step 4: Implement the HTML source-position pass

In internal/render/html.go, replace the raw-byte return path with an x/net/html.Tokenizer pass over the original bytes. The tokenizer reports byte ranges via z.Raw(); track each block-level open tag's start offset and find its matching end tag with a stack. Emit a new HTML stream where block opening tags carry data-source-start/data-source-end, preserving all attributes and inline content verbatim. Each block contributes one BlockMap whose Segments cover the decoded text nodes inside it.

Sketch:

func annotateHTMLSource(src []byte) (string, RenderMap, error) {
	z := html.NewTokenizer(bytes.NewReader(src))
	var out bytes.Buffer
	type frame struct {
		name      string
		blockIdx  int   // index in blocks where this frame's range starts
		openStart int   // byte offset in src of this frame's opening tag
	}
	var stack []frame
	var blocks []BlockMap
	pos := 0

	for {
		tt := z.Next()
		raw := z.Raw()
		switch tt {
		case html.ErrorToken:
			// EOF or parse error: flush remainder, return.
			return out.String(), RenderMap{Blocks: blocks}, nil
		case html.StartTagToken:
			name := atomString(z)
			if isBlockTag(name) {
				blocks = append(blocks, BlockMap{SourceStart: pos})
				stack = append(stack, frame{name: name, blockIdx: len(blocks) - 1, openStart: pos})
				out.Write(injectDataSourceAttrs(raw, pos))
			} else {
				out.Write(raw)
			}
		case html.EndTagToken:
			name := atomString(z)
			if len(stack) > 0 && stack[len(stack)-1].name == name {
				f := stack[len(stack)-1]
				stack = stack[:len(stack)-1]
				end := pos + len(raw)
				blocks[f.blockIdx].SourceEnd = end
				// Rewrite the deferred data-source-end on the matching open tag.
				rewriteOpenEnd(&out, /* offset of injected attr */, end)
			}
			out.Write(raw)
		case html.TextToken:
			// One Segment per text token inside the current block.
			if len(stack) > 0 {
				appendTextSegment(&blocks[stack[len(stack)-1].blockIdx], pos, raw)
			}
			out.Write(raw)
		default:
			out.Write(raw)
		}
		pos += len(raw)
	}
}