## docs/svelte/01-introduction/01-overview.md

# Svelte Overview

Svelte is a UI framework that compiles components into optimized JavaScript. Use it for anything from standalone components to full stack apps with SvelteKit.

```svelte
<!file: App.svelte>
<script>
	function greet() {
		alert('Welcome to Svelte!');
	}
</script>

<button onclick={greet}>click me</button>

<style>
	button {
		font-size: 2em;
	}
</style>
```

For beginners, start with the [interactive tutorial](/tutorial). Try Svelte online in the [playground](/playground) or on [StackBlitz](https://sveltekit.new).

## docs/svelte/01-introduction/02-getting-started.md

# Getting Started with Svelte 5

## Quick Start

```bash
npx sv create myapp
cd myapp
npm install
npm run dev
```

SvelteKit is the recommended framework for most projects. Alternatively:

```bash
npm create vite@latest
# Select svelte option
```

## Editor Support

- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)
- Command line: `sv check`

## Help Resources

- [Discord](/chat)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/svelte)

## docs/svelte/01-introduction/03-svelte-files.md

# Svelte Components (.svelte files)

Components are written in `.svelte` files with three optional sections:

```svelte
<script module>
	// runs once when module evaluates
</script>

<script>
	// runs for each component instance
</script>

<style>
	/* component-scoped styles */
</style>
```

## `<script>`

Contains JavaScript/TypeScript (use `lang="ts"`) that runs when a component instance is created. Top-level variables are accessible in markup.

## `<script module>`

Runs once when the module evaluates. Variables can be referenced in the component, but not vice versa.

```svelte
<script module>
	let total = 0;
</script>

<script>
	total += 1;
	console.log(`instantiated ${total} times`);
</script>
```

You can `export` bindings from this block (except `export default`).

## `<style>`

CSS is automatically scoped to the component:

```svelte
<style>
	p {
		/* only affects <p> elements in this component */
		color: burlywood;
	}
</style>
```

## docs/svelte/01-introduction/04-svelte-js-files.md

# .svelte.js and .svelte.ts files

Svelte 5 operates on `.svelte.js` and `.svelte.ts` files in addition to `.svelte` files.

These files:
- Behave like regular JS/TS modules
- Support runes for reactive logic
- Allow sharing reactive state across your app

```js
// store.svelte.js
export let $state count = 0;
export const increment = () => count += 1;
```

> Note: You cannot export reassigned state across modules.

## docs/svelte/02-runes/01-what-are-runes.md

# Svelte 5 Runes

Runes are compiler-controlled symbols in `.svelte` and `.svelte.js`/`.svelte.ts` files with a `$` prefix.

## Key Characteristics

- No imports needed - built into Svelte
- Not assignable to variables or passable as arguments
- Only valid in specific positions (compiler will warn)
- Always prefixed with `$`

```js
let message = $state('hello');
```

> Runes are new in Svelte 5 and replace the reactive syntax from previous versions.

## docs/svelte/02-runes/02-$state.md

# Svelte 5 Runes - Condensed Documentation

## $state

Creates reactive state that triggers UI updates when changed.

```svelte
<script>
	let count = $state(0);
</script>

<button onclick={() => count++}>
	clicks: {count}
</button>
```

### Deep state

Arrays and objects become deeply reactive state proxies:

```svelte
<script>
	let todos = $state([
		{
			done: false,
			text: 'add more todos'
		}
	]);
</script>
```

- Modifying nested properties triggers UI updates
- New objects added to arrays are automatically proxified
- Destructuring breaks reactivity

### Classes

Use $state in class fields:

```js
class Todo {
	done = $state(false);
	text = $state();

	constructor(text) {
		this.text = text;
	}

	reset() {
		this.text = '';
		this.done = false;
	}
}
```

When using methods, handle `this` context:
```svelte
<!-- Won't work -->
<button onclick={todo.reset}>reset</button>

<!-- Works -->
<button onclick={() => todo.reset()}>reset</button>
```

Or use arrow functions in class:
```js
class Todo {
	// ...
	reset = () => {
		this.text = '';
		this.done = false;
	}
}
```

## $state.raw

For non-deeply reactive state:

```js
let person = $state.raw({
	name: 'Heraclitus',
	age: 49
});

// No effect
person.age += 1;

// Works - creates new object
person = {
	name: 'Heraclitus',
	age: 50
};
```

## $state.snapshot

Create static copy of reactive state:

```svelte
<script>
	let counter = $state({ count: 0 });

	function onclick() {
		console.log($state.snapshot(counter)); // { count: ... } not Proxy
	}
</script>
```

## Passing state

State is passed by value, not by reference:

```js
let a = $state(1);
let b = $state(2);
// Accessing current values
```

For reactive objects:

```js
function add(input) {
	return {
		get value() {
			return input.a + input.b;
		}
	};
}

let input = $state({ a: 1, b: 2 });
let total = add(input);
```

## Cross-module state

Can't export directly reassigned state:

```js
// Not allowed
export let count = $state(0);
export function increment() {
	count += 1;
}
```

Instead, export objects:
```js
// Allowed - updating property, not reassigning
export const counter = $state({
	count: 0
});

export function increment() {
	counter.count += 1;
}
```

Or use getter functions:
```js
let count = $state(0);

export function getCount() {
	return count;
}

export function increment() {
	count += 1;
}
```

## docs/svelte/02-runes/03-$derived.md

# $derived Rune in Svelte 5

The `$derived` rune creates reactive values that automatically update when their dependencies change.

## Basic Usage

```svelte
<script>
	let count = $state(0);
	let doubled = $derived(count * 2);
</script>

<button onclick={() => count++}>
	{doubled}
</button>

<p>{count} doubled is {doubled}</p>
```

> Without `$derived`, `doubled` would not update when `count` changes.

## Complex Derivations with $derived.by

For multi-line derivations, use `$derived.by`:

```svelte
<script>
	let numbers = $state([1, 2, 3]);
	let total = $derived.by(() => {
		let total = 0;
		for (const n of numbers) {
			total += n;
		}
		return total;
	});
</script>

<button onclick={() => numbers.push(numbers.length + 1)}>
	{numbers.join(' + ')} = {total}
</button>
```

`$derived(expression)` is equivalent to `$derived.by(() => expression)`.

## Dependencies

Any state read synchronously inside the `$derived` expression becomes a dependency. Use `untrack` to exempt state from being a dependency.

## Overriding Derived Values

You can temporarily override derived values by reassigning them (useful for optimistic UI):

```svelte
<script>
	let { post, like } = $props();
	let likes = $derived(post.likes);

	async function onclick() {
		// Optimistic update
		likes += 1;
		try {
			await like();
		} catch {
			// Rollback on failure
			likes -= 1;
		}
	}
</script>

<button {onclick}>🧡 {likes}</button>
```

## Reactivity Behavior

Unlike `$state`, `$derived` values are not converted to deeply reactive proxies. When accessing properties of a derived object that references a reactive state, mutations affect the underlying state.

## Update Propagation

Svelte uses push-pull reactivity:
- Changes are immediately pushed to dependents
- Derived values are only recalculated when read
- Updates are skipped if the new value is referentially identical to the previous value

```svelte
<script>
	let count = $state(0);
	let large = $derived(count > 10);
</script>

<button onclick={() => count++}>
	{large}
</button>
```

The button text only updates when `large` changes value, not on every `count` change.

## docs/svelte/02-runes/04-$effect.md

# Svelte 5 $effect Rune

## Basic Usage

Effects run when state updates, useful for third-party libraries, canvas manipulation, or network requests. They only run in the browser.

```svelte
<script>
	let size = $state(50);
	let color = $state('#ff3e00');
	let canvas;

	$effect(() => {
		const context = canvas.getContext('2d');
		context.clearRect(0, 0, canvas.width, canvas.height);

		// this will re-run whenever `color` or `size` change
		context.fillStyle = color;
		context.fillRect(0, 0, size, size);
	});
</script>

<canvas bind:this={canvas} width="100" height="100"></canvas>
```

## Lifecycle

- Effects run after DOM mounting and in a microtask after state changes
- Re-runs are batched and happen after DOM updates
- Can return a teardown function that runs before effect re-runs or when destroyed

```svelte
<script>
	let count = $state(0);
	let milliseconds = $state(1000);

	$effect(() => {
		const interval = setInterval(() => {
			count += 1;
		}, milliseconds);

		return () => {
			clearInterval(interval);
		};
	});
</script>

<h1>{count}</h1>

<button onclick={() => (milliseconds *= 2)}>slower</button>
<button onclick={() => (milliseconds /= 2)}>faster</button>
```

## Dependencies

- Automatically tracks reactive values read synchronously
- Async operations (after `await` or in `setTimeout`) won't track dependencies
- Only reruns when the object it reads changes, not when properties change
- Dependencies are based on what was read in the previous run

```svelte
<script>
	let state = $state({ value: 0 });
	let derived = $derived({ value: state.value * 2 });

	// runs once (state is never reassigned)
	$effect(() => {
		state;
	});

	// runs when state.value changes
	$effect(() => {
		state.value;
	});

	// runs when state.value changes (derived is a new object each time)
	$effect(() => {
		derived;
	});
</script>

<button onclick={() => (state.value += 1)}>
	{state.value}
</button>

<p>{state.value} doubled is {derived.value}</p>
```

## Variants

### `$effect.pre`

Runs before DOM updates:

```svelte
<script>
	import { tick } from 'svelte';

	let div = $state();
	let messages = $state([]);

	$effect.pre(() => {
		if (!div) return; // not yet mounted
		messages.length; // dependency to trigger re-runs

		// autoscroll when new messages are added
		if (div.offsetHeight + div.scrollTop > div.scrollHeight - 20) {
			tick().then(() => {
				div.scrollTo(0, div.scrollHeight);
			});
		}
	});
</script>

<div bind:this={div}>
	{#each messages as message}
		<p>{message}</p>
	{/each}
</div>
```

### `$effect.tracking`

Tells if code is running in a tracking context:

```svelte
<script>
	console.log('in component setup:', $effect.tracking()); // false

	$effect(() => {
		console.log('in effect:', $effect.tracking()); // true
	});
</script>

<p>in template: {$effect.tracking()}</p> 
```

### `$effect.root`

Creates a non-tracked scope without auto-cleanup:

```js
const destroy = $effect.root(() => {
	$effect(() => {
		// setup
	});

	return () => {
		// cleanup
	};
});

// later...
destroy();
```

## When Not To Use `$effect`

Avoid using for state synchronization. Instead of:

```svelte
<script>
	let count = $state(0);
	let doubled = $state();

	// don't do this!
	$effect(() => {
		doubled = count * 2;
	});
</script>
```

Use `$derived`:

```svelte
<script>
	let count = $state(0);
	let doubled = $derived(count * 2);
</script>
```

For linked values, use function bindings instead of effects:

```svelte
<script>
	let total = 100;
	let spent = $state(0);
	let left = $state(total);

	function updateSpent(value) {
		spent = value;
		left = total - spent;
	}

	function updateLeft(value) {
		left = value;
		spent = total - left;
	}
</script>

<label>
	<input type="range" bind:value={() => spent, updateSpent} max={total} />
	{spent}/{total} spent
</label>

<label>
	<input type="range" bind:value={() => left, updateLeft} max={total} />
	{left}/{total} left
</label>
```

## docs/svelte/02-runes/05-$props.md

# $props in Svelte 5

The `$props` rune defines component inputs.

## Basic Usage

```svelte
<!-- App.svelte -->
<script>
	import MyComponent from './MyComponent.svelte';
</script>

<MyComponent adjective="cool" />
```

```svelte
<!-- MyComponent.svelte -->
<script>
	let { adjective } = $props();
</script>

<p>this component is {adjective}</p>
```

## Fallback Values

```js
let { adjective = 'happy' } = $props();
```

> Note: Fallback values are not reactive state proxies

## Renaming Props

```js
let { super: trouper = 'lights are gonna find me' } = $props();
```

## Rest Props

```js
let { a, b, c, ...others } = $props();
```

## Updating Props

Props update when parent values change. Child components can temporarily override prop values:

```svelte
<!-- App.svelte -->
<script>
	import Child from './Child.svelte';
	let count = $state(0);
</script>

<button onclick={() => (count += 1)}>
	clicks (parent): {count}
</button>

<Child {count} />
```

```svelte
<!-- Child.svelte -->
<script>
	let { count } = $props();
</script>

<button onclick={() => (count += 1)}>
	clicks (child): {count}
</button>
```

### Important Rules

1. You can reassign props but should not mutate them unless they are `$bindable`
2. Mutating regular objects has no effect
3. Mutating reactive state proxies works but triggers an `ownership_invalid_mutation` warning
4. Fallback values are not reactive state proxies, so mutations won't cause updates

## Type Safety

```svelte
<script lang="ts">
	let { adjective }: { adjective: string } = $props();
</script>
```

Or with JSDoc:

```svelte
<script>
	/** @type {{ adjective: string }} */
	let { adjective } = $props();
</script>
```

With separate type declaration:

```svelte
<script lang="ts">
	interface Props {
		adjective: string;
	}

	let { adjective }: Props = $props();
</script>
```

## $props.id()

Generates a unique ID for the component instance:

```svelte
<script>
	const uid = $props.id();
</script>

<form>
	<label for="{uid}-firstname">First Name: </label>
	<input id="{uid}-firstname" type="text" />

	<label for="{uid}-lastname">Last Name: </label>
	<input id="{uid}-lastname" type="text" />
</form>
```

## docs/svelte/02-runes/06-$bindable.md

# Svelte 5 Condensed: $bindable

## Basic Usage

`$bindable` enables two-way data flow between parent and child components.

```svelte
/// file: FancyInput.svelte
<script>
	let { value = $bindable(), ...props } = $props();
</script>

<input bind:value={value} {...props} />
```

Parent component can bind to the prop:

```svelte
/// file: App.svelte
<script>
	import FancyInput from './FancyInput.svelte';

	let message = $state('hello');
</script>

<FancyInput bind:value={message} />
<p>{message}</p>
```

## Default Values

Provide fallback values when no prop is passed:

```js
/// file: FancyInput.svelte
let { value = $bindable('fallback'), ...props } = $props();
```

## Key Points

- Props normally flow one-way (parent to child)
- `$bindable` allows data to flow up from child to parent
- Parent components can choose whether to use `bind:` or not
- Use sparingly to maintain clear data flow in your app
- State proxies can be mutated in child components

## docs/svelte/02-runes/07-$inspect.md

# Svelte 5 Documentation: $inspect

## Basic Usage

```svelte
<script>
	let count = $state(0);
	let message = $state('hello');

	$inspect(count, message); // logs when `count` or `message` change
</script>

<button onclick={() => count++}>Increment</button>
<input bind:value={message} />
```

> **Note**: `$inspect` only works during development. In production, it becomes a no-op.

## $inspect(...).with

Customize logging behavior with a callback:

```svelte
<script>
	let count = $state(0);

	$inspect(count).with((type, count) => {
		if (type === 'update') {
			debugger; // or `console.trace`, or whatever you want
		}
	});
</script>

<button onclick={() => count++}>Increment</button>
```

Quick trace shorthand:

```js
$inspect(stuff).with(console.trace);
```

## $inspect.trace(...)

Traces reactive dependencies in development:

```svelte
<script>
	import { doSomeWork } from './elsewhere';

	$effect(() => {
		$inspect.trace(); // logs which state triggered this effect
		doSomeWork();
	});
</script>
```

Accepts an optional label parameter.

## docs/svelte/02-runes/08-$host.md

# $host

When compiling a component as a custom element, the `$host` rune provides access to the host element.

```svelte
/// file: Stepper.svelte
<svelte:options customElement="my-stepper" />

<script>
	function dispatch(type) {
		$host().dispatchEvent(new CustomEvent(type));
	}
</script>

<button onclick={() => dispatch('decrement')}>decrement</button>
<button onclick={() => dispatch('increment')}>increment</button>
```

```svelte
/// file: App.svelte
<script>
	import './Stepper.svelte';

	let count = $state(0);
</script>

<my-stepper
	ondecrement={() => count -= 1}
	onincrement={() => count += 1}
></my-stepper>

<p>count: {count}</p>
```

## docs/svelte/03-template-syntax/01-basic-markup.md

# Basic Markup in Svelte 5

## Tags

```svelte
<script>
	import Widget from './Widget.svelte';
</script>

<div>
	<Widget />
</div>
```

- Lowercase tags (`<div>`) = HTML elements
- Capitalized tags or dot notation (`<Widget>`, `<my.stuff>`) = components

## Element Attributes

```svelte
<div class="foo">
	<button disabled>can't touch this</button>
</div>

<!-- Unquoted values -->
<input type=checkbox />

<!-- JavaScript expressions in attributes -->
<a href="page/{p}">page {p}</a>

<!-- Attributes as expressions -->
<button disabled={!clickable}>...</button>

<!-- Boolean attributes included if truthy, excluded if falsy -->
<input required={false} placeholder="This input field is not required" />
<div title={null}>This div has no title attribute</div>

<!-- Shorthand when name and value match -->
<button {disabled}>...</button>
```

## Component Props

```svelte
<Widget foo={bar} answer={42} text="hello" />

<!-- Spread attributes -->
<Widget {...things} />
```

## Events

```svelte
<button onclick={() => console.log('clicked')}>click me</button>
```

- Event attributes are case sensitive (`onclick` ≠ `onClick`)
- Can use shorthand: `<button {onclick}>click me</button>`
- Can spread events: `<button {...thisSpreadContainsEventAttributes}>click me</button>`
- `ontouchstart` and `ontouchmove` are passive by default

### Event Delegation

Svelte uses event delegation for performance. Important notes:
- When manually dispatching events, use `{ bubbles: true }`
- Avoid `stopPropagation` with `addEventListener`
- Use `on` from `svelte/events` instead of `addEventListener`

Delegated events: `beforeinput`, `click`, `change`, `dblclick`, `contextmenu`, `focusin`, `focusout`, `input`, `keydown`, `keyup`, `mousedown`, `mousemove`, `mouseout`, `mouseover`, `mouseup`, `pointerdown`, `pointermove`, `pointerout`, `pointerover`, `pointerup`, `touchend`, `touchmove`, `touchstart`

## Text Expressions

```svelte
<h1>Hello {name}!</h1>
<p>{a} + {b} = {a + b}.</p>

<!-- RegExp literals need parentheses -->
<div>{(/^[A-Za-z ]+$/).test(value) ? x : y}</div>

<!-- Render HTML (use with caution) -->
{@html potentiallyUnsafeHtmlString}
```

- `null` or `undefined` expressions are omitted
- All others are coerced to strings
- Escape curly braces with HTML entities: `&lbrace;`, `&lcub;`, `&#123;`, `&rbrace;`, `&rcub;`, `&#125;`

## Comments

```svelte
<!-- Regular HTML comment -->
<h1>Hello world</h1>

<!-- svelte-ignore a11y-autofocus -->
<input bind:value={name} autofocus />

<!-- @component
This is a component that displays a greeting.
-->
<script>
	let { name } = $props();
</script>

<main>
	<h1>Hello, {name}</h1>
</main>
```

- Use `<!-- svelte-ignore -->` to disable warnings
- Use `<!-- @component -->` for component documentation

## docs/svelte/03-template-syntax/02-if.md

# {#if ...}

```svelte
{#if expression}...{/if}
{#if expression}...{:else if expression}...{/if}
{#if expression}...{:else}...{/if}
```

Conditionally render content with if blocks:

```svelte
{#if answer === 42}
	<p>what was the question?</p>
{/if}
```

Chain conditions with `:else if` and `:else`:

```svelte
{#if porridge.temperature > 100}
	<p>too hot!</p>
{:else if 80 > porridge.temperature}
	<p>too cold!</p>
{:else}
	<p>just right!</p>
{/if}
```

Note: Blocks can wrap elements or text within elements.

## docs/svelte/03-template-syntax/03-each.md

# Svelte 5 Each Blocks

## Basic Usage

```svelte
{#each expression as name}...{/each}
{#each expression as name, index}...{/each}
```

Iterate over arrays, array-likes, or iterables (Map, Set, etc.):

```svelte
<h1>Shopping list</h1>
<ul>
	{#each items as item}
		<li>{item.name} x {item.qty}</li>
	{/each}
</ul>
```

With index:

```svelte
{#each items as item, i}
	<li>{i + 1}: {item.name} x {item.qty}</li>
{/each}
```

## Keyed Each Blocks

```svelte
{#each expression as name (key)}...{/each}
{#each expression as name, index (key)}...{/each}
```

Keys help Svelte efficiently update lists when data changes:

```svelte
{#each items as item (item.id)}
	<li>{item.name} x {item.qty}</li>
{/each}

{#each items as item, i (item.id)}
	<li>{i + 1}: {item.name} x {item.qty}</li>
{/each}
```

## Destructuring

```svelte
{#each items as { id, name, qty }, i (id)}
	<li>{i + 1}: {name} x {qty}</li>
{/each}

{#each objects as { id, ...rest }}
	<li><span>{id}</span><MyComponent {...rest} /></li>
{/each}

{#each items as [id, ...rest]}
	<li><span>{id}</span><MyComponent values={rest} /></li>
{/each}
```

## Each Without Item

For repeating n times:

```svelte
{#each { length: 8 }, rank}
	{#each { length: 8 }, file}
		<div class:black={(rank + file) % 2 === 1}></div>
	{/each}
{/each}
```

## Else Blocks

```svelte
{#each todos as todo}
	<p>{todo.text}</p>
{:else}
	<p>No tasks today!</p>
{/each}
```

## docs/svelte/03-template-syntax/04-key.md

# {#key ...}

```svelte
{#key expression}...{/key}
```

Key blocks destroy and recreate their contents when an expression value changes:

```svelte
{#key value}
	<Component />
{/key}
```

Useful for:
- Reinstantiating components when a value changes
- Triggering transitions on value changes:

```svelte
{#key value}
	<div transition:fade>{value}</div>
{/key}
```

## docs/svelte/03-template-syntax/05-await.md

# {#await ...}

```svelte
{#await expression}...{:then name}...{:catch name}...{/await}
{#await expression}...{:then name}...{/await}
{#await expression then name}...{/await}
{#await expression catch name}...{/await}
```

Await blocks handle the three states of a Promise:

```svelte
{#await promise}
	<p>waiting for the promise to resolve...</p>
{:then value}
	<p>The value is {value}</p>
{:catch error}
	<p>Something went wrong: {error.message}</p>
{/await}
```

> During SSR, only the pending branch renders. Non-Promise expressions only render the `:then` branch.

**Simplified variants:**

```svelte
{#await promise}
	<p>waiting for the promise to resolve...</p>
{:then value}
	<p>The value is {value}</p>
{/await}
```

```svelte
{#await promise then value}
	<p>The value is {value}</p>
{/await}
```

```svelte
{#await promise catch error}
	<p>The error is {error}</p>
{/await}
```

> Use with dynamic imports for lazy loading:
> ```svelte
> {#await import('./Component.svelte') then { default: Component }}
> 	<Component />
> {/await}
> ```

## docs/svelte/03-template-syntax/06-snippet.md

# Svelte 5 Snippets

## {#snippet ...}

```svelte
{#snippet name()}...{/snippet}
{#snippet name(param1, param2, paramN)}...{/snippet}
```

Snippets create reusable markup chunks within components:

```svelte
{#snippet figure(image)}
	<figure>
		<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
		<figcaption>{image.caption}</figcaption>
	</figure>
{/snippet}

{#each images as image}
	{#if image.href}
		<a href={image.href}>
			{@render figure(image)}
		</a>
	{:else}
		{@render figure(image)}
	{/if}
{/each}
```

Snippets can have parameters with default values and destructuring (no rest parameters).

## Scope

Snippets can access outer scope values:

```svelte
<script>
	let { message = `it's great to see you!` } = $props();
</script>

{#snippet hello(name)}
	<p>hello {name}! {message}!</p>
{/snippet}

{@render hello('alice')}
{@render hello('bob')}
```

Snippets are visible to siblings and their children. They can reference themselves and other snippets:

```svelte
{#snippet countdown(n)}
	{#if n > 0}
		<span>{n}...</span>
		{@render countdown(n - 1)}
	{:else}
		{@render blastoff()}
	{/if}
{/snippet}

{#snippet blastoff()}
	<span>🚀</span>
{/snippet}

{@render countdown(10)}
```

## Passing Snippets to Components

### Explicit Props

```svelte
<script>
	import Table from './Table.svelte';

	const fruits = [
		{ name: 'apples', qty: 5, price: 2 },
		{ name: 'bananas', qty: 10, price: 1 },
		{ name: 'cherries', qty: 20, price: 0.5 }
	];
</script>

{#snippet header()}
	<th>fruit</th>
	<th>qty</th>
	<th>price</th>
	<th>total</th>
{/snippet}

{#snippet row(d)}
	<td>{d.name}</td>
	<td>{d.qty}</td>
	<td>{d.price}</td>
	<td>{d.qty * d.price}</td>
{/snippet}

<Table data={fruits} {header} {row} />
```

### Implicit Props

Snippets declared inside a component become props on the component:

```svelte
<Table data={fruits}>
	{#snippet header()}
		<th>fruit</th>
		<th>qty</th>
		<th>price</th>
		<th>total</th>
	{/snippet}

	{#snippet row(d)}
		<td>{d.name}</td>
		<td>{d.qty}</td>
		<td>{d.price}</td>
		<td>{d.qty * d.price}</td>
	{/snippet}
</Table>
```

### Implicit `children` Snippet

Non-snippet content becomes the `children` snippet:

```svelte
<!-- App.svelte -->
<Button>click me</Button>
```

```svelte
<!-- Button.svelte -->
<script>
	let { children } = $props();
</script>

<button>{@render children()}</button>
```

> Don't create a prop named `children` if you also have content inside the component

### Optional Snippet Props

Handle optional snippets with optional chaining:

```svelte
<script>
    let { children } = $props();
</script>

{@render children?.()}
```

Or with fallback content:

```svelte
<script>
    let { children } = $props();
</script>

{#if children}
    {@render children()}
{:else}
    fallback content
{/if}
```

## Typing Snippets

```svelte
<script lang="ts" generics="T">
	import type { Snippet } from 'svelte';

	let {
		data,
		children,
		row
	}: {
		data: T[];
		children: Snippet;
		row: Snippet<[T]>;
	} = $props();
</script>
```

## Exporting Snippets

Top-level snippets can be exported from `<script module>` if they don't reference non-module script declarations:

```svelte
<script module>
	export { add };
</script>

{#snippet add(a, b)}
	{a} + {b} = {a + b}
{/snippet}
```

> Requires Svelte 5.5.0+

## Advanced Usage

- Programmatic snippets can be created with `createRawSnippet` API
- Snippets replace slots in Svelte 5 (slots are deprecated)

## docs/svelte/03-template-syntax/07-@render.md

# {@render ...}

Use `{@render ...}` to render [snippets](snippet).

```svelte
{#snippet sum(a, b)}
	<p>{a} + {b} = {a + b}</p>
{/snippet}

{@render sum(1, 2)}
{@render sum(3, 4)}
{@render sum(5, 6)}
```

The expression can be an identifier or any JavaScript expression:

```svelte
{@render (cool ? coolSnippet : lameSnippet)()}
```

## Optional snippets

For potentially undefined snippets, use optional chaining:

```svelte
{@render children?.()}
```

Or use an `{#if ...}` block with fallback content:

```svelte
{#if children}
	{@render children()}
{:else}
	<p>fallback content</p>
{/if}
```

## docs/svelte/03-template-syntax/08-@html.md

# {@html ...}

Use `{@html ...}` to inject raw HTML into your component:

```svelte
<article>
	{@html content}
</article>
```

> [!NOTE] Always sanitize HTML content to prevent XSS attacks.

## Limitations

- Expression must be valid standalone HTML
- Will not compile Svelte code
- Cannot split HTML tags across multiple `{@html}` tags

## Styling

Content rendered with `{@html ...}` is invisible to Svelte's style scoping:

```svelte
<style>
	/* Won't work for elements inside {@html} content */
	article {
		a { color: hotpink }
		img { width: 100% }
	}

	/* Use :global instead */
	article:global{
		a { color: hotpink }
		img { width: 100% }
	}
</style>
```

## docs/svelte/03-template-syntax/09-@const.md

# {@const ...}

The `{@const ...}` tag defines a local constant within a block.

```svelte
{#each boxes as box}
	{@const area = box.width * box.height}
	{box.width} * {box.height} = {area}
{/each}
```

Only allowed as an immediate child of:
- Blocks (`{#if ...}`, `{#each ...}`, `{#snippet ...}`, etc.)
- Components (`<Component />`)
- `<svelte:boundary>`

## docs/svelte/03-template-syntax/10-@debug.md

# {@debug ...}

The `{@debug ...}` tag provides debugging capabilities in Svelte components:

```svelte
<script>
	let user = {
		firstname: 'Ada',
		lastname: 'Lovelace'
	};
</script>

{@debug user}

<h1>Hello {user.firstname}!</h1>
```

## Usage

- Logs values when they change and pauses execution if devtools are open
- Accepts comma-separated variable names (not expressions):

```svelte
{@debug user}
{@debug user1, user2, user3}
```

- Without arguments, triggers on any state change:

```svelte
{@debug}
```

## docs/svelte/03-template-syntax/11-bind.md

# Svelte 5 and SvelteKit Condensed Documentation

## bind:

Data flows down from parent to child. `bind:` allows data to flow upward.

```svelte
<input bind:value={value} />
<input bind:value /> <!-- shorthand when names match -->
```

### Function bindings (v5.9.0+)

```svelte
<input bind:value={
	() => value,
	(v) => value = v.toLowerCase()}
/>

<!-- For readonly bindings -->
<div
	bind:clientWidth={null, redraw}
	bind:clientHeight={null, redraw}
>...</div>
```

### Input bindings

```svelte
<!-- Text input -->
<script>
	let message = $state('hello');
</script>
<input bind:value={message} />

<!-- Numeric input (coerces to number) -->
<script>
	let a = $state(1);
</script>
<input type="number" bind:value={a} min="0" max="10" />
<input type="range" bind:value={a} min="0" max="10" />

<!-- Checkbox -->
<input type="checkbox" bind:checked={accepted} />

<!-- Radio/checkbox groups -->
<script>
	let tortilla = $state('Plain');
	let fillings = $state([]);
</script>
<input type="radio" bind:group={tortilla} value="Plain" />
<input type="radio" bind:group={tortilla} value="Whole wheat" />

<input type="checkbox" bind:group={fillings} value="Rice" />
<input type="checkbox" bind:group={fillings} value="Beans" />

<!-- File inputs -->
<script>
	let files = $state();
	function clear() {
		files = new DataTransfer().files;
	}
</script>
<input bind:files type="file" />
<button onclick={clear}>clear</button>
```

### Select bindings

```svelte
<!-- Single select -->
<select bind:value={selected}>
	<option value={a}>a</option>
	<option value={b}>b</option>
</select>

<!-- Multiple select -->
<select multiple bind:value={fillings}>
	<option>Rice</option>
	<option>Beans</option>
</select>
```

### Media element bindings

```svelte
<!-- Audio bindings -->
<audio 
  src={clip} 
  bind:duration 
  bind:currentTime 
  bind:paused
></audio>

<!-- Video has same bindings as audio plus: -->
<video bind:videoWidth bind:videoHeight></video>
```

### Other element bindings

```svelte
<!-- Image -->
<img bind:naturalWidth bind:naturalHeight />

<!-- Details -->
<details bind:open={isOpen}>
	<summary>Title</summary>
	<p>Content</p>
</details>

<!-- Contenteditable -->
<div contenteditable="true" bind:innerHTML={html}></div>

<!-- Dimensions -->
<div bind:offsetWidth={width} bind:offsetHeight={height}>
	<Chart {width} {height} />
</div>
```

### bind:this

```svelte
<script>
	/** @type {HTMLCanvasElement} */
	let canvas;

	$effect(() => {
		const ctx = canvas.getContext('2d');
		drawStuff(ctx);
	});
</script>

<canvas bind:this={canvas}></canvas>

<!-- Component instances -->
<ShoppingCart bind:this={cart} />
<button onclick={() => cart.empty()}>Empty shopping cart</button>
```

### Component bindings

```svelte
<!-- Parent -->
<Keypad bind:value={pin} />

<!-- Child (Keypad.svelte) -->
<script>
	let { value = $bindable() } = $props();
</script>

<!-- With fallback -->
<script>
	let { bindableProperty = $bindable('fallback value') } = $props();
</script>
```

## docs/svelte/03-template-syntax/12-use.md

# use: Directive in Svelte 5

Actions are functions called when an element is mounted, added with the `use:` directive.

## Basic Usage

```svelte
<script>
	/** @type {import('svelte/action').Action} */
	function myaction(node) {
		$effect(() => {
			// setup code
			return () => {
				// cleanup code
			};
		});
	}
</script>

<div use:myaction>...</div>
```

## With Parameters

```svelte
<script>
	/** @type {import('svelte/action').Action} */
	function myaction(node, data) {
		// ...
	}
</script>

<div use:myaction={data}>...</div>
```

> Note: Actions run once when mounted (not during SSR). They don't re-run if parameters change.

## Typing

```svelte
<script>
	/**
	 * @type {import('svelte/action').Action<
	 * 	HTMLDivElement,
	 * 	undefined,
	 * 	{
	 * 		onswiperight: (e: CustomEvent) => void;
	 * 		onswipeleft: (e: CustomEvent) => void;
	 * 	}
	 * >}
	 */
	function gestures(node) {
		$effect(() => {
			// ...
			node.dispatchEvent(new CustomEvent('swipeleft'));
			// ...
			node.dispatchEvent(new CustomEvent('swiperight'));
		});
	}
</script>

<div
	use:gestures
	onswipeleft={next}
	onswiperight={prev}
>...</div>
```

The `Action` interface accepts three optional type arguments:
1. Node type (can be `Element` for all elements)
2. Parameter type
3. Custom event handlers created by the action

## docs/svelte/03-template-syntax/13-transition.md

# Svelte 5 Transitions

## Basic Usage

Transitions are triggered when elements enter or leave the DOM due to state changes.

```svelte
<script>
	import { fade } from 'svelte/transition';
	let visible = $state(false);
</script>

<button onclick={() => visible = !visible}>toggle</button>

{#if visible}
	<div transition:fade>fades in and out</div>
{/if}
```

## Local vs Global

Transitions are local by default - they only play when their immediate block is created/destroyed.

```svelte
{#if x}
	{#if y}
		<p transition:fade>fades in and out only when y changes</p>
		<p transition:fade|global>fades in and out when x or y change</p>
	{/if}
{/if}
```

## Parameters

```svelte
{#if visible}
	<div transition:fade={{ duration: 2000 }}>fades in and out over two seconds</div>
{/if}
```

## Custom Transitions

```js
transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => {
	delay?: number,
	duration?: number,
	easing?: (t: number) => number,
	css?: (t: number, u: number) => string,
	tick?: (t: number, u: number) => void
}
```

CSS-based custom transition (preferred for performance):

```svelte
<script>
	import { elasticOut } from 'svelte/easing';

	/** @type {boolean} */
	export let visible;

	/**
	 * @param {HTMLElement} node
	 * @param {{ delay?: number, duration?: number, easing?: (t: number) => number }} params
	 */
	function whoosh(node, params) {
		const existingTransform = getComputedStyle(node).transform.replace('none', '');

		return {
			delay: params.delay || 0,
			duration: params.duration || 400,
			easing: params.easing || elasticOut,
			css: (t, u) => `transform: ${existingTransform} scale(${t})`
		};
	}
</script>

{#if visible}
	<div in:whoosh>whooshes in</div>
{/if}
```

JavaScript-based custom transition (use `css` when possible):

```svelte
<script>
	export let visible = false;

	/**
	 * @param {HTMLElement} node
	 * @param {{ speed?: number }} params
	 */
	function typewriter(node, { speed = 1 }) {
		const valid = node.childNodes.length === 1 && node.childNodes[0].nodeType === Node.TEXT_NODE;

		if (!valid) {
			throw new Error(`This transition only works on elements with a single text node child`);
		}

		const text = node.textContent;
		const duration = text.length / (speed * 0.01);

		return {
			duration,
			tick: (t) => {
				const i = ~~(text.length * t);
				node.textContent = text.slice(0, i);
			}
		};
	}
</script>

{#if visible}
	<p in:typewriter={{ speed: 1 }}>The quick brown fox jumps over the lazy dog</p>
{/if}
```

## Transition Events

Elements with transitions dispatch these events:
- `introstart`
- `introend`
- `outrostart`
- `outroend`

```svelte
{#if visible}
	<p
		transition:fly={{ y: 200, duration: 2000 }}
		onintrostart={() => (status = 'intro started')}
		onoutrostart={() => (status = 'outro started')}
		onintroend={() => (status = 'intro ended')}
		onoutroend={() => (status = 'outro ended')}
	>
		Flies in and out
	</p>
{/if}
```

## docs/svelte/03-template-syntax/14-in-and-out.md

# in: and out: Directives

These directives create one-way transitions that don't reverse when interrupted.

```svelte
<script>
  import { fade, fly } from 'svelte/transition';
  
  let visible = $state(false);
</script>

<label>
  <input type="checkbox" bind:checked={visible}>
  visible
</label>

{#if visible}
	<div in:fly={{ y: 200 }} out:fade>flies in, fades out</div>
{/if}
```

Key differences from `transition:`:
- Transitions are not bidirectional
- An `in` transition continues playing alongside the `out` transition
- If an `out` transition is aborted, transitions restart from scratch

## docs/svelte/03-template-syntax/15-animate.md

# animate:

Animations trigger when contents of a keyed each block are re-ordered (not when elements are added/removed).

```svelte
{#each list as item, index (item)}
	<li animate:flip>{item}</li>
{/each}
```

## Animation Parameters

```svelte
{#each list as item, index (item)}
	<li animate:flip={{ delay: 500 }}>{item}</li>
{/each}
```

## Custom animation functions

```js
animation = (node: HTMLElement, { from: DOMRect, to: DOMRect }, params: any) => {
	delay?: number,
	duration?: number,
	easing?: (t: number) => number,
	css?: (t: number, u: number) => string,
	tick?: (t: number, u: number) => void
}
```

Custom animations receive:
- `node`: The HTML element
- `animation`: Object with `from` and `to` DOMRect properties
- `parameters`: Any custom parameters

Return an object with either:
- `css` method (preferred, runs off main thread)
- `tick` function (runs during animation)

```svelte
<script>
	import { cubicOut } from 'svelte/easing';

	function whizz(node, { from, to }, params) {
		const dx = from.left - to.left;
		const dy = from.top - to.top;
		const d = Math.sqrt(dx * dx + dy * dy);

		return {
			delay: 0,
			duration: Math.sqrt(d) * 120,
			easing: cubicOut,
			css: (t, u) => `transform: translate(${u * dx}px, ${u * dy}px) rotate(${t * 360}deg);`
		};
	}
</script>

{#each list as item, index (item)}
	<div animate:whizz>{item}</div>
{/each}
```

Using `tick` instead of `css`:

```svelte
<script>
	import { cubicOut } from 'svelte/easing';

	function whizz(node, { from, to }, params) {
		const dx = from.left - to.left;
		const dy = from.top - to.top;
		const d = Math.sqrt(dx * dx + dy * dy);

		return {
			delay: 0,
			duration: Math.sqrt(d) * 120,
			easing: cubicOut,
			tick: (t, u) => Object.assign(node.style, { color: t > 0.5 ? 'Pink' : 'Blue' })
		};
	}
</script>

{#each list as item, index (item)}
	<div animate:whizz>{item}</div>
{/each}
```

> Prefer `css` over `tick` for better performance on slower devices.

## docs/svelte/03-template-syntax/17-style.md

# style: directive

The `style:` directive provides a shorthand for setting styles on elements.

## Basic Usage

```svelte
<div style:color="red">...</div>
<!-- Equivalent to -->
<div style="color: red;">...</div>
```

## Dynamic Values

```svelte
<div style:color={myColor}>...</div>
```

## Shorthand Form

```svelte
<div style:color>...</div>
```

## Multiple Styles

```svelte
<div 
  style:color 
  style:width="12rem" 
  style:background-color={darkMode ? 'black' : 'white'}>
  ...
</div>
```

## Important Modifier

```svelte
<div style:color|important="red">...</div>
```

## Precedence

When combined with `style` attributes, directives take precedence:

```svelte
<div style="color: blue;" style:color="red">This will be red</div>
```

## docs/svelte/03-template-syntax/18-class.md

# Svelte Class Handling

## Class Attribute

### Basic Usage

```svelte
<div class={large ? 'large' : 'small'}>...</div>
```

> Note: Falsy values are stringified, but `undefined`/`null` omit the attribute entirely.

### Objects and Arrays (Svelte 5.16+)

**Objects** - truthy keys are added:

```svelte
<script>
	let { cool } = $props();
</script>

<div class={{ cool, lame: !cool }}>...</div>
```

**Arrays** - truthy values are combined:

```svelte
<div class={[faded && 'saturate-0 opacity-50', large && 'scale-200']}>...</div>
```

**Combining with props**:

```svelte
<!file: Button.svelte>
<script>
	let props = $props();
</script>

<button {...props} class={['cool-button', props.class]}>
	{@render props.children?.()}
</button>
```

Usage:

```svelte
<!file: App.svelte>
<script>
	import Button from './Button.svelte';
	let useTailwind = $state(false);
</script>

<Button
	onclick={() => useTailwind = true}
	class={{ 'bg-blue-700 sm:w-1/2': useTailwind }}
>
	Accept the inevitability of Tailwind
</Button>
```

### TypeScript Support

```svelte
<script lang="ts">
	import type { ClassValue } from 'svelte/elements';

	const props: { class: ClassValue } = $props();
</script>

<div class={['original', props.class]}>...</div>
```

## Class Directive (Legacy)

```svelte
<div class:cool={cool} class:lame={!cool}>...</div>
```

Shorthand when name matches value:

```svelte
<div class:cool class:lame={!cool}>...</div>
```

> Note: Prefer using the class attribute with objects/arrays over class: directives in Svelte 5.16+.

## docs/svelte/04-styling/01-scoped-styles.md

# Scoped Styles in Svelte

## Basic Scoping

Styles in `<style>` tags are automatically scoped to the component using a generated class (e.g., `svelte-123xyz`).

```svelte
<style>
	p {
		/* this will only affect <p> elements in this component */
		color: burlywood;
	}
</style>
```

## Specificity

- Scoped selectors get a specificity boost of 0-1-0 from the added class
- Component styles override global styles with the same selector, even if loaded later
- Multiple occurrences of the scoping class after the first use `:where(.svelte-xyz123)` to avoid further specificity increases

## Scoped Keyframes

Keyframe animations are also scoped to the component:

```svelte
<style>
	.bouncy {
		animation: bounce 10s;
	}

	/* these keyframes are only accessible inside this component */
	@keyframes bounce {
		/* ... */
	}
</style>
```

## docs/svelte/04-styling/02-global-styles.md

# Global Styles in Svelte

## :global(...)

Apply styles globally to specific selectors:

```svelte
<style>
	:global(body) {
		/* applies to <body> */
		margin: 0;
	}

	div :global(strong) {
		/* applies to all <strong> elements, in any component,
		   that are inside <div> elements belonging
		   to this component */
		color: goldenrod;
	}

	p:global(.big.red) {
		/* applies to all <p> elements belonging to this component
		   with `class="big red"`, even if it is applied
		   programmatically (for example by a library) */
	}
</style>
```

For global keyframes, prepend names with `-global-`:

```svelte
<style>
	@keyframes -global-my-animation-name {
		/* code goes here */
	}
</style>
```

## :global

Apply styles to multiple selectors globally using a block:

```svelte
<style>
	:global {
		/* applies to every <div> in your application */
		div { ... }

		/* applies to every <p> in your application */
		p { ... }
	}

	.a :global {
		/* applies to every `.b .c .d` element, in any component,
		   that is inside an `.a` element in this component */
		.b .c .d {...}
	}
</style>
```

## docs/svelte/04-styling/03-custom-properties.md

# Custom Properties

Pass CSS custom properties to components:

```svelte
<Slider
	bind:value
	min={0}
	max={100}
	--track-color="black"
	--thumb-color="rgb({r} {g} {b})"
/>
```

This desugars to:

```svelte
<svelte-css-wrapper style="display: contents; --track-color: black; --thumb-color: rgb({r} {g} {b})">
	<Slider
		bind:value
		min={0}
		max={100}
	/>
</svelte-css-wrapper>
```

For SVG elements, it uses `<g>` instead:

```svelte
<g style="--track-color: black; --thumb-color: rgb({r} {g} {b})">
	<Slider
		bind:value
		min={0}
		max={100}
	/>
</g>
```

Inside components, access these properties with fallbacks:

```svelte
<style>
	.track {
		background: var(--track-color, #aaa);
	}

	.thumb {
		background: var(--thumb-color, blue);
	}
</style>
```

Custom properties can also be defined on parent elements (like `:root`) to apply globally.

> Note: The wrapper element won't affect layout but may impact CSS selectors using the `>` combinator.

## docs/svelte/04-styling/04-nested-style-elements.md

# Nested `<style>` elements

Only one top-level `<style>` tag is allowed per component. Nested `<style>` tags inside elements or logic blocks are inserted directly into the DOM without Svelte's scoping or processing.

```svelte
<div>
	<style>
		/* this style tag will be inserted as-is */
		div {
			/* this will apply to all `<div>` elements in the DOM */
			color: red;
		}
	</style>
</div>
```

## docs/svelte/05-special-elements/01-svelte-boundary.md

# Svelte 5 Error Boundaries

## `<svelte:boundary>`

```svelte
<svelte:boundary onerror={handler}>...</svelte:boundary>
```

Error boundaries isolate errors in components to prevent app-wide crashes and enable recovery.

- Catches errors during rendering, updating, and `$effect` execution
- Does NOT catch errors in event handlers, timeouts, or async operations

## Properties

### `failed`

Renders fallback UI with error details and reset function:

```svelte
<svelte:boundary>
	<FlakyComponent />

	{#snippet failed(error, reset)}
		<button onclick={reset}>oops! try again</button>
	{/snippet}
</svelte:boundary>
```

### `onerror`

Handles errors programmatically:

```svelte
<svelte:boundary onerror={(e) => report(e)}>
	...
</svelte:boundary>
```

Managing error state outside the boundary:

```svelte
<script>
	let error = $state(null);
	let reset = $state(() => {});

	function onerror(e, r) {
		error = e;
		reset = r;
	}
</script>

<svelte:boundary {onerror}>
	<FlakyComponent />
</svelte:boundary>

{#if error}
	<button onclick={() => {
		error = null;
		reset();
	}}>
		oops! try again
	</button>
{/if}
```

Errors in `onerror` propagate to parent boundaries.

## docs/svelte/05-special-elements/02-svelte-window.md

# Svelte Window Element

## `<svelte:window>`

Adds event listeners to the `window` object without manual cleanup.

```svelte
<svelte:window onevent={handler} />
<svelte:window bind:prop={value} />
```

Must appear at the top level of your component.

### Event Example

```svelte
<script>
	function handleKeydown(event) {
		alert(`pressed the ${event.key} key`);
	}
</script>

<svelte:window onkeydown={handleKeydown} />
```

### Bindable Properties

```svelte
<svelte:window bind:scrollY={y} />
```

**Read/Write Properties:**
- `scrollX`
- `scrollY`

**Readonly Properties:**
- `innerWidth`
- `innerHeight`
- `outerWidth`
- `outerHeight`
- `online` (alias for `window.navigator.onLine`)
- `devicePixelRatio`

> **Note:** Page won't scroll to initial bound values of `scrollX`/`scrollY`. For initial scrolling, use `scrollTo()` in an `$effect`.

## docs/svelte/05-special-elements/03-svelte-document.md

# <svelte:document>

```svelte
<svelte:document onevent={handler} />
<svelte:document bind:prop={value} />
```

Allows adding event listeners and actions to the `document` object.

- Must appear only at the top level of your component
- Never place inside blocks or elements
- Useful for events that don't fire on `window` (e.g., `visibilitychange`)

```svelte
<svelte:document onvisibilitychange={handleVisibilityChange} use:someAction />
```

## Bindable Properties (readonly)

- `activeElement`
- `fullscreenElement`
- `pointerLockElement`
- `visibilityState`

## docs/svelte/05-special-elements/04-svelte-body.md

# <svelte:body>

```svelte
<svelte:body onevent={handler} />
```

Allows adding event listeners to `document.body` for events that don't fire on `window` (like `mouseenter`/`mouseleave`). Also supports [actions](use).

**Rules:**
- Must appear only at top level of component
- Cannot be inside blocks or elements

**Example:**
```svelte
<svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />
```

## docs/svelte/05-special-elements/05-svelte-head.md

# <svelte:head>

```svelte
<svelte:head>...</svelte:head>
```

Inserts elements into `document.head`. During SSR, head content is exposed separately from body content.

**Rules:**
- Must appear only at top level of component
- Cannot be inside blocks or elements

**Example:**
```svelte
<svelte:head>
	<title>Hello world!</title>
	<meta name="description" content="This is where the description goes for SEO" />
</svelte:head>
```

## docs/svelte/05-special-elements/06-svelte-element.md

# <svelte:element>

```svelte
<svelte:element this={expression} />
```

Renders an element that's unknown at author time (e.g., from a CMS).

## Usage

```svelte
<script>
	let tag = $state('div');
</script>

<svelte:element this={tag}>
	Content inside the dynamic element
</svelte:element>
```

## Key Points

- Only `bind:this` binding is supported
- If `this` is nullish, nothing renders
- If `this` is a void element (e.g., `br`) with children, a runtime error occurs in dev mode

```svelte
<script>
	let tag = $state('hr');
</script>

<svelte:element this={tag}>
	This text cannot appear inside an hr element
</svelte:element>
```

- Specify namespace explicitly when needed:

```svelte
<svelte:element this={tag} xmlns="http://www.w3.org/2000/svg" />
```

- `this` must be a valid DOM element tag (`#text` or `svelte:head` won't work)

## docs/svelte/05-special-elements/07-svelte-options.md

# `<svelte:options>`

```svelte
<svelte:options option={value} />
```

## Available Options

- `runes={true|false}` - Forces component into runes or legacy mode
- `namespace="html|svg|mathml"` - Sets component namespace (default: "html")
- `customElement={...}` - Options for custom element compilation
- `css="injected"` - Injects styles inline

```svelte
<svelte:options customElement="my-custom-element" />
```

> Note: `immutable`, `accessors` options are deprecated in Svelte 5 and non-functional in runes mode.

## docs/svelte/06-runtime/01-stores.md

# Svelte Stores

## Overview

A store is an object that allows reactive access to a value via a store contract. Access store values in components with the `$` prefix.

```svelte
<script>
	import { writable } from 'svelte/store';

	const count = writable(0);
	console.log($count); // logs 0

	count.set(1);
	console.log($count); // logs 1

	$count = 2;
	console.log($count); // logs 2
</script>
```

## When to Use Stores

In Svelte 5, runes are preferred for most use cases:

```ts
/// file: state.svelte.js
export const userState = $state({
	name: 'name',
	/* ... */
});
```

```svelte
<script>
	import { userState } from './state.svelte.js';
</script>

<p>User name: {userState.name}</p>
<button onclick={() => {
	userState.name = 'new name';
}}>
	change name
</button>
```

Use stores for complex async data streams or when manual control over updates is needed.

## svelte/store API

### `writable`

Creates a store with values that can be set externally.

```js
import { writable } from 'svelte/store';

const count = writable(0);

count.subscribe((value) => {
	console.log(value);
}); // logs '0'

count.set(1); // logs '1'

count.update((n) => n + 1); // logs '2'
```

With start/stop functions:

```js
import { writable } from 'svelte/store';

const count = writable(0, () => {
	console.log('got a subscriber');
	return () => console.log('no more subscribers');
});

count.set(1); // does nothing

const unsubscribe = count.subscribe((value) => {
	console.log(value);
}); // logs 'got a subscriber', then '1'

unsubscribe(); // logs 'no more subscribers'
```

### `readable`

Creates a store whose value cannot be set externally.

```ts
import { readable } from 'svelte/store';

const time = readable(new Date(), (set) => {
	set(new Date());

	const interval = setInterval(() => {
		set(new Date());
	}, 1000);

	return () => clearInterval(interval);
});

const ticktock = readable('tick', (set, update) => {
	const interval = setInterval(() => {
		update((sound) => (sound === 'tick' ? 'tock' : 'tick'));
	}, 1000);

	return () => clearInterval(interval);
});
```

### `derived`

Derives a store from one or more other stores.

```ts
import { derived } from 'svelte/store';

const doubled = derived(a, ($a) => $a * 2);
```

Asynchronous derivation:

```ts
import { derived } from 'svelte/store';

const delayed = derived(
	a,
	($a, set) => {
		setTimeout(() => set($a), 1000);
	},
	2000
);

const delayedIncrement = derived(a, ($a, set, update) => {
	set($a);
	setTimeout(() => update((x) => x + 1), 1000);
});
```

With cleanup function:

```ts
import { derived } from 'svelte/store';

const tick = derived(
	frequency,
	($frequency, set) => {
		const interval = setInterval(() => {
			set(Date.now());
		}, 1000 / $frequency);

		return () => {
			clearInterval(interval);
		};
	},
	2000
);
```

Multiple source stores:

```ts
import { derived } from 'svelte/store';

const summed = derived([a, b], ([$a, $b]) => $a + $b);

const delayed = derived([a, b], ([$a, $b], set) => {
	setTimeout(() => set($a + $b), 1000);
});
```

### `readonly`

Makes a store readonly.

```js
import { readonly, writable } from 'svelte/store';

const writableStore = writable(1);
const readableStore = readonly(writableStore);

readableStore.subscribe(console.log);

writableStore.set(2); // console: 2
// readableStore.set(2); // ERROR
```

### `get`

Retrieves the current value of a store without subscribing.

```ts
import { get } from 'svelte/store';

const value = get(store);
```

## Store Contract

A valid store must:

1. Have a `.subscribe` method that accepts a subscription function
2. Call the subscription function immediately with the current value
3. Return an unsubscribe function
4. Optionally have a `.set` method (for writable stores)

## docs/svelte/06-runtime/02-context.md

# Context

Context allows components to access values from parent components without prop-drilling.

## Basic Usage

```svelte
<!file: Parent.svelte>
<script>
	import { setContext } from 'svelte';

	setContext('my-context', 'hello from Parent.svelte');
</script>
```

```svelte
<!file: Child.svelte>
<script>
	import { getContext } from 'svelte';

	const message = getContext('my-context');
</script>

<h1>{message}, inside Child.svelte</h1>
```

Usage:
```svelte
<Parent>
	<Child />
</Parent>
```

Available functions: `setContext`, `getContext`, `hasContext`, `getAllContexts`

## Context with State

```svelte
<script>
	import { setContext } from 'svelte';
	import Child from './Child.svelte';

	let counter = $state({
		count: 0
	});

	setContext('counter', counter);
</script>

<button onclick={() => counter.count += 1}>
	increment
</button>

<Child />
<Child />
<Child />
```

⚠️ Update properties directly rather than reassigning the object:
```svelte
<!-- Correct -->
<button onclick={() => counter.count = 0}>
	reset
</button>

<!-- Wrong - breaks reactivity -->
<button onclick={() => counter = { count: 0 }}>
	reset
</button>
```

## Type-safe Context

```js
/// file: context.js
// @filename: ambient.d.ts
interface User {}

// @filename: index.js
import { getContext, setContext } from 'svelte';

const key = {};

/** @param {User} user */
export function setUserContext(user) {
	setContext(key, user);
}

export function getUserContext() {
	return /** @type {User} */ (getContext(key));
}
```

## Alternative to Global State

Context is safer than global state for server-side rendering, as it's not shared between requests.

```js
/// file: state.svelte.js
export const myGlobalState = $state({
	user: {
		// ...
	}
	// ...
});
```

Using global state during SSR can leak data between users:

```svelte
<!file: App.svelte->
<script>
	import { myGlobalState } from 'svelte';

	let { data } = $props();

	if (data.user) {
		myGlobalState.user = data.user;
	}
</script>
```

## docs/svelte/06-runtime/03-lifecycle-hooks.md

# Svelte 5 Lifecycle Hooks

## Component Lifecycle

In Svelte 5, components have only two lifecycle phases:
- Creation (mounting)
- Destruction (unmounting)

State updates trigger only the specific effects that depend on that state.

## `onMount`

Runs after component is mounted to DOM. Not executed during SSR.

```svelte
<script>
  import { onMount } from 'svelte';

  onMount(() => {
    console.log('the component has mounted');
    
    // Return function runs on unmount
    return () => console.log('cleanup');
  });
</script>
```

> [!NOTE] Cleanup only works when function synchronously returns a value (not with async functions).

## `onDestroy`

Runs before component unmounts. Only lifecycle hook that runs during SSR.

```svelte
<script>
  import { onDestroy } from 'svelte';

  onDestroy(() => {
    console.log('the component is being destroyed');
  });
</script>
```

## `tick`

Returns promise that resolves after pending state changes are applied.

```svelte
<script>
  import { tick } from 'svelte';

  $effect.pre(() => {
    console.log('the component is about to update');
    tick().then(() => {
      console.log('the component just updated');
    });
  });
</script>
```

## Deprecated: `beforeUpdate` / `afterUpdate`

Shimmed for backward compatibility but not available in components using runes.

- Use `$effect.pre` instead of `beforeUpdate`
- Use `$effect` instead of `afterUpdate`

### Chat Window Example

```svelte
<script>
  import { tick } from 'svelte';

  let theme = $state('dark');
  let messages = $state([]);
  let viewport;

  $effect.pre(() => {
    messages;
    const autoscroll = viewport && viewport.offsetHeight + viewport.scrollTop > viewport.scrollHeight - 50;

    if (autoscroll) {
      tick().then(() => {
        viewport.scrollTo(0, viewport.scrollHeight);
      });
    }
  });

  function handleKeydown(event) {
    if (event.key === 'Enter') {
      const text = event.target.value;
      if (!text) return;

      messages = [...messages, text];
      event.target.value = '';
    }
  }

  function toggle() {
    theme = theme === 'dark' ? 'light' : 'dark';
  }
</script>

<div class:dark={theme === 'dark'}>
  <div bind:this={viewport}>
    {#each messages as message}
      <p>{message}</p>
    {/each}
  </div>

  <input onkeydown={handleKeydown} />

  <button onclick={toggle}> Toggle dark mode </button>
</div>
```

## docs/svelte/06-runtime/04-imperative-component-api.md

# Imperative Component API

## `mount`

Creates and mounts a component to a target element:

```js
import { mount } from 'svelte';
import App from './App.svelte';

const app = mount(App, {
  target: document.querySelector('#app'),
  props: { some: 'property' }
});
```

**Note**: Effects (including `onMount` callbacks and action functions) don't run during `mount`. Use `flushSync()` to force pending effects to run.

## `unmount`

Removes a previously mounted component:

```js
import { mount, unmount } from 'svelte';
import App from './App.svelte';

const app = mount(App, { target: document.body });

// later
unmount(app, { outro: true });
```

Returns a `Promise` that resolves after transitions complete (if `outro: true`) or immediately otherwise.

## `render`

Server-side only. Returns HTML for server rendering:

```js
import { render } from 'svelte/server';
import App from './App.svelte';

const result = render(App, {
  props: { some: 'property' }
});
result.body; // HTML for <body>
result.head; // HTML for <head>
```

## `hydrate`

Reuses SSR-rendered HTML and makes it interactive:

```js
import { hydrate } from 'svelte';
import App from './App.svelte';

const app = hydrate(App, {
  target: document.querySelector('#app'),
  props: { some: 'property' }
});
```

Like `mount`, effects don't run during `hydrate` - use `flushSync()` afterward if needed.

## docs/svelte/07-misc/02-testing.md

# Svelte Testing Guide

## Unit and Integration Testing with Vitest

### Setup

```bash
npm install -D vitest
```

Configure Vite:

```js
// vite.config.js
import { defineConfig } from'vitest/config';

export default defineConfig({
  // Tell Vitest to use browser entry points
  resolve: process.env.VITEST
    ? { conditions: ['browser'] }
    : undefined
});
```

### Testing JavaScript Functions

```js
// multiplier.svelte.test.js
import { flushSync } from 'svelte';
import { expect, test } from 'vitest';
import { multiplier } from './multiplier.svelte.js';

test('Multiplier', () => {
  let double = multiplier(0, 2);
  expect(double.value).toEqual(0);
  
  double.set(5);
  expect(double.value).toEqual(10);
});
```

### Using Runes in Tests

Filename must include `.svelte`:

```js
// multiplier.svelte.test.js
import { flushSync } from 'svelte';
import { expect, test } from 'vitest';
import { multiplier } from './multiplier.svelte.js';

test('Multiplier', () => {
  let count = $state(0);
  let double = multiplier(() => count, 2);
  
  expect(double.value).toEqual(0);
  count = 5;
  expect(double.value).toEqual(10);
});
```

### Testing Effects

Wrap in `$effect.root` and use `flushSync()`:

```js
// logger.svelte.test.js
import { flushSync } from 'svelte';
import { expect, test } from 'vitest';
import { logger } from './logger.svelte.js';

test('Effect', () => {
  const cleanup = $effect.root(() => {
    let count = $state(0);
    let log = logger(() => count);
    
    flushSync();
    expect(log.value).toEqual([0]);
    
    count = 1;
    flushSync();
    expect(log.value).toEqual([0, 1]);
  });
  
  cleanup();
});
```

## Component Testing

### Setup

```bash
npm install -D jsdom
```

Update Vite config:

```js
// vite.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom'
  },
  resolve: process.env.VITEST
    ? { conditions: ['browser'] }
    : undefined
});
```

### Basic Component Test

```js
// component.test.js
import { flushSync, mount, unmount } from 'svelte';
import { expect, test } from 'vitest';
import Component from './Component.svelte';

test('Component', () => {
  const component = mount(Component, {
    target: document.body,
    props: { initial: 0 }
  });
  
  expect(document.body.innerHTML).toBe('<button>0</button>');
  
  document.body.querySelector('button').click();
  flushSync();
  
  expect(document.body.innerHTML).toBe('<button>1</button>');
  
  unmount(component);
});
```

### Using Testing Library

```js
// component.test.js
import { render, screen } from '@testing-library/svelte';
import userEvent from '@testing-library/user-event';
import { expect, test } from 'vitest';
import Component from './Component.svelte';

test('Component', async () => {
  const user = userEvent.setup();
  render(Component);
  
  const button = screen.getByRole('button');
  expect(button).toHaveTextContent(0);
  
  await user.click(button);
  expect(button).toHaveTextContent(1);
});
```

## E2E Testing with Playwright

### Setup

Install via VS Code extension or:

```bash
npm init playwright
```

Configure Playwright:

```js
// playwright.config.js
const config = {
  webServer: {
    command: 'npm run build && npm run preview',
    port: 4173
  },
  testDir: 'tests',
  testMatch: /(.+\.)?(test|spec)\.[jt]s/
};

export default config;
```

### Writing Tests

```js
// tests/hello-world.spec.js
import { expect, test } from '@playwright/test';

test('home page has expected h1', async ({ page }) => {
  await page.goto('/');
  await expect(page.locator('h1')).toBeVisible();
});
```

## docs/svelte/07-misc/03-typescript.md

# Svelte 5 TypeScript Guide

## Basic Usage

Add `lang="ts"` to script tags:

```svelte
<script lang="ts">
	let name: string = 'world';

	function greet(name: string) {
		alert(`Hello, ${name}!`);
	}
</script>

<button onclick={(e: Event) => greet(e.target.innerText)}>
	{name as string}
</button>
```

Only type-only features are supported without preprocessors. Unsupported features:
- enums
- access modifiers with initializers
- non-ECMAScript standard features

## Setup

### SvelteKit/Vite (Recommended)

```ts
// svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

const config = {
	preprocess: vitePreprocess()
};

export default config;
```

For non-type-only features:

```ts
// svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

const config = {
	preprocess: vitePreprocess({ script: true })
};

export default config;
```

### tsconfig.json Requirements

- `target`: at least `ES2022` or `ES2015` with `useDefineForClassFields`
- `verbatimModuleSyntax`: `true`
- `isolatedModules`: `true`

## Typing Components

### $props

```svelte
<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		requiredProperty: number;
		optionalProperty?: boolean;
		snippetWithStringArgument: Snippet<[string]>;
		eventHandler: (arg: string) => void;
		[key: string]: unknown;
	}

	let {
		requiredProperty,
		optionalProperty,
		snippetWithStringArgument,
		eventHandler,
		...everythingElse
	}: Props = $props();
</script>
```

### Generic Components

```svelte
<script lang="ts" generics="Item extends { text: string }">
	interface Props {
		items: Item[];
		select(item: Item): void;
	}

	let { items, select }: Props = $props();
</script>
```

### Wrapper Components

```svelte
<script lang="ts">
	import type { HTMLButtonAttributes } from 'svelte/elements';

	let { children, ...rest }: HTMLButtonAttributes = $props();
</script>

<button {...rest}>
	{@render children?.()}
</button>
```

For elements without dedicated types:

```svelte
<script lang="ts">
	import type { SvelteHTMLElements } from 'svelte/elements';

	let { children, ...rest }: SvelteHTMLElements['div'] = $props();
</script>
```

## Typing Runes

### $state

```ts
let count: number = $state(0);
```

For undefined initial values:

```ts
class Counter {
	count = $state() as number;
	constructor(initial: number) {
		this.count = initial;
	}
}
```

## Component Types

### Component Type

```svelte
<script lang="ts">
	import type { Component } from 'svelte';

	interface Props {
		DynamicComponent: Component<{ prop: string }>;
	}

	let { DynamicComponent }: Props = $props();
</script>

<DynamicComponent prop="foo" />
```

### ComponentProps

```ts
import type { Component, ComponentProps } from 'svelte';
import MyComponent from './MyComponent.svelte';

function withProps<TComponent extends Component<any>>(
	component: TComponent,
	props: ComponentProps<TComponent>
) {}

withProps(MyComponent, { foo: 'bar' });
```

### Component Instance

```svelte
<script lang="ts">
	import MyComponent from './MyComponent.svelte';

	let componentConstructor: typeof MyComponent = MyComponent;
	let componentInstance: MyComponent;
</script>

<MyComponent bind:this={componentInstance} />
```

## Extending DOM Types

For custom elements or attributes:

```ts
// additional-svelte-typings.d.ts
declare namespace svelteHTML {
	interface IntrinsicElements {
		'my-custom-element': { someattribute: string; 'on:event': (e: CustomEvent<any>) => void };
	}
	interface HTMLAttributes<T> {
		onbeforeinstallprompt?: (event: any) => any;
		mycustomattribute?: any;
	}
}
```

Or by augmenting modules:

```ts
// additional-svelte-typings.d.ts
import { HTMLButtonAttributes } from 'svelte/elements';

declare module 'svelte/elements' {
	export interface SvelteHTMLElements {
		'custom-button': HTMLButtonAttributes;
	}

	export interface HTMLButtonAttributes {
		veryexperimentalattribute?: string;
	}
}

export {};
```

Instructions for LLMs: <SYSTEM>Always use Svelte 5 runes and Svelte 5 syntax. Runes do not need to be imported, they are globals. $state() runes are always declared using `let`, never with `const`. When passing a function to $derived, you must always use $derived.by(() => ...). Error boundaries can only catch errors during component rendering and at the top level of an $effect inside the error boundary. Error boundaries do not catch errors in onclick or other event handlers.</SYSTEM>