Question
Should element identity be injected at serve time rather than inferred from the rendered DOM?
Surfaced by How other visual editors write into source and attach to a dev server. It was never charted because ADR-0001 framed the choice as a binary - never inject, or mutate source - and a third option was not in view.
The evidence.
- Pinegrow injects
data-pg-id, and Utopia injects data-uid. Both strip it before anything reaches disk. Only Onlook actually writes identity attributes into source files, where they remain and are observable as committed attributes in third-party public repos.
- Fingerprint-style signal matching is the field's documented fallback tier, not its first choice. Dosmos labels its own tiers in code -
// Exact for a build-time stamp, // Heuristic for the signal bundle, in that order. Everyone who can instrument ranks the instrumented answer first.
- webtweak already serves the Target page through its own server and already injects the Overlay into it. A serve-time identity token costs nothing on disk, requires no build step, and does not touch the user's files.
Why this sits underneath other tickets.
If identity becomes a lookup rather than a judgement, a large part of What the deterministic writer does when it cannot be sure stops existing - there is far less uncertainty to have a policy about. Deciding the uncertainty policy first means designing for a problem that may have been removed.
It also bears directly on Does 1.0 reorder the DOM. That ticket's core collision is that siblingIndex and the nth-of-type selector are positional, so a reorder invalidates the identity every other patch in the batch was built from. A serve-time token is not positional, so the collision does not arise.
Resolve:
- Whether to inject at serve time at all, and what the token is - a nanoid, a content hash, a path from the parse, something else.
- Whether ADR-0001 is amended or superseded. It says identity is "never an injected attribute"; serve-time injection does not mutate source, so this may be a clarification rather than a reversal. Either way the ADR must be updated, because a future reader will otherwise find the code contradicting it.
- How the token survives the round trip. The Overlay sees it in the DOM, but reconcile has to find the same element in source text that does not contain it. What maps one to the other - a server-side index built when the page is served, and does that index survive the user hand-editing source between capture and reconcile?
- What happens when the page is not served by webtweak. A future dev-server-attached mode may make serve-time injection unavailable, which would put the Fingerprint back as the fallback tier - so does the Fingerprint stay regardless, as the second tier?
- Whether the Fingerprint is kept, reduced, or dropped. Note that Dosmos independently arrived at webtweak's exact priority order, 80-character truncation and own-text preference, so the existing bundle is worth keeping as a fallback even if injection lands.
- Whether an injected token changes anything about
Peek, the shape create op's anchor, or the existing nonWtClasses filtering that already hides Overlay-owned classes from the Fingerprint.
Primary source for all of the above: docs/research/visual-editor-source-writing.md on branch research/visual-editor-source-writing.
Question
Should element identity be injected at serve time rather than inferred from the rendered DOM?
Surfaced by How other visual editors write into source and attach to a dev server. It was never charted because ADR-0001 framed the choice as a binary - never inject, or mutate source - and a third option was not in view.
The evidence.
data-pg-id, and Utopia injectsdata-uid. Both strip it before anything reaches disk. Only Onlook actually writes identity attributes into source files, where they remain and are observable as committed attributes in third-party public repos.// Exactfor a build-time stamp,// Heuristicfor the signal bundle, in that order. Everyone who can instrument ranks the instrumented answer first.Why this sits underneath other tickets.
If identity becomes a lookup rather than a judgement, a large part of What the deterministic writer does when it cannot be sure stops existing - there is far less uncertainty to have a policy about. Deciding the uncertainty policy first means designing for a problem that may have been removed.
It also bears directly on Does 1.0 reorder the DOM. That ticket's core collision is that
siblingIndexand thenth-of-typeselector are positional, so a reorder invalidates the identity every other patch in the batch was built from. A serve-time token is not positional, so the collision does not arise.Resolve:
Peek, the shapecreateop'sanchor, or the existingnonWtClassesfiltering that already hides Overlay-owned classes from the Fingerprint.Primary source for all of the above:
docs/research/visual-editor-source-writing.mdon branchresearch/visual-editor-source-writing.