Problem
website/app/docs/suspense/page.ts:94 gives the wrong reason for why a <webjs-suspense> .fallback is read inline at SSR. The sentence currently reads:
The .fallback is read at SSR as the inline placeholder (never through the data-webjs-prop-* path, since a TemplateResult is not serializer-safe) and must be an unquoted property hole.
Serializer-safety explains why a TemplateResult cannot ride that path. It does not explain why it must not. The load-bearing constraint is TIMING: data-webjs-prop-* applies the property at hydration, which is far too late for a placeholder whose entire job is to be in the first flushed bytes.
The distinction matters because the current wording points at a fixable-looking obstacle. A reader could reasonably conclude that making TemplateResult serializable would unlock the data-webjs-prop-* path, and spend real time on it. It would not: even a perfectly serializable fallback applied at hydration arrives after the shell has flushed, so there is no placeholder during the window the boundary exists for.
Design / approach
Replace the parenthetical with the timing reason. The corrected sentence, already written and reviewed, is:
The .fallback is read at SSR as the inline placeholder (never through the data-webjs-prop-* path, because that applies the property at hydration, far too late for a placeholder that has to be in the first flushed bytes) and must be an unquoted property hole.
Provenance. This correction was written as part of PR #1314, which is being closed unmerged as superseded by PR #1317 (#1307). The line is unrelated to that PR's subject and would otherwise be lost with it, which is the only reason this issue exists. Nothing else from #1314 is worth salvaging.
Implementation notes (for the implementing agent)
Where to edit
website/app/docs/suspense/page.ts:94. One <p>. The exact before and after are quoted above; only the parenthetical changes.
Landmines
- This is a docs page in the in-repo
website app, so it is TypeScript inside an html template. Keep it a single line, matching the surrounding paragraphs.
- The prose hook enforces AGENTS.md invariant 11 on new content: no em-dashes, no space-surrounded hyphen or semicolon used as a pause between words, and
WebJs capitalized in prose. The replacement text above already complies.
- Do not widen this into a rewrite of the Suspense page. The rest of that paragraph, including the
renderFallback() sentence and the Loading States link, is correct and stays.
Invariants to respect
- AGENTS.md invariant 11 (prose punctuation and brand casing).
Tests + docs
- No test layer applies; this is a single documentary sentence with no behavioural surface.
test/docs/ contains docs-site assertions. Check whether any asserts on this paragraph before editing; if one does, update it.
- The doc gate does not fire, since no
packages/*/src file is staged.
Acceptance criteria
Problem
website/app/docs/suspense/page.ts:94gives the wrong reason for why a<webjs-suspense>.fallbackis read inline at SSR. The sentence currently reads:Serializer-safety explains why a
TemplateResultcannot ride that path. It does not explain why it must not. The load-bearing constraint is TIMING:data-webjs-prop-*applies the property at hydration, which is far too late for a placeholder whose entire job is to be in the first flushed bytes.The distinction matters because the current wording points at a fixable-looking obstacle. A reader could reasonably conclude that making
TemplateResultserializable would unlock thedata-webjs-prop-*path, and spend real time on it. It would not: even a perfectly serializable fallback applied at hydration arrives after the shell has flushed, so there is no placeholder during the window the boundary exists for.Design / approach
Replace the parenthetical with the timing reason. The corrected sentence, already written and reviewed, is:
Provenance. This correction was written as part of PR #1314, which is being closed unmerged as superseded by PR #1317 (#1307). The line is unrelated to that PR's subject and would otherwise be lost with it, which is the only reason this issue exists. Nothing else from #1314 is worth salvaging.
Implementation notes (for the implementing agent)
Where to edit
website/app/docs/suspense/page.ts:94. One<p>. The exact before and after are quoted above; only the parenthetical changes.Landmines
websiteapp, so it is TypeScript inside anhtmltemplate. Keep it a single line, matching the surrounding paragraphs.WebJscapitalized in prose. The replacement text above already complies.renderFallback()sentence and the Loading States link, is correct and stays.Invariants to respect
Tests + docs
test/docs/contains docs-site assertions. Check whether any asserts on this paragraph before editing; if one does, update it.packages/*/srcfile is staged.Acceptance criteria
website/app/docs/suspense/page.ts:94gives the timing reason rather than serializer-safetycd website && npx webjs checkpasses