Entendendo o Contexto do Document Object Model

Antes de mergulhar na mecânica do svelte:document, é essencial entender por que esse elemento especial existe e qual espaço de problema ele ocupa dentro da arquitetura do Svelte. O Document Object Model do navegador apresenta uma estrutura hierárquica onde o objeto document fica como nó raiz contendo todo o conteúdo da página, distinto do objeto window (que representa a janela do navegador em si) e do elemento body (o contêiner visível para o conteúdo da página).

Muitos eventos do navegador borbulham por essa hierarquia, mas certos eventos disparam especificamente no objeto document e nunca chegam ao window. O evento visibilitychange representa o exemplo mais comum — esse evento dispara exclusivamente no document quando os usuários alternam abas, minimizam navegadores ou navegam para fora. Da mesma forma, propriedades como activeElement (rastreando qual elemento tem foco atualmente) existem apenas no document, tornando o acesso direto ao documento necessário para determinados comportamentos de aplicação.

O elemento especial <svelte:document> do Svelte fornece acesso declarativo a essa funcionalidade em nível de documento, mantendo os princípios do Svelte de limpeza automática, segurança na renderização do lado do servidor e suporte a bindings reativos. Sem essa abstração, os desenvolvedores precisariam conectar manualmente ouvintes de eventos em hooks de ciclo de vida, lembrar de limpá-los na destruição do componente e lidar com ambientes SSR onde o document não existe.

Sintaxe Básica e Requisitos de Posicionamento

O elemento <svelte:document> segue uma regra de posicionamento estrita compartilhada com seus elementos especiais irmãos <svelte:window> e <svelte:body>: ele deve aparecer no nível superior do seu componente, nunca aninhado dentro de blocos, elementos ou estruturas condicionais.

<script>
	let visibilityState = $state('visible')

	function handleVisibilityChange() {
		visibilityState = document.visibilityState
		console.log(`Page visibility changed to: ${visibilityState}`)
	}
</script>

<!-- Correct: top-level placement -->
<svelte:document onvisibilitychange={handleVisibilityChange} />

<main>
	<p>Current visibility: {visibilityState}</p>
</main>

Tentar colocar <svelte:document> dentro de blocos condicionais ou elementos acionará um erro do compilador. Essa restrição existe porque o Svelte precisa registrar ouvintes em nível de documento durante a inicialização do componente, não condicionalmente durante a renderização. O compilador impõe isso para evitar comportamento de tempo de execução confuso, onde ouvintes podem ou não existir com base em condições de renderização.

<script>
	let showDocumentHandler = $state(true);
</script>

<!-- NCORRECT: This will cause a compiler error -->
{#if showDocumentHandler}
	<svelte:document onvisibilitychange={handleChange} />
{/if}

<!--INCORRECT: Cannot nest inside elements -->
<div>
	<svelte:document onvisibilitychange={handleChange} />
</div>

A razão por trás dessa restrição conecta-se à estratégia de compilação do Svelte. Elementos especiais como <svelte:document> compilam para chamadas diretas de API DOM durante a inicialização do componente. Colocá-los dentro de blocos condicionais exigiria gerenciamento dinâmico de ouvintes com coordenação complexa do ciclo de vida, anulando a simplicidade que torna esses elementos valiosos.

Tratamento de Eventos no Document

O caso de uso principal para <svelte:document> envolve ouvir eventos específicos do documento. O Svelte 5 usa a sintaxe moderna oneventname em vez da diretiva legada on:eventname, alinhando-se com os padrões nativos do DOM e melhorando o desempenho por meio de delegação de eventos.

O Evento visibilitychange

O evento visibilitychange representa o exemplo canônico de uso do <svelte:document>. Este evento dispara sempre que o estado de visibilidade da página muda — quando os usuários alternam abas do navegador, minimizam janelas ou navegam para aplicações diferentes.

<script>
	let isPageVisible = $state(true)
	let lastVisibilityChange = $state(null)
	let hiddenDuration = $state(0)
	let hiddenStartTime = $state(null)

	function handleVisibilityChange(event) {
		const now = new Date()
		lastVisibilityChange = now.toLocaleTimeString()

		if (document.visibilityState === 'hidden') {
			isPageVisible = false
			hiddenStartTime = Date.now()
		} else {
			isPageVisible = true
			if (hiddenStartTime) {
				hiddenDuration += Date.now() - hiddenStartTime
				hiddenStartTime = null
			}
		}
	}
</script>

<svelte:document onvisibilitychange={handleVisibilityChange} />

<div class="visibility-tracker">
	<div class={{ status: true, visible: isPageVisible, hidden: !isPageVisible }}>
		{isPageVisible ? '👁️ Page Visible' : '🙈 Page Hidden'}
	</div>

	{#if lastVisibilityChange}
		<p>Last change: {lastVisibilityChange}</p>
	{/if}

	<p>Total time hidden: {Math.round(hiddenDuration / 1000)} seconds</p>
</div>

<style>
	.status {
		padding: 1rem;
		border-radius: 0.5rem;
		font-weight: bold;
		transition: all 0.3s ease;
	}

	.visible {
		background: #d4edda;
		color: #155724;
	}

	.hidden {
		background: #f8d7da;
		color: #721c24;
	}
</style>

Esse padrão é extremamente valioso para aplicações que precisam pausar operações custosas quando os usuários navegam para fora. Reprodutores de vídeo podem pausar a reprodução, sistemas de análise podem rastrear o tempo de engajamento com precisão, e aplicações em tempo real podem reduzir o polling ao servidor quando a página não está visível.

Eventos de Seleção e Área de Transferência

O objeto document serve como alvo para vários eventos relacionados a seleção e área de transferência que não borbulham para o window:

<script>
	let selectedText = $state('')
	let selectionCount = $state(0)
	let clipboardHistory = $state([])

	function handleSelectionChange() {
		const selection = document.getSelection()
		const text = selection?.toString() || ''

		if (text !== selectedText) {
			selectedText = text
			if (text) {
				selectionCount++
			}
		}
	}

	function handleCopy(event) {
		const copiedText = document.getSelection()?.toString()
		if (copiedText) {
			clipboardHistory = [
				{ text: copiedText, timestamp: new Date() },
				...clipboardHistory.slice(0, 9)
			]
		}
	}

	function handlePaste(event) {
		const pastedData = event.clipboardData?.getData('text')
		console.log('User pasted:', pastedData)
	}
</script>

<svelte:document
	onselectionchange={handleSelectionChange}
	oncopy={handleCopy}
	onpaste={handlePaste}
/>

<article>
	<h2>Text Selection Tracker</h2>
	<p>
		Select any text on this page to see it tracked below. The selection change event fires on the
		document whenever the user's text selection changes, whether by mouse, keyboard, or programmatic
		manipulation.
	</p>

	<p>
		Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum ante ipsum primis in
		faucibus orci luctus et ultrices posuere cubilia curae; Praesent euismod neque non eros
		efficitur, at consequat lorem facilisis.
	</p>
</article>

<aside class="selection-info">
	<h3>Current Selection</h3>
	<pre>{selectedText || '(nothing selected)'}</pre>
	<p>Total selections made: {selectionCount}</p>

	{#if clipboardHistory.length > 0}
		<h3>Copy History</h3>
		<ul>
			{#each clipboardHistory as entry}
				<li>
					<span class="timestamp">{entry.timestamp.toLocaleTimeString()}</span>
					<code>{entry.text.slice(0, 50)}{entry.text.length > 50 ? '...' : ''}</code>
				</li>
			{/each}
		</ul>
	{/if}
</aside>

Eventos de Tela Cheia

Gerenciar o estado de tela cheia requer tratamento de eventos em nível de documento, pois os eventos fullscreenchange e fullscreenerror disparam no document:

<script>
	let isFullscreen = $state(false)
	let fullscreenElement = $state(null)
	let fullscreenError = $state(null)

	function handleFullscreenChange() {
		isFullscreen = !!document.fullscreenElement
		fullscreenElement = document.fullscreenElement?.tagName || null

		if (!isFullscreen) {
			console.log('Exited fullscreen mode')
		}
	}

	function handleFullscreenError(event) {
		fullscreenError = 'Failed to enter fullscreen mode. The browser may have blocked the request.'
		setTimeout(() => (fullscreenError = null), 5000)
	}

	async function toggleFullscreen(element) {
		try {
			if (!document.fullscreenElement) {
				await element.requestFullscreen()
			} else {
				await document.exitFullscreen()
			}
		} catch (err) {
			fullscreenError = err.message
		}
	}

	let videoContainer
</script>

<svelte:document
	onfullscreenchange={handleFullscreenChange}
	onfullscreenerror={handleFullscreenError}
/>

<div class="fullscreen-demo">
	<div bind:this={videoContainer} class={['video-container', isFullscreen && 'fullscreen']}>
		<div class="video-placeholder">
			<p>Video Content Area</p>
			<p class="status">
				{isFullscreen ? 'Currently in fullscreen' : 'Normal view'}
			</p>
		</div>

		<button onclick={() => toggleFullscreen(videoContainer)}>
			{isFullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
		</button>
	</div>

	{#if fullscreenError}
		<div class="error-message" role="alert">
			{fullscreenError}
		</div>
	{/if}

	{#if fullscreenElement}
		<p>Fullscreen element: <code>&lt;{fullscreenElement.toLowerCase()}&gt;</code></p>
	{/if}
</div>

Bindings Reativos: Lendo o Estado do Document

Além do tratamento de eventos, <svelte:document> fornece bindings reativos para quatro propriedades do documento. Ao contrário de muitos bindings de elementos no Svelte, todos os bindings do documento são somente leitura — você pode observar seus valores, mas não pode defini-los programaticamente por meio de binding.

Binding activeElement

A propriedade activeElement rastreia qual elemento DOM tem foco atualmente. Esse binding é atualizado de forma reativa conforme os usuários navegam por campos de formulário com Tab, clicam em elementos interativos ou quando o foco é movido programaticamente:

<script>
	let activeElement = $state(null)
	let focusHistory = $state([])

	$effect(() => {
		if (activeElement) {
			const elementDescription = describeElement(activeElement)

			if (focusHistory[0]?.description !== elementDescription) {
				focusHistory = [
					{ description: elementDescription, time: new Date() },
					...focusHistory.slice(0, 19)
				]
			}
		}
	})

	function describeElement(el) {
		if (!el) return 'None'

		const tag = el.tagName.toLowerCase()
		const id = el.id ? `#${el.id}` : ''
		const className = el.className ? `.${el.className.split(' ')[0]}` : ''
		const name = el.name ? `[name="${el.name}"]` : ''
		const type = el.type ? `[type="${el.type}"]` : ''

		return `${tag}${id}${className}${name}${type}`
	}
</script>

<svelte:document bind:activeElement />

<div class="focus-tracker">
	<div class="current-focus">
		<h3>Currently Focused Element</h3>
		<code class="element-display">
			{describeElement(activeElement)}
		</code>
	</div>

	<form class="demo-form">
		<h3>Test Form</h3>

		<div class="field">
			<label for="username">Username</label>
			<input type="text" id="username" name="username" placeholder="Enter username" />
		</div>

		<div class="field">
			<label for="email">Email</label>
			<input type="email" id="email" name="email" placeholder="Enter email" />
		</div>

		<div class="field">
			<label for="password">Password</label>
			<input type="password" id="password" name="password" placeholder="Enter password" />
		</div>

		<div class="field">
			<label for="role">Role</label>
			<select id="role" name="role">
				<option>Developer</option>
				<option>Designer</option>
				<option>Manager</option>
			</select>
		</div>

		<div class="actions">
			<button type="button">Cancel</button>
			<button type="submit">Submit</button>
		</div>
	</form>

	<div class="focus-history">
		<h3>Focus History</h3>
		<ol reversed>
			{#each focusHistory as entry}
				<li>
					<code>{entry.description}</code>
					<small>{entry.time.toLocaleTimeString()}</small>
				</li>
			{/each}
		</ol>
	</div>
</div>

O binding activeElement habilita padrões sofisticados de gerenciamento de foco, melhorias de acessibilidade e sistemas de navegação por teclado. É particularmente valioso para diálogos modais que precisam prender o foco, implementações de skip-link e validação de formulário complexa que responde ao foco de campo.

Binding visibilityState

Enquanto o evento visibilitychange informa quando a visibilidade muda, o binding visibilityState fornece acesso reativo ao estado atual:

<script>
	let visibilityState = $state('visible')
	let pollInterval = $state(null)
	let dataFetchCount = $state(0)

	$effect(() => {
		if (visibilityState === 'visible') {
			pollInterval = setInterval(() => {
				fetchLatestData()
			}, 5000)

			fetchLatestData()

			return () => {
				clearInterval(pollInterval)
			}
		} else {
			console.log('Polling paused - page hidden')
		}
	})

	async function fetchLatestData() {
		dataFetchCount++
		console.log(`Fetch #${dataFetchCount} - Page is ${visibilityState}`)
	}
</script>

<svelte:document bind:visibilityState />

<div class="polling-demo">
	<h2>Visibility-Aware Polling</h2>

	<div class="status-card" data-visibility={visibilityState}>
		<span class="indicator"></span>
		<span>Page is {visibilityState}</span>
	</div>

	<p>Data fetches performed: <strong>{dataFetchCount}</strong></p>

	<p class="explanation">
		This component automatically pauses API polling when you switch to another tab and resumes when
		you return. Try switching tabs and watch the fetch count!
	</p>
</div>

<style>
	.status-card {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		padding: 1rem;
		border-radius: 0.5rem;
		background: #f0f0f0;
	}

	.indicator {
		width: 12px;
		height: 12px;
		border-radius: 50%;
		background: #28a745;
	}

	[data-visibility='hidden'] .indicator {
		background: #dc3545;
	}
</style>

Bindings fullscreenElement e pointerLockElement

Esses bindings fornecem acesso reativo ao elemento de tela cheia atual e a qualquer elemento que tenha capturado o bloqueio do ponteiro:

<script>
	let fullscreenElement = $state(null)
	let pointerLockElement = $state(null)

	let gameCanvas

	$effect(() => {
		if (pointerLockElement === gameCanvas) {
			console.log('Game has pointer lock - mouse movement now controls the game')
		}
	})

	function startGame() {
		gameCanvas?.requestPointerLock()
	}

	function handleMouseMove(event) {
		if (pointerLockElement === gameCanvas) {
			console.log('Mouse delta:', event.movementX, event.movementY)
		}
	}
</script>

<svelte:document bind:fullscreenElement bind:pointerLockElement />

<div class="game-container">
	<canvas
		bind:this={gameCanvas}
		width="800"
		height="600"
		onmousemove={handleMouseMove}
		onclick={startGame}
	></canvas>

	<div class="game-status">
		{#if pointerLockElement}
			<p>🎮 Pointer locked to: {pointerLockElement.tagName}</p>
			<p><kbd>Esc</kbd> to release</p>
		{:else}
			<p>Click canvas to capture pointer</p>
		{/if}

		{#if fullscreenElement}
			<p>📺 Fullscreen active</p>
		{/if}
	</div>
</div>

Integrando Attachments com `<svelte:document>`

O Svelte 5.29 introduziu attachments por meio da diretiva {@attach ...} como a forma moderna e totalmente reativa de anexar comportamentos a elementos. Attachments são funções que executam em um effect quando um elemento é montado e podem opcionalmente retornar uma função de limpeza. Ao contrário da diretiva use: mais antiga (actions), attachments são totalmente reativos — eles re-executam automaticamente quando qualquer estado lido dentro deles muda.

O elemento especial <svelte:document> suporta tanto a diretiva legada use: quanto a sintaxe moderna {@attach ...}, permitindo encapsular comportamentos reutilizáveis em nível de documento.

Entendendo Attachments vs Actions

Antes de mergulhar no uso em nível de documento, vamos esclarecer a distinção entre essas duas abordagens:

Actions (use:): Executam uma vez quando o elemento é montado. Elas não re-executam automaticamente quando os argumentos mudam (embora possam usar blocos internos $effect para reatividade). Actions são a abordagem legada, mas continuam suportadas.

Attachments ({@attach ...}): Executam em um contexto de effect, tornando-os totalmente reativos. Quando o estado lido dentro do attachment muda, o attachment inteiro re-executa (a função de limpeza é chamada primeiro, depois o attachment executa novamente). Esta é a abordagem recomendada no Svelte 5.29+.

<script>
	let count = $state(0)

	// Action approach (legacy) - does NOT re-run when count changes
	function actionExample(node, initialCount) {
		console.log('Action ran with:', initialCount)
		// Would need internal $effect to react to changes
	}

	// Attachment approach (modern) - automatically re-runs when count changes
	function attachmentExample(node) {
		console.log('Attachment ran with:', count)
		return () => console.log('Attachment cleanup')
	}
</script>

<!-- Legacy action syntax -->
<div use:actionExample={count}></div>

<!-- Modern attachment syntax - fully reactive -->
<div {@attach attachmentExample}></div>

Attachments em Nível de Documento: Detecção de Inatividade

Um caso de uso poderoso para attachments em nível de documento é implementar detecção de inatividade que reage a mudanças de configuração:

<script>
	let userIsIdle = $state(false)
	let idleTimeout = $state(10000)
	let lastActivity = $state(new Date())

	/**
	 * Attachment factory for idle detection
	 * @param {number} timeout - Milliseconds before considering user idle
	 * @returns {import('svelte/attachments').Attachment<Document>}
	 */
	function idleTracker(timeout) {
		return (node) => {
			let idleTimer

			function resetTimer() {
				clearTimeout(idleTimer)

				if (userIsIdle) {
					userIsIdle = false
				}
				lastActivity = new Date()

				idleTimer = setTimeout(() => {
					userIsIdle = true
				}, timeout)
			}

			const activityEvents = ['mousedown', 'mousemove', 'keydown', 'scroll', 'touchstart']

			activityEvents.forEach((event) => {
				node.addEventListener(event, resetTimer, { passive: true })
			})

			resetTimer()

			// Cleanup function - runs before re-run or on unmount
			return () => {
				clearTimeout(idleTimer)
				activityEvents.forEach((event) => {
					node.removeEventListener(event, resetTimer)
				})
			}
		}
	}
</script>

<!--
	Because idleTracker(idleTimeout) runs in an effect context,
	changing idleTimeout will automatically tear down and recreate
	the idle tracker with the new timeout value!
-->
<svelte:document {@attach idleTracker(idleTimeout)} />

<div class="idle-demo">
	<header>
		<h2>Reactive Idle Detection</h2>

		<div class={['user-status', userIsIdle && 'idle']}>
			{userIsIdle ? '💤 User Idle' : '✨ User Active'}
		</div>
	</header>

	<div class="controls">
		<label>
			Idle timeout (seconds):
			<input
				type="range"
				min="5"
				max="60"
				bind:value={() => idleTimeout / 1000, (v) => (idleTimeout = v * 1000)}
			/>
			<span>{idleTimeout / 1000}s</span>
		</label>
	</div>

	<p class="last-activity">
		Last activity: {lastActivity.toLocaleTimeString()}
	</p>

	<p class="explanation">
		Try adjusting the timeout slider—the idle tracker automatically reconfigures itself with the new
		value thanks to attachment reactivity!
	</p>
</div>

<style>
	.user-status {
		padding: 0.5rem 1rem;
		border-radius: 0.5rem;
		font-weight: bold;
		background: #d4edda;
		color: #155724;
		transition: all 0.3s ease;
	}

	.user-status.idle {
		background: #fff3cd;
		color: #856404;
	}
</style>

Atalhos de Teclado com Configuração Reativa

Outro padrão poderoso envolve atalhos de teclado que podem ser reconfigurados dinamicamente:

<script>
	let lastShortcut = $state('')
	let showCommandPalette = $state(false)
	let shortcutsEnabled = $state(true)

	/**
	 * Creates an attachment for keyboard shortcut handling
	 * @param {Record<string, (event: KeyboardEvent) => void>} shortcuts
	 * @returns {import('svelte/attachments').Attachment<Document>}
	 */
	function keyboardShortcuts(shortcuts) {
		return (node) => {
			function handleKeydown(event) {
				if (!shortcutsEnabled) return

				const key = []
				if (event.ctrlKey || event.metaKey) key.push('ctrl')
				if (event.shiftKey) key.push('shift')
				if (event.altKey) key.push('alt')
				key.push(event.key.toLowerCase())

				const combo = key.join('+')

				if (shortcuts[combo]) {
					event.preventDefault()
					shortcuts[combo](event)
					lastShortcut = combo
				}
			}

			node.addEventListener('keydown', handleKeydown)

			return () => {
				node.removeEventListener('keydown', handleKeydown)
			}
		}
	}

	// Define shortcuts - changing this object will trigger attachment re-run
	let shortcuts = $derived({
		'ctrl+k': () => (showCommandPalette = !showCommandPalette),
		'ctrl+s': () => console.log('Save triggered'),
		'ctrl+shift+p': () => console.log('Quick actions'),
		escape: () => (showCommandPalette = false)
	})
</script>

<svelte:document {@attach keyboardShortcuts(shortcuts)} />

<div class="shortcuts-demo">
	<header>
		<h2>Keyboard Shortcuts</h2>

		<label class="toggle">
			<input type="checkbox" bind:checked={shortcutsEnabled} />
			Shortcuts {shortcutsEnabled ? 'enabled' : 'disabled'}
		</label>
	</header>

	<section class="shortcuts-list">
		<h3>Available Shortcuts</h3>
		<ul>
			<li><kbd>Ctrl</kbd> + <kbd>K</kbd> — Toggle Command Palette</li>
			<li><kbd>Ctrl</kbd> + <kbd>S</kbd> — Save</li>
			<li><kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> — Quick Actions</li>
			<li><kbd>Escape</kbd> — Close dialogs</li>
		</ul>

		{#if lastShortcut}
			<p class="last-shortcut">Last used: <code>{lastShortcut}</code></p>
		{/if}
	</section>

	{#if showCommandPalette}
		<div class="command-palette" role="dialog" aria-label="Command Palette">
			<input type="text" placeholder="Type a command..." autofocus />
			<p class="hint">Press <kbd>Escape</kbd> to close</p>
		</div>
	{/if}
</div>

<style>
	.command-palette {
		position: fixed;
		top: 20%;
		left: 50%;
		transform: translateX(-50%);
		background: white;
		padding: 1.5rem;
		border-radius: 0.5rem;
		box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
		z-index: 1000;
	}

	.command-palette input {
		width: 300px;
		padding: 0.75rem;
		font-size: 1rem;
		border: 1px solid #ddd;
		border-radius: 0.25rem;
	}

	kbd {
		background: #eee;
		padding: 0.2rem 0.4rem;
		border-radius: 0.25rem;
		font-family: monospace;
		font-size: 0.9em;
	}
</style>

Attachments Inline para Comportamento em Nível de Documento

Para casos mais simples, você pode definir attachments inline diretamente no <svelte:document>:

<script>
	let documentClickCount = $state(0)
	let lastClickTarget = $state('')
</script>

<svelte:document
	{@attach (doc) => {
		function handleClick(event) {
			documentClickCount++
			lastClickTarget = event.target?.tagName || 'unknown'
		}

		doc.addEventListener('click', handleClick)

		return () => {
			doc.removeEventListener('click', handleClick)
		}
	}}
/>

<div class="click-tracker">
	<p>Document clicks: {documentClickCount}</p>
	<p>Last clicked element: <code>{lastClickTarget || 'none'}</code></p>
</div>

Controlando a Re-execução de Attachments

Como attachments são totalmente reativos, eles re-executam sempre que qualquer estado lido dentro deles muda. Para operações de configuração custosas, você pode querer isolar as partes reativas em um effect aninhado:

<script>
	let config = $state({ threshold: 100, debug: false })

	/**
	 * Attachment with expensive setup that shouldn't re-run on every config change
	 * @returns {import('svelte/attachments').Attachment<Document>}
	 */
	function expensiveDocumentBehavior() {
		return (node) => {
			// Expensive setup - only runs once per mount
			console.log('Expensive setup work...')
			const observer = new IntersectionObserver(() => {})

			// Reactive part - runs when config changes
			$effect(() => {
				console.log('Config changed:', config.threshold, config.debug)
				// React to config changes without re-running expensive setup
			})

			return () => {
				observer.disconnect()
			}
		}
	}
</script>

<svelte:document {@attach expensiveDocumentBehavior()} />

Convertendo Actions Legadas para Attachments

Se você estiver usando bibliotecas de terceiros que fornecem actions, pode convertê-las para attachments usando o utilitário fromAction de svelte/attachments:

<script>
	import { fromAction } from 'svelte/attachments'
	import { someLibraryAction } from 'some-library'

	// Convert the action to an attachment
	const attachableVersion = fromAction(someLibraryAction)
</script>

<!-- Now usable with {@attach ...} syntax -->
<svelte:document {@attach attachableVersion(options)} />

Coordenando Múltiplos Elementos Especiais

Aplicações do mundo real frequentemente precisam coordenar eventos de document, window e body juntos. Entender como esses três elementos especiais diferem ajuda a escolher a ferramenta certa para cada situação:

<script>
	// Window-specific: scroll position, resize, online/offline
	let scrollY = $state(0)
	let innerWidth = $state(0)
	let online = $state(true)

	// Document-specific: visibility, active element, fullscreen
	let visibilityState = $state('visible')
	let activeElement = $state(null)

	// Body-specific: mouse enter/leave the viewport
	let mouseInViewport = $state(true)

	// Derived state combining multiple sources
	let userEngagement = $derived.by(() => {
		if (visibilityState === 'hidden') return 'away'
		if (!mouseInViewport) return 'distracted'
		if (!activeElement || activeElement === document.body) return 'passive'
		return 'engaged'
	})

	$effect(() => {
		console.log(`User engagement level: ${userEngagement}`)

		if (userEngagement === 'away') {
			// Pause expensive operations
		} else if (userEngagement === 'engaged') {
			// Full operation mode
		}
	})
</script>

<!-- Window bindings for viewport and network state -->
<svelte:window bind:scrollY bind:innerWidth bind:online />

<!-- Document bindings for page-level state -->
<svelte:document bind:visibilityState bind:activeElement />

<!-- Body events for mouse presence detection -->
<svelte:body
	onmouseenter={() => (mouseInViewport = true)}
	onmouseleave={() => (mouseInViewport = false)}
/>

<div class="engagement-dashboard">
	<h2>User Engagement Monitor</h2>

	<div class="metrics-grid">
		<div class="metric">
			<span class="label">Engagement</span>
			<span class="value" data-level={userEngagement}>{userEngagement}</span>
		</div>

		<div class="metric">
			<span class="label">Page Visible</span>
			<span class="value">{visibilityState === 'visible' ? '✓' : '✗'}</span>
		</div>

		<div class="metric">
			<span class="label">Mouse in Viewport</span>
			<span class="value">{mouseInViewport ? '✓' : '✗'}</span>
		</div>

		<div class="metric">
			<span class="label">Network</span>
			<span class="value">{online ? 'Online' : 'Offline'}</span>
		</div>

		<div class="metric">
			<span class="label">Scroll Position</span>
			<span class="value">{Math.round(scrollY)}px</span>
		</div>

		<div class="metric">
			<span class="label">Viewport Width</span>
			<span class="value">{innerWidth}px</span>
		</div>
	</div>
</div>

Considerações sobre Renderização do Lado do Servidor

Os elementos especiais do Svelte são projetados com segurança SSR em mente. O elemento <svelte:document> compila para código que só executa em ambientes de navegador, prevenindo erros de "document is not defined" durante a renderização no servidor.

No entanto, você ainda deve ter cuidado com o código no seu bloco <script> que referencia globais do navegador:

<script>
	// DANGEROUS: This runs during SSR and will crash
	// const state = document.visibilityState;

	// SAFE: Initialize with a sensible default
	let visibilityState = $state('visible')

	// SAFE: Use $effect for browser-only code
	$effect(() => {
		// This only runs in the browser after mount
		visibilityState = document.visibilityState
	})

	// SAFE: Check for browser environment explicitly
	function checkDocumentState() {
		if (typeof document === 'undefined') return
		// Safe to access document here
	}
</script>

<svelte:document bind:visibilityState />

O binding em si lida com o caso SSR de forma elegante — bind:visibilityState não causará erros durante a renderização no servidor. Mas qualquer código imperativo que acesse document diretamente precisa de proteção.

Para aplicações SvelteKit, use a verificação browser de $app/environment:

<script>
	import { browser } from '$app/environment'

	let activeElement = $state(null)
	let documentTitle = $state('')

	$effect(() => {
		if (!browser) return

		documentTitle = document.title

		const observer = new MutationObserver(() => {
			documentTitle = document.title
		})

		const titleElement = document.querySelector('title')
		if (titleElement) {
			observer.observe(titleElement, { childList: true })
		}

		return () => observer.disconnect()
	})
</script>

<svelte:document bind:activeElement />

<div>
	<p>Current page title: {documentTitle}</p>
	<p>Active element: {activeElement?.tagName || 'None'}</p>
</div>

Padrão Avançado: Construindo uma Armadilha de Foco

A armadilha de foco é essencial para diálogos modais acessíveis. Usando <svelte:document> combinado com o binding activeElement, podemos construir uma armadilha de foco robusta:

<script>
	let activeElement = $state(null)
	let trapContainer = $state(null)
	let isTrapping = $state(false)
	let previousActiveElement = null

	export function activate(container) {
		trapContainer = container
		isTrapping = true
		previousActiveElement = activeElement

		const firstFocusable = getFirstFocusable(container)
		firstFocusable?.focus()
	}

	export function deactivate() {
		isTrapping = false
		trapContainer = null

		previousActiveElement?.focus()
		previousActiveElement = null
	}

	function getFirstFocusable(container) {
		return container?.querySelector(
			'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
		)
	}

	function getAllFocusable(container) {
		return Array.from(
			container?.querySelectorAll(
				'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
			) || []
		)
	}

	function handleKeydown(event) {
		if (!isTrapping || !trapContainer) return

		if (event.key === 'Tab') {
			const focusable = getAllFocusable(trapContainer)
			const firstFocusable = focusable[0]
			const lastFocusable = focusable[focusable.length - 1]

			if (event.shiftKey && activeElement === firstFocusable) {
				event.preventDefault()
				lastFocusable?.focus()
			} else if (!event.shiftKey && activeElement === lastFocusable) {
				event.preventDefault()
				firstFocusable?.focus()
			}
		}

		if (event.key === 'Escape') {
			deactivate()
		}
	}

	// Guard against focus leaving the trap
	$effect(() => {
		if (!isTrapping || !trapContainer || !activeElement) return

		if (!trapContainer.contains(activeElement)) {
			const firstFocusable = getFirstFocusable(trapContainer)
			firstFocusable?.focus()
		}
	})
</script>

<svelte:document bind:activeElement onkeydown={handleKeydown} />

Armadilhas Comuns e Como Evitá-las

1. Esquecer que os Bindings São Somente Leitura

Todos os bindings de <svelte:document> são somente leitura. Tentar defini-los programaticamente não funcionará:

<script>
	let activeElement = $state(null)

	function focusSpecificElement() {
		// THIS DOESN'T WORK - activeElement binding is readonly
		// activeElement = document.getElementById('target');

		// PREFERRED:Instead, focus the element directly
		document.getElementById('target')?.focus()
		// The binding will automatically update to reflect the new focus
	}
</script>

<svelte:document bind:activeElement />

2. Criando Vazamentos de Memória com Effects

Ao usar $effect para responder a mudanças de estado do documento, sempre retorne funções de limpeza para quaisquer recursos que você criar:

<script>
	let visibilityState = $state('visible')

	// AVOID: MEMORY LEAK: Interval never cleaned up
	$effect(() => {
		if (visibilityState === 'visible') {
			setInterval(() => console.log('tick'), 1000)
		}
	})

	// PREFERRED: Return cleanup function
	$effect(() => {
		if (visibilityState === 'visible') {
			const interval = setInterval(() => console.log('tick'), 1000)
			return () => clearInterval(interval)
		}
	})
</script>

<svelte:document bind:visibilityState />

3. Attachments Re-executando com Muita Frequência

Os attachments re-executam sempre que qualquer estado lido dentro deles muda. Fique atento ao estado que você acessa:

<script>
	let config = $state({ timeout: 5000, label: 'test' });

	// AVOID PROBLEM: Re-runs on ANY config property change, even label
	function problematicAttachment() {
		return (node) => {
			console.log('Setup with timeout:', config.timeout);
			// Reading config.timeout makes attachment dependent on entire config object
			return () => console.log('Cleanup');
		};
	}

	// PREFERRED: Pass only what you need
	function betterAttachment(timeout) {
		return (node) => {
			console.log('Setup with timeout:', timeout);
			return () => console.log('Cleanup');
		};
	}
</script>

<!-- Re-runs on any config change -->
<svelte:document {@attach problematicAttachment()} />

<!-- Only re-runs when timeout changes -->
<svelte:document {@attach betterAttachment(config.timeout)} />

4. Depender Excessivamente de Eventos do Documento

Alguns eventos para os quais você pode esperar precisar de <svelte:document> funcionam bem em <svelte:window> ou em elementos regulares. Use o alvo mais específico possível:

<!-- AVOID: Overkill: keydown events bubble, use svelte:window or element instead -->
<svelte:document onkeydown={handleKeydown} />

<!-- PREFERRED: svelte:window for global keyboard shortcuts -->
<svelte:window onkeydown={handleKeydown} />

<!-- BEST: Element-level for scoped keyboard handling -->
<div onkeydown={handleKeydown} tabindex="0">
	<!-- content -->
</div>

Reserve <svelte:document> para eventos que realmente só disparam no objeto document: visibilitychange, selectionchange, fullscreenchange e eventos similares específicos do documento.

5. Não Tratar o Estado Inicial

Os bindings do documento podem não ter seus valores esperados imediatamente na montagem do componente. Projete sua lógica para lidar com estados indefinidos ou iniciais de forma elegante:

<script>
	let activeElement = $state(null)

	// AVOID FRAGILE: Assumes activeElement is always defined
	$effect(() => {
		console.log(activeElement.tagName) // May throw!
	})

	// PREFERRED ROBUST: Guard against null/undefined
	$effect(() => {
		if (activeElement) {
			console.log(activeElement.tagName)
		}
	})
</script>

<svelte:document bind:activeElement />

Resumo das Boas Práticas

Ao trabalhar com <svelte:document> no Svelte 5, tenha estes princípios em mente:

Use <svelte:document> especificamente para preocupações em nível de documento. Eventos como visibilitychange, selectionchange e fullscreenchange disparam apenas no documento. Propriedades como activeElement e visibilityState existem apenas no documento. Não o use para eventos que poderiam ser tratados em um nível mais específico.

Prefira attachments ({@attach ...}) em vez de actions (use:) para código novo. Os attachments fornecem reatividade completa out of the box e se integram melhor com o modelo reativo do Svelte 5. Use fromAction de svelte/attachments para converter actions legadas quando necessário.

Combine bindings declarativos com $effect para padrões reativos poderosos. O binding fornece acesso reativo ao estado do documento; os effects permitem que você responda a esse estado com efeitos colaterais, limpeza e lógica complexa.

Lembre-se da segurança no SSR. Embora o próprio <svelte:document> lide com o SSR de forma elegante, qualquer código imperativo no seu bloco de script que acessa document diretamente precisa de proteção via effects ou verificações de ambiente.

Fique atento à reatividade dos attachments. Os attachments re-executam quando qualquer estado lido dentro deles muda. Passe apenas os valores específicos necessários, ou use effects aninhados para operações de configuração custosas que não devem re-executar.

Coordene com <svelte:window> e <svelte:body> de forma cuidadosa. Cada elemento especial serve a um propósito distinto na hierarquia do DOM. Entender quais eventos e propriedades pertencem a cada um ajuda você a construir componentes mais limpos e de fácil manutenção.

Conclusão

O elemento especial <svelte:document> representa o compromisso do Svelte em tornar as APIs do DOM acessíveis de forma reativa e declarativa, enquanto lida com a complexidade do gerenciamento de ciclo de vida, compatibilidade com SSR e limpeza automática. Ao fazer a ponte entre as APIs imperativas do navegador e o modelo de componente reativo do Svelte, ele permite interações sofisticadas — desde otimização de desempenho com consciência de visibilidade até recursos de edição colaborativa — sem sacrificar a experiência do desenvolvedor ou a manutenibilidade do código.

Dominar o <svelte:document> requer compreender não apenas sua sintaxe, mas o contexto mais amplo de como documentos, janelas e bodies interagem no modelo de eventos do navegador. A introdução dos attachments no Svelte 5.29 aprimora ainda mais o poder desse elemento, fornecendo reatividade completa e composabilidade para interações em nível de documento.

À medida que você constrói aplicações cada vez mais sofisticadas, os padrões explorados aqui — rastreamento de visibilidade, gerenciamento de foco, coordenação de tela cheia e reatividade baseada em attachments — serão inestimáveis para criar aplicações que respondem de forma inteligente à presença do usuário e às mudanças de estado do documento.

Principais Conclusões

<svelte:document> fornece acesso declarativo a eventos e propriedades em nível de documento com segurança SSR automática, tratando eventos como visibilitychange, selectionchange, fullscreenchange e propriedades como activeElement, visibilityState
Os bindings reativos habilitam fluxo de dados bidirecional com propriedades somente leitura (activeElement, pointerLockElement, fullscreenElement, visibilityState, pictureInPictureElement) fornecendo o estado atual do documento
Attachments ({@attach}) são preferidos em relação às actions no Svelte 5.29+, oferecendo reatividade completa, composabilidade, suporte inline e melhor integração com TypeScript em comparação com a sintaxe legada use:
O rastreamento de visibilidade otimiza desempenho e UX pausando animações, adiando atualizações e gerenciando operações com uso intensivo de recursos quando os usuários alternam abas ou minimizam janelas
A detecção de mudança de seleção habilita edição colaborativa com recursos como sincronização de posição do cursor, barras de ferramentas de formatação de texto e encadeamento de comentários em tempo real
As APIs de tela cheia e bloqueio de ponteiro requerem gestos do usuário, o que significa que requestFullscreen() ou requestPointerLock() programáticos devem ser acionados por cliques de botão ou outras interações do usuário
Combinar $derived com bindings do documento cria padrões reativos que respondem automaticamente às mudanças de estado sem gerenciamento manual de effects ou atualizações de manipuladores de eventos
A segurança no SSR é integrada para o próprio <svelte:document>, mas o acesso imperativo ao document em blocos de script requer encapsulamento com $effect ou verificações de ambiente (typeof document !== 'undefined')

Veja Também

Documentação Oficial do Svelte 5 - <svelte:document>
MDN Web Docs - Interface Document
API de Visibilidade de Página - Entendendo estados de visibilidade e otimização de desempenho
API de Tela Cheia - Guia completo para o modo tela cheia e requisitos de gestos do usuário
API de Bloqueio de Ponteiro - Controles em primeira pessoa e movimento irrestrito do mouse
API de Seleção - Trabalhando com seleção de texto e intervalos em documentos