Skip to content

docs: give the real reason a Suspense fallback is read inline at SSR #1324

Description

@vivek7405

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

  • website/app/docs/suspense/page.ts:94 gives the timing reason rather than serializer-safety
  • The rest of the paragraph is unchanged
  • cd website && npx webjs check passes
  • The prose hook accepts the commit (no em-dash, no pause-hyphen, correct brand casing)

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions