Skip to content

feat: live HTML pages with in-place text editing and Primer blocks (collaboration M6) - #177

Open
maxsam4 wants to merge 19 commits into
stack/14-m10a4-blocksfrom
stack/15-m6-pages
Open

maxsam4 wants to merge 19 commits into
stack/14-m10a4-blocksfrom
stack/15-m6-pages

Conversation

@maxsam4

@maxsam4 maxsam4 commented Nov 19, 2026

Copy link
Copy Markdown

Replaces #156 (review history there).

One link of a linear stack, one milestone per PR. The base is stack/14-m10a4-blocks (#176), so this diff is this milestone's own work plus the merge resolutions it needs against the links below it.

Summary

HTML uploads become live page documents: the page renders as uploaded in its sandboxed frame, people edit its text in place, and agent republishes carry their text over.

  • Auto-stamping held; no fallback to agent-authored ids. At publish, every element whose children are only text and <br> gets a data-pid. It is inserted into the original upload (parse5 with source offsets), so the rest of the page stays byte for byte.

    • Valid existing pids are kept. A duplicate or invalid pid is rewritten, and a pid on a non-text element is removed (the bridge would otherwise wipe that element's children).
    • One text rule serves seeding, splicing, comparison and the bridge: <br> is \n, and outside <pre> source whitespace collapses. Editing one word of an indented paragraph never splices line breaks in.
    • Checked on real agent pages up to 120 KB and 1,069 pids: stripping the pids gives the original, and stamping again changes nothing.
  • Matching across republishes (page/match.ts), in order:

    1. a pid the agent kept;
    2. same tag and path, similarity ≥ 0.6;
    3. same tag anywhere, similarity ≥ 0.8;
    4. otherwise a fresh pid.

    Repeated labels and close runner-ups are uncertain and never carried silently. Matching uses the shared bounded lib/similarity.ts with a total budget. Every examined pair costs work, candidates come from tag and path indexes, pairs are capped, and only the first 3,000 elements per side are matched. Stamping and splicing are linear: a 20,000-element page of identical labels stamps and matches in about 0.2 s.

  • State. Each pid's text lives in page/<blockId>/<pid>, one paragraph whose block id is the page block's. A pid target { tabId, blockId, pid } therefore locates its block like any other, so preconditions, suggestions and comment marks work unchanged.

    • <primer-*> embeds live in embed/<blockId>/<embedId> as native blocks: table, code, diagram and math.
    • The page block (packages/blocks) carries sourceKey, title, pids and embeds. reachableFragments follows them, so a removed element's thread orphans instead of disappearing.
  • Publish (page/publish.ts, lib/publish.ts).

    • HTML goes through the one live publish path. The stamped source is stored once with the checkpoint that published it (pages/<docId>/<versionId>.html) and purged with the document.
    • A legacy document's next version makes it live, and its open threads are anchored where their quote occurs once in the page text. The legacy HTML version path and lib/threadCarry.ts are removed (one way).
  • Republish: three-way carry-over through applyPlan (page/carry.ts).

    • Text only people changed is kept.
    • Where both sides changed, the agent's text wins. The person who last wrote that text (from doc_updates.touched) gets it back as an ordinary stored suggestion.
    • mine is read inside the build on the document queue, so typing that races a republish is never lost.
    • A suggest-mode agent only suggests text on existing elements: no version, no stored original, no source switch. Such an agent can't make a legacy document live (forbidden, with a fix).
    • Republishes of one document are serialised, so two publishes on the same base can't both win.
  • Splice-back on demand. Export, checkpoints (static.html, export.html) and print splice changed pids and edited embeds into the stamped source. An embed counts as untouched when its blocks equal those re-derived from the stored source, so no editor-writable state can make an export lie.

  • Agents.

    • primer_get_doc lists pages: each page's source with its pids, and each pid's text (fenced with fenceUntrusted) and version.
    • An update op on { tabId, blockId, pid } takes plain text.
    • The authoring skill gains an "HTML pages" section, and the reference documents both.
  • Bridge (v1.js, features page-text and embeds).

    • After the page's load handlers ran, it reports each stamped element's DOM text and rect, then rects again on scroll and resize, and reports clicks.
    • set_page_texts sets text only (\n → <br>), only on elements carrying that pid, never inside embeds.
    • set_embeds fills <primer-*> elements with text-only HTML the host builds from the block state, and Mermaid renders in place.
    • protocol.ts parses every message strictly.
  • Host.

    • PageView renders the frame (GET /api/documents/:docId/pages/:blockId/content, artifact CSP, sandbox unchanged) and binds it via GET …/pages/:blockId. It pushes current text to editable pids only, and pushes again on every fragment change.
    • A pid whose first reported DOM text isn't its source text was drawn by a script. It is read-only and opens no editor.
    • The one shared live/Overlay.tsx (C9) draws a BlockNote editor in Primer's window over the element, bound to its sub-fragment. Page text gets BlockNote comments through a pid-scoped PrimerThreadStore; embeds get the full block editor.

Security

  • The iframe sandbox and connect-src 'none' are unchanged. The overlay and every editing control live in the host. The page receives only text, set with textContent and <br>.
  • Page block props are editor-writable:
    • sourceKey is honoured only inside pages/<documentId>/.
    • A source that can't be read never fails a read, an export or a checkpoint. It is listed as unavailable, each source is loaded once per read, and reads are capped at 20 pages and 5,000 pids.
  • Page text reaches agents fenced (random tag, escaped contents).
  • Stamping and matching are bounded on hostile pages (see above).

Test evidence

  • CI gates run locally: codegen-drift-check, db:migrate:test, typecheck, pnpm -r build, pnpm test (api 1003 passed, web 364, mcp 125, blocks 3) and pnpm audit --audit-level=high. All pass.
  • pnpm --filter @primer/api test:browser: 11 passed.
  • New tests:
    • stamping only inserts data-pid attributes; script, style and nested-markup elements are not stamped; br becomes a newline; an existing data-pid is kept; offsets on a BOM, CRLF and astral characters;
    • an untouched page exports the original byte for byte; editing one pid changes only its span;
    • kept pid wins; a reworded paragraph keeps its pid; a moved heading matches; new and removed elements; repeated labels are uncertain; a 20,000-element page stays within budget;
    • the three-way carry-over table; repeated labels are never carried silently; a removed element orphans its thread;
    • an HTML upload creates a live page document with one page block; page content is served with the artifact CSP and sandbox unchanged;
    • people's text survives an agent republish, and both-changed text becomes their suggestion;
    • an agent edits a pid through ops and the thread on it survives;
    • a suggest-mode agent's HTML republish only suggests, and its legacy conversion is refused;
    • a page block with a bogus sourceKey doesn't break the read;
    • <primer-*> tags survive sanitize with literal ids; a missing embed id is refused; untouched embeds export verbatim;
    • the protocol parses page_elements and rejects malformed rects; set_page_texts only touches stamped nodes (the real v1.js in jsdom); a script-drawn pid is read-only; set_embeds content is text only.
  • Browser check (headless Chrome against pnpm dev, two people in separate browser contexts): an agent published a page with a script-drawn chart and total and a <primer-table>.
    • Person A edited the heading through the overlay, and B saw it live.
    • B edited the same heading, and A saw it live.
    • Clicking the script-drawn total opened no editor, and the page kept the script's value.
    • The agent republished with the heading unchanged (and another paragraph reworded); the people's heading text survived.
    • A cell of the <primer-table> was edited in the overlay, and both people's frames showed it.

Deviations

  • Ops can't return script_text_read_only: only the browser can tell that text was drawn by a script. The server treats every pid as text, and the host makes script-drawn pids read-only.
  • Agent ops on embeds are not supported yet; people edit embeds in the overlay. Suggestions keep their sub-fragment for page text only.
  • Bundles don't copy pages/<blockId>.html: the stamped source is stored once, immutably, with the checkpoint that published it, and each bundle's state.ydoc names it.

🤖 Generated with Claude Code

maxsam4 and others added 19 commits November 19, 2026 23:20
People edit an HTML page's text without touching the page's own code: every
element whose children are only text and <br> gets a `data-pid`, inserted
into the original upload so the rest of the page stays byte for byte. Pids
survive agent republishes by matching old and new elements (kept pid, then
same path, then same tag, by text similarity), and a match on repeated
labels or with a close runner-up is flagged uncertain so people's text on it
is never carried silently. Splice-back writes changed text at each pid's
source span and leaves untouched pids' bytes alone.

One text rule serves seeding, splicing, comparison and the bridge: <br> is a
newline and, outside <pre>, source indentation collapses, so editing one word
in an indented paragraph never splices line breaks in. Checked on real agent
pages up to 120 KB / 1,000 pids: stripping the pids gives the original, and
restamping is a no-op.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each pid's text lives in its own fragment `page/<blockId>/<pid>`, written
through the one apply pipeline. A text edit replaces only the changed middle,
so comment marks on the rest of the text stay. On an agent republish each
pid is decided three ways against its last stamped text: untouched text takes
the agent's, text only people changed is carried, and when both changed, or
the match was uncertain, the agent's text wins and people's text is returned
as a suggestion. People's text is read inside the edit on the document queue,
so typing that races the republish is never lost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Agents can place <primer-table>, <primer-code>, <primer-mermaid> and
<primer-math> in an HTML page. The sanitizer keeps them with their literal
`data-embed-id` and `lang`; each becomes the native BlockNote block (table,
code, diagram, math) in its own fragment, and an untouched one exports as its
original source. A missing, invalid or repeated id is refused at publish with
the element's path, since an id set by a script can't anchor state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The bridge reports each stamped element's DOM text after the page's scripts
ran; a pid whose text no longer equals its source text was drawn by a script
(a chart label, a counter) and gets no overlay editor, as do pids a script
cloned or the sanitizer dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A page's fragments are seeded from its stamped source at publish (each pid
with its text, each embed with its native blocks), and its current HTML is
rendered on demand by splicing in only the pids and embeds that changed. An
embed counts as untouched when its blocks equal the blocks its source gives,
recomputed from the stored stamped source, so no editor-writable state can
make the export lie about it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…stack

Both stacks kept. The working status that M4 removed stays removed (its
MCP tool, client method, route row and banner). M10a's two migrations are
replaced by one regenerated on top of M5's (0022, same tables and indexes).
The comments, suggestions and delete-guard strings from M3-M5 get i18n keys
in every locale, so the localisation lint holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Page text is untrusted input, so matching shares the banded similarity the
Markdown republish merge uses and stops comparing past a total budget
(remaining elements get fresh pids, which never carries text silently).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A page is untrusted input. Matching charged only similarity's character
work, so pairs rejected by tag, path or length were free and a page with
thousands of elements still did quadratic work. Now every examined pair
costs at least 1, candidates come from tag and path indexes, both loops stop
once the budget is spent, the pairs kept per stage are capped and only the
first 3,000 elements per side are matched; the rest get fresh pids.
Stamping and splicing applied each insertion by copying the whole page, also
quadratic; both now build the output in one pass. A 20,000-element page of
identical labels stamps and matches in well under a second.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An HTML publish now makes a live document holding one page block over the
stamped upload, like Markdown and text: the stamped source is stored once
with the checkpoint that published it (pages/<documentId>/<versionId>.html,
purged with the document), each pid's fragment is seeded with its text and
each embed's with its blocks, and a legacy document's open threads are
anchored where their quote occurs once in the page text. An HTML version of
a page document carries people's text over three ways through the pipeline:
the publisher's text wins where both changed, and the person who last wrote
the lost text gets it back as their suggestion.

The page block (packages/blocks) names its fragments: the page's pids and
embed ids are props, so reachability, and with it thread orphaning, follows
republishes. Its source key is editor-writable, so every read checks it lies
in the document's own prefix. Bundles, export and print render a page
document as its page with people's text spliced in; its frame is served from
GET /api/documents/:docId/pages/:blockId/content with the artifact CSP, and
GET /api/documents/:docId/pages/:blockId binds the host to it (policy, each
pid's source text, embeds).

Page text paragraphs carry the page block's id, so a pid target locates its
block like any other: agents edit page text with `update` and a plain-text
block under the usual version precondition, and suggestions on page text
keep their fragment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uggest-mode republish)

A page republish follows the same rule as Markdown: when nothing applied, no
original is stored and no checkpoint written. An agent that may only suggest
on a legacy document can't make it live (there is nothing to suggest against).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Its HTML republish proposes new text for the page's existing elements as
suggestions; the page's source, elements and embeds change only by someone
who may edit, so the stored source is discarded and no version is made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y document

HTML publishes are live pages now, so the thread carry across HTML versions
(lib/threadCarry.ts) has no caller and goes, with its tests. Tests of legacy
behaviour create a legacy document directly (testing/legacy.ts); content
assertions expect the stamped pids. Republishes of one document run one at a
time, so two publishes on the same base can't both win.

New tests pin a page document end to end: the upload becomes one page
block; its frame is served with the artifact CSP; export splices people's
text into the original; an agent's republish keeps text only people changed
and returns both-changed text to its writer as a suggestion; a removed
element's thread is orphaned, not lost; an agent edits a pid with ops and the
comment on it stays; a suggest-mode agent only suggests and can't make a
legacy document live.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
primer_get_doc lists a page document's pages: each page block's source as
published (with its data-pid attributes, to republish with them intact) and
each pid's current text, fenced as untrusted with the shared random-tag
fence, with the version an update expects. An `update` op on
{ tabId, blockId, pid } takes plain text. The authoring skill's HTML pages
section explains stamping, keeping pids on republish, carry-over and
suggestions, script-drawn text and the <primer-*> blocks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oint

Page block props are editor-writable, so any editor could point a page at a
missing source and make loadStamped throw for every reader. Loading a
source now returns null (logged) on any storage error; an agent's read lists
such a page as unavailable (`source: null`) and still returns the rest,
loads each source once, and lists at most 20 pages and 5,000 pids. Export
and checkpoints render the first page block whose source loads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Feature `page-text`: after the page's load handlers ran, the bridge reports
each stamped element's DOM text and rect (page_elements), then rects again
on scroll and resize (page_rects), and clicks (pid_clicked). set_page_texts
sets only text on elements carrying that data-pid, outside Primer blocks,
with `\n` as <br>: nothing the host sends is parsed as markup. Feature
`embeds`: <primer-*> blocks report rects and clicks (embed_clicked) and show
the static HTML the host renders (set_embeds), Mermaid rendered in place.
The host parses every message strictly (ids as the server stamps them,
finite rects, bounded sizes).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A page block renders its page in the sandboxed frame (ArtifactIframe, which
now grants a live page the page-text and embeds features and hands it their
messages) and pushes people's current text and each Primer block's
text-only HTML into it, again on every change of those fragments.

Clicking an element opens the one host overlay (live/Overlay.tsx, C9): a
BlockNote editor in Primer's window drawn over the element, bound to its
sub-fragment, so keystrokes never reach the page. Page text gets BlockNote's
comments, anchored in its fragment (the thread store can be scoped to one
pid); a Primer block gets the full block editor. Text a script drew is
read-only and opens no editor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…xt alone

Found in the browser check: the host pushed people's text into every pid,
so a pid a script redraws (a computed total) showed its source text again;
now only editable pids get text pushed. The overlay follows the frame when
the host scrolls, opens with the cursor at the end of the text, and drops
BlockNote's side padding so it lines up with the element.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat: live HTML pages with in-place text editing and Primer blocks (collaboration M6)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant