Add offscreen block skeletons

[srubin]

Summary

Adds an Editor-owned block skeleton mode for large documents. Offscreen blocks keep one editable, text-containing DOM subtree while skipping block renderers, decorator components, and leaf components. Selected and near-viewport blocks use the normal renderer.

Visibility uses one IntersectionObserver with 500 px overscan; a MutationObserver registers structural edits without a render-all measurement frame. Native scroll anchoring preserves position as blocks promote. Browsers that explicitly report no anchoring support retain full rendering.

Decorators can expose stable DOM IDs through getDOMAnchorIdsForRange. Draft renders the same anchor wrapper in full and skeleton output, keeping addressable IDs without exposing an arbitrary skeleton-attributes API.

Skeleton text inherits the editor's contentEditable, so native selection, select-all, caret movement, and editing work without pinned blocks or keyboard special cases.

Test Plan

• Full suite: 44 suites passed; 402 tests passed, 3 skipped; 500 snapshots passed.

• Lint passes.

• Build exits successfully.

• Downstream production-mode UI coverage verifies select-all, distant caret promotion, autoscroll, typing, and timeline seek behavior.

• I used AI

[scottcheng]

design

looking at this PR and https://github.com/descriptinc/descript/pull/38103, my understanding is that this approach exposes getSkeletonAttributesForRange to customize the skeleton styling, in order to:

• keep height consistency between skeleton and full rendering
• keep skeleton addressable (card boundary id)

I don't love that the script feature builder has to know when to opt in to declare a parallel getSkeletonAttributes, that needs to stay in sync with the rendered styling.

one alternative is to remove the need to match skeleton height against full rendering height:

• skeleton has approximate height, by using the same text style (and the existing getMinHeightForBlock)
  • this further reduces # of DOM elements, each block can just be a single text node (in most cases), rather than splitting up into spans based on getSkeletonAttributesForRange
  • for scrollbar size / position fidelity: it's probably fine if the scrollbar isn't 100% accurate, and if we care about its fidelity we can render it based on skeleton height so it doesn't depend on full rendering — I think it's already custom
• as skeleton blocks scroll in from above the fold becomes fully rendered, or scroll out of view above, measure the difference and compensate in the same render pass
  • we already have useMaintainScriptPosition, I didn't look closely at it, and I think we need to make some changes to it to work for this purpose
• for addressability: we can replace getSkeletonAttributesForRange with a more explicit / concrete interface to define id of a block — that might already suffice, or if we care about precision within a block, inject DOM elements w/ id

wdyt?

verification

I was going to try some scrolling in the https://github.com/descriptinc/descript/pull/38103 preview build but I suppose that depends on merging and publishing this, so I'll leave the verification to you!

the concern is that if the skeleton height and full render height diverge, since UseTextEditorContentVisibility tracks block heights based on what's actually rendered, for offscreen blocks it'd register the skeleton heights, and when scrolled into screen the height may jump. concretely, decorators that depend on redux state (e.g. card boundary in audio-only comp, as bugbot pointed out), and decorators with custom CSS (e.g. full-line script clips). I made a test project full of script clips, and a lot of scenes in a paragraph.

further notes

more claude-written notes in https://app.notion.com/p/descript/Script-skeleton-height-parity-vs-scroll-compensation-design-notes-3b2abe2e1a50819c969fcd2843131a86

[srubin]

design

looking at this PR and descriptinc/descript#38103, my understanding is that this approach exposes getSkeletonAttributesForRange to customize the skeleton styling, in order to:

* keep height consistency between skeleton and full rendering

* keep skeleton addressable (card boundary id)

I don't love that the script feature builder has to know when to opt in to declare a parallel getSkeletonAttributes, that needs to stay in sync with the rendered styling.

I agree with the principle that this API is too broad!

one alternative is to remove the need to match skeleton height against full rendering height:

* skeleton has approximate height, by using the same text style (and the existing `getMinHeightForBlock`)
  
  * this further reduces # of DOM elements, each block can just be a single text node (in most cases), rather than splitting up into spans based on `getSkeletonAttributesForRange`
  * for scrollbar size / position fidelity: it's probably fine if the scrollbar isn't 100% accurate, and if we care about its fidelity we can render it based on skeleton height so it doesn't depend on full rendering — I think it's already custom

* as skeleton blocks scroll in from above the fold becomes fully rendered, or scroll out of view above, measure the difference and compensate in the same render pass

This sounds more complex and error-prone than requiring a little bit of upfront developer effort and then relying on the browser to handle scrolling entirely on its own. But I'll noodle on it.

  * we already have `useMaintainScriptPosition`, I didn't look closely at it, and I think we need to make some changes to it to work for this purpose

* for addressability: we can replace `getSkeletonAttributesForRange` with a more explicit / concrete interface to define id of a block — that might already suffice, or if we care about precision within a block, inject DOM elements w/ id

Agreed! There's no reason to expose a full suite of attributes when all we need is an id.

wdyt?

verification

I was going to try some scrolling in the descriptinc/descript#38103 preview build but I suppose that depends on merging and publishing this, so I'll leave the verification to you!

I can always publish interim versions of draft-js for testing in the descript PRs. Will do once I take another pass.

the concern is that if the skeleton height and full render height diverge, since UseTextEditorContentVisibility tracks block heights based on what's actually rendered, for offscreen blocks it'd register the skeleton heights, and when scrolled into screen the height may jump. concretely, decorators that depend on redux state (e.g. card boundary in audio-only comp, as bugbot pointed out), and decorators with custom CSS (e.g. full-line script clips). I made a test project full of script clips, and a lot of scenes in a paragraph.

We might not even need the content visibility stuff anymore if we turn on skeletons, since the offscreen nodes will be very simple. We should profile that.

further notes

more claude-written notes in https://app.notion.com/p/descript/Script-skeleton-height-parity-vs-scroll-compensation-design-notes-3b2abe2e1a50819c969fcd2843131a86

[scottcheng]

• as skeleton blocks scroll in from above the fold becomes fully rendered, or scroll out of view above, measure the difference and compensate in the same render pass

This sounds more complex and error-prone than requiring a little bit of upfront developer effort and then relying on the browser to handle scrolling entirely on its own. But I'll noodle on it.

yeah fair, I'm probably oversimplifying it, maybe worth a quick prototype to see if it's feasible?

also, my claude keeps suggesting that the native overflow-anchor may be the whole solution, and we don't need any custom scroll position compensation, but I haven't verified that.

[srubin]

• as skeleton blocks scroll in from above the fold becomes fully rendered, or scroll out of view above, measure the difference and compensate in the same render pass

This sounds more complex and error-prone than requiring a little bit of upfront developer effort and then relying on the browser to handle scrolling entirely on its own. But I'll noodle on it.

yeah fair, I'm probably oversimplifying it, maybe worth a quick prototype to see if it's feasible?

also, my claude keeps suggesting that the native overflow-anchor may be the whole solution, and we don't need any custom scroll position compensation, but I haven't verified that.

For sure, will try it out!