Shell (#217): published-doc SEO — author content moved into a cross-origin iframe

[yayashuxue]

Context

The cross-origin iframe shell (#217) fixes the layout-instability ("歪") class of bugs by moving the author document into a same-origin, sandboxed /frame iframe (opaque origin) and keeping tdoc chrome in the outer shell. Author CSS can no longer touch the chrome — structurally, not by luck.

That isolation has an SEO cost we need a decision on before rollout.

The problem

	Old overlay (single-origin)	Shell (this re-arch)
GET /d/<slug>/v/<n> returns	author content inline (overlay injected)	chrome + <iframe src="…/frame">
Where the doc text lives	in the crawled page	in /frame
/frame direct access	n/a	403 (gated on Sec-Fetch-Dest: iframe)

So a crawler hitting a published doc URL sees the shell chrome + an iframe, not the prose. Googlebot can render iframes and may index their content, but the long-standing official guidance is that iframe content is not guaranteed to be attributed to the host page — it's weaker and unreliable versus inline content. Net: published docs would index worse than they do today.

This is a genuine tension: isolation (iframe) ↔ SEO (inline content) — the same response can't easily do both (inline content is exactly what author CSS pollutes).

Proposed fix (keeps both isolation AND SEO; does not require reverting the shell)

Give the author content a real, crawlable URL + canonical:

1. Allow a top-level GET of the content document — either ungate /frame for navigations or add a dedicated /d/<slug>/v/<n>/raw. It stays safe: the sandbox CSP keeps the origin opaque (author JS still inert), and frame-ancestors 'self' prevents third-party framing. Top-level access just shows the bare (public) content.
2. That content page carries <link rel="canonical" href="/d/<slug>/v/<n>"> and goes into the sitemap.
3. Googlebot crawls the content page, sees the prose, attributes it to the doc URL.

This composes cleanly with the "delete overlay.js entirely / full migration" direction.

Decision needed

Do we want published tdoc docs to be indexed by search engines?

• If docs are shared by direct link (not search-discovered) → current shell is acceptable; defer this.
• If organic/search traffic matters → the crawlable-content-URL + canonical work is a merge blocker for the shell and should ship in Cross-origin iframe shell for author documents #217 (or immediately after, before the worker cut reaches production).

Related: #217 (cross-origin iframe shell). Homepage/site pages have the same consideration and are planned to render as plain server-rendered pages (content inline, no iframe) — that path is SEO-safe by construction.

[yayashuxue]

How Claude Artifacts handles this (reference architecture we modeled on)

The shell's isolation (cross-origin sandboxed iframe + parent-side comment chrome) is copied from Claude Artifacts — verified by inspecting it directly.

Its SEO posture is not a solution Artifacts built — it's a requirement Artifacts doesn't have:

• Claude Artifacts = app content. It renders inside the claude.ai app (behind your session) or via explicit share links. Anthropic has no need for the content inside an artifact to be indexed by search engines, so they keep pure iframe isolation with no SEO layer.
• tdoc = a publishing platform. Published docs are meant to be shared and potentially discovered. So tdoc carries an SEO requirement Artifacts doesn't.

Conclusion: copy the isolation from Artifacts; the crawlable-content-URL + canonical layer is tdoc-specific, because tdoc is a content site and Artifacts isn't. We can't inherit a fix that was never needed there.

(Caveat: the iframe architecture is verified; Artifacts' SEO posture is inferred from the product model, not confirmed from their code.)

[yayashuxue]

Decision (2026-08-24): deprioritized — NOT a merge blocker for the shell

Most files are private, and private docs are gated by enforceDocAccess (401/403) — so they are not crawlable under either architecture (overlay or shell). SEO only ever applied to the public/published subset, which is small here. So the shell proceeds without the crawlable-content-URL work.

Runtime cost of adding SEO later ≈ zero (so it's safe to defer):

• The content is already served (/frame, /export) — a crawlable URL serves the same bytes from R2/disk, same per-request cost as the iframe today.
• canonical is a static <link>; the sitemap is generated from meta (cacheable, O(published docs)).
• No new state, no hot-path overhead, no scalability bottleneck.

Status: SEO is downgraded from "blocker" to "cheap to add on demand." Revisit only if organic search traffic on public docs becomes a goal.