feat(core): add unstable useObserveDocument hook

[pedrobonamin]

Description

Adds useObserveDocument. a hook that uses the new unstable_observeDocument functionality from the documentPreviewStore

This hook is internal as in beta, we are using it for the corel branch but it can be extracted and merged into next

What to review

Testing

Notes for release

n/a internal

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
page-building-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 24, 2025 5:17pm
performance-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 24, 2025 5:17pm
test-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 24, 2025 5:17pm

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
studio-workshop	⬜️ Ignored (Inspect)			Jan 24, 2025 5:17pm
test-next-studio	⬜️ Ignored (Inspect)			Jan 24, 2025 5:17pm

[github-actions]

No changes to documentation

[github-actions]

Component Testing Report Updated Jan 24, 2025 5:23 PM (UTC)

❌ Failed Tests (2) -- expand for details

File	Status	Duration	Passed	Skipped	Failed
comments/CommentInput.spec.tsx	✅ Passed (Inspect)	1m 4s	15	0	0
formBuilder/ArrayInput.spec.tsx	✅ Passed (Inspect)	12s	3	0	0
formBuilder/inputs/PortableText/Annotations.spec.tsx	❌ Failed (Inspect)	1m 59s	4	0	2
formBuilder/inputs/PortableText/copyPaste/CopyPaste.spec.tsx	✅ Passed (Inspect)	51s	11	7	0
formBuilder/inputs/PortableText/copyPaste/CopyPasteFields.spec.tsx	✅ Passed (Inspect)	0s	0	12	0
formBuilder/inputs/PortableText/Decorators.spec.tsx	✅ Passed (Inspect)	26s	6	0	0
formBuilder/inputs/PortableText/DisableFocusAndUnset.spec.tsx	✅ Passed (Inspect)	14s	3	0	0
formBuilder/inputs/PortableText/DragAndDrop.spec.tsx	✅ Passed (Inspect)	26s	6	0	0
formBuilder/inputs/PortableText/FocusTracking.spec.tsx	✅ Passed (Inspect)	1m 7s	15	0	0
formBuilder/inputs/PortableText/Input.spec.tsx	✅ Passed (Inspect)	1m 30s	21	0	0
formBuilder/inputs/PortableText/ObjectBlock.spec.tsx	✅ Passed (Inspect)	2m 2s	21	0	0
formBuilder/inputs/PortableText/PresenceCursors.spec.tsx	✅ Passed (Inspect)	13s	3	9	0
formBuilder/inputs/PortableText/Styles.spec.tsx	✅ Passed (Inspect)	26s	6	0	0
formBuilder/inputs/PortableText/Toolbar.spec.tsx	✅ Passed (Inspect)	1m 43s	21	0	0
formBuilder/tree-editing/TreeEditing.spec.tsx	✅ Passed (Inspect)	0s	0	3	0
formBuilder/tree-editing/TreeEditingNestedObjects.spec.tsx	✅ Passed (Inspect)	0s	0	3	0

[github-actions]

⚡️ Editor Performance Report

Updated Fri, 24 Jan 2025 17:23:13 GMT

Benchmark	reference latency of sanity@latest	experiment latency of this branch	Δ (%) latency difference
article (title)	24.1 efps (42ms)	25.0 efps (40ms)	-2ms (-3.6%)	✅
article (body)	72.5 efps (14ms)	61.5 efps (16ms)	+2ms (+17.8%)	✅
article (string inside object)	25.3 efps (40ms)	26.3 efps (38ms)	-2ms (-3.8%)	✅
article (string inside array)	23.5 efps (43ms)	22.7 efps (44ms)	+2ms (+3.5%)	✅
recipe (name)	52.6 efps (19ms)	52.6 efps (19ms)	+0ms (-/-%)	✅
recipe (description)	58.8 efps (17ms)	58.8 efps (17ms)	+0ms (-/-%)	✅
recipe (instructions)	99.9+ efps (5ms)	99.9+ efps (5ms)	+0ms (-/-%)	✅
synthetic (title)	19.4 efps (52ms)	19.6 efps (51ms)	-1ms (-1.0%)	✅
synthetic (string inside object)	19.6 efps (51ms)	19.2 efps (52ms)	+1ms (+2.0%)	✅

efps — editor "frames per second". The number of updates assumed to be possible within a second.

Derived from input latency. efps = 1000 / input_latency

Detailed information

🏠 Reference result

The performance result of sanity@latest

Benchmark	latency	p75	p90	p99	blocking time	test duration
article (title)	42ms	47ms	55ms	497ms	319ms	10.8s
article (body)	14ms	17ms	19ms	180ms	229ms	5.3s
article (string inside object)	40ms	43ms	45ms	192ms	188ms	6.8s
article (string inside array)	43ms	45ms	51ms	187ms	256ms	6.9s
recipe (name)	19ms	20ms	23ms	37ms	0ms	7.0s
recipe (description)	17ms	18ms	20ms	35ms	0ms	4.3s
recipe (instructions)	5ms	7ms	8ms	11ms	0ms	3.0s
synthetic (title)	52ms	56ms	68ms	308ms	853ms	13.3s
synthetic (string inside object)	51ms	57ms	90ms	351ms	1167ms	8.4s

🧪 Experiment result

The performance result of this branch

Benchmark	latency	p75	p90	p99	blocking time	test duration
article (title)	40ms	63ms	69ms	201ms	841ms	10.7s
article (body)	16ms	18ms	29ms	71ms	212ms	5.8s
article (string inside object)	38ms	40ms	44ms	57ms	146ms	6.6s
article (string inside array)	44ms	45ms	47ms	168ms	162ms	6.9s
recipe (name)	19ms	20ms	23ms	39ms	0ms	7.5s
recipe (description)	17ms	18ms	20ms	28ms	0ms	4.5s
recipe (instructions)	5ms	7ms	8ms	9ms	0ms	3.2s
synthetic (title)	51ms	52ms	57ms	167ms	371ms	12.3s
synthetic (string inside object)	52ms	54ms	61ms	240ms	701ms	7.9s

📚 Glossary

column definitions

• benchmark — the name of the test, e.g. "article", followed by the label of the field being measured, e.g. "(title)".
• latency — the time between when a key was pressed and when it was rendered. derived from a set of samples. the median (p50) is shown to show the most common latency.
• p75 — the 75th percentile of the input latency in the test run. 75% of the sampled inputs in this benchmark were processed faster than this value. this provides insight into the upper range of typical performance.
• p90 — the 90th percentile of the input latency in the test run. 90% of the sampled inputs were faster than this. this metric helps identify slower interactions that occurred less frequently during the benchmark.
• p99 — the 99th percentile of the input latency in the test run. only 1% of sampled inputs were slower than this. this represents the worst-case scenarios encountered during the benchmark, useful for identifying potential performance outliers.
• blocking time — the total time during which the main thread was blocked, preventing user input and UI updates. this metric helps identify performance bottlenecks that may cause the interface to feel unresponsive.
• test duration — how long the test run took to complete.