@sveltejs/opencode 0.1.3 → 0.1.5

package/README.md

@@ -40,7 +40,7 @@ The default configuration:
 
 ```json
 {
-	"$schema": "https://raw.githubusercontent.com/sveltejs/mcp/refs/heads/main/packages/opencode/schema.json",
+	"$schema": "https://raw.githubusercontent.com/sveltejs/ai-tools/refs/heads/main/packages/opencode/schema.json",
 	"mcp": {
 		"type": "remote",
 		"enabled": true

package/config.ts

@@ -4,6 +4,28 @@ import { homedir } from 'os';
 import { join } from 'path';
 import * as v from 'valibot';
 
+// Schema for individual agent configuration
+const agent_config_schema = v.object({
+	model: v.pipe(
+		v.optional(v.string()),
+		v.description('Model identifier for the agent (e.g., "anthropic/claude-sonnet-4-20250514")'),
+	),
+	temperature: v.pipe(
+		v.optional(v.number()),
+		v.description('Temperature setting for the agent (e.g., 0.7)'),
+	),
+	top_p: v.pipe(
+		v.optional(v.number()),
+		v.description(
+			'Control response diversity with the top_p option. Alternative to temperature for controlling randomness.',
+		),
+	),
+	maxSteps: v.pipe(
+		v.optional(v.number()),
+		v.description('Maximum number of steps the agent can take (e.g., 10)'),
+	),
+});
+
 const default_config = {
 	mcp: {
 		type: 'remote' as 'remote' | 'local',
@@ -11,36 +33,61 @@ const default_config = {
 	},
 	subagent: {
 		enabled: true,
+		agents: {} as Record<string, v.InferInput<typeof agent_config_schema>>,
 	},
 	instructions: {
 		enabled: true,
 	},
 	skills: {
-		enabled: true,
+		enabled: true as boolean | string[],
 	},
 };
 
 export const config_schema = v.object({
-	mcp: v.optional(
-		v.object({
-			type: v.optional(v.picklist(['remote', 'local'])),
-			enabled: v.optional(v.boolean()),
-		}),
+	mcp: v.pipe(
+		v.optional(
+			v.object({
+				type: v.optional(v.picklist(['remote', 'local'])),
+				enabled: v.optional(v.boolean()),
+			}),
+		),
+		v.description(
+			"Configuration for the MCP. You can chose if it should be enabled or not and the transport to use 'remote' (default) and 'local'.",
+		),
 	),
-	subagent: v.optional(
-		v.object({
-			enabled: v.optional(v.boolean()),
-		}),
+	subagent: v.pipe(
+		v.optional(
+			v.object({
+				enabled: v.optional(v.boolean()),
+				agents: v.optional(v.record(v.string(), agent_config_schema)),
+			}),
+		),
+		v.description('Configuration for the subagent. You can choose if it should be enabled or not.'),
 	),
-	instructions: v.optional(
-		v.object({
-			enabled: v.optional(v.boolean()),
-		}),
+	instructions: v.pipe(
+		v.optional(
+			v.object({
+				enabled: v.optional(v.boolean()),
+			}),
+		),
+		v.description(
+			'Configuration for the automatic AGENTS.md injection. You can choose if it should be enabled or not.',
+		),
 	),
-	skills: v.optional(
-		v.object({
-			enabled: v.optional(v.boolean()),
-		}),
+	skills: v.pipe(
+		v.optional(
+			v.object({
+				enabled: v.pipe(
+					v.optional(v.union([v.boolean(), v.array(v.string())])),
+					v.description(
+						'It can be either a boolean or an array containing the skills that you want to enable',
+					),
+				),
+			}),
+		),
+		v.description(
+			'Configuration for the skills. You can choose if it they should be enabled or not, or specify an array of skill names to enable only specific skills.',
+		),
 	),
 });
 
@@ -112,8 +159,12 @@ function merge_with_defaults(user_config: Partial<McpConfig>): McpConfig {
 			...user_config.mcp,
 		},
 		subagent: {
-			...default_config.subagent,
+			enabled: default_config.subagent.enabled,
 			...user_config.subagent,
+			agents: {
+				...default_config.subagent.agents,
+				...user_config.subagent?.agents,
+			},
 		},
 		instructions: {
 			...default_config.instructions,
@@ -151,7 +202,11 @@ export function get_mcp_config(ctx: PluginInput) {
 			if (parsed.success) {
 				merged = {
 					mcp: { ...merged.mcp, ...parsed.output.mcp },
-					subagent: { ...merged.subagent, ...parsed.output.subagent },
+					subagent: {
+						...merged.subagent,
+						...parsed.output.subagent,
+						agents: { ...merged.subagent?.agents, ...parsed.output.subagent?.agents },
+					},
 					instructions: { ...merged.instructions, ...parsed.output.instructions },
 					skills: { ...merged.skills, ...parsed.output.skills },
 				};

package/index.ts

@@ -39,29 +39,41 @@ export const svelte_plugin: Plugin = async (ctx) => {
 				input.instructions.push(...instructions_paths.map((file) => join(instructions_dir, file)));
 			}
 
-			if (mcp_config.skills?.enabled !== false) {
+			const skills_enabled = mcp_config.skills?.enabled;
+			if (skills_enabled !== false) {
 				const skills_dir = join(current_dir, 'skills');
-				// @ts-expect-error -- skills is a new opencode feature
-				input.skills.paths.push(skills_dir);
+				if (Array.isArray(skills_enabled)) {
+					// only add specific skill directories by name
+					for (const skill_name of skills_enabled) {
+						const skill_path = join(skills_dir, skill_name);
+						// @ts-expect-error -- skills is a new opencode feature
+						input.skills.paths.push(skill_path);
+					}
+				} else {
+					// @ts-expect-error -- skills is a new opencode feature
+					input.skills.paths.push(skills_dir);
+				}
 			}
 
 			// if the user doesn't have the MCP server already we add one based on config
-			if (!input.mcp[svelte_mcp_name] && mcp_config.mcp?.enabled !== false) {
+			if (!input.mcp[svelte_mcp_name]) {
 				if (mcp_config.mcp?.type === 'remote') {
 					input.mcp[svelte_mcp_name] = {
 						type: 'remote',
 						url: 'https://mcp.svelte.dev/mcp',
+						enabled: mcp_config.mcp?.enabled ?? true,
 					};
 				} else {
 					input.mcp[svelte_mcp_name] = {
 						type: 'local',
 						command: ['npx', '-y', '@sveltejs/mcp'],
+						enabled: mcp_config.mcp?.enabled ?? true,
 					};
 				}
 			}
 			if (mcp_config.subagent?.enabled !== false) {
 				// we add the editor subagent that will be used when editing Svelte files to prevent wasting context on the main agent
-				input.agent['svelte-file-editor'] = {
+				const default_config: (typeof input.agent)[string] = {
 					color: '#ff3e00',
 					mode: 'subagent',
 					prompt: `You are a Svelte 5 expert responsible for writing, editing, and validating Svelte components and modules. You have access to the Svelte MCP server which provides documentation and code analysis tools. Always use the tools from the svelte MCP server to fetch documentation with \`get_documentation\` and validating the code with \`svelte_autofixer\`. If the autofixer returns any issue or suggestions try to solve them.
@@ -138,6 +150,27 @@ After completing your work, provide:
 						[`${svelte_mcp_name}_*`]: true,
 					},
 				};
+
+				// Get per-agent config from svelte.json (if any)
+				const svelte_file_editor_config = mcp_config.subagent?.agents?.['svelte-file-editor'];
+
+				// Configure agent from svelte.json only
+				// Priority: svelte.json agent config > defaults
+				input.agent['svelte-file-editor'] = {
+					...default_config,
+					...(svelte_file_editor_config?.model !== undefined && {
+						model: svelte_file_editor_config.model,
+					}),
+					...(svelte_file_editor_config?.temperature !== undefined && {
+						temperature: svelte_file_editor_config.temperature,
+					}),
+					...(svelte_file_editor_config?.maxSteps !== undefined && {
+						maxSteps: svelte_file_editor_config.maxSteps,
+					}),
+					...(svelte_file_editor_config?.top_p !== undefined && {
+						top_p: svelte_file_editor_config.top_p,
+					}),
+				};
 			}
 		},
 	};

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@sveltejs/opencode",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "license": "MIT",
-  "homepage": "https://github.com/sveltejs/mcp#readme",
+  "homepage": "https://github.com/sveltejs/ai-tools#readme",
   "bugs": {
-    "url": "https://github.com/sveltejs/mcp/issues"
+    "url": "https://github.com/sveltejs/ai-tools/issues"
   },
   "files": [
     "index.ts",
@@ -15,7 +15,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sveltejs/mcp.git",
+    "url": "git+https://github.com/sveltejs/ai-tools.git",
     "path": "packages/opencode"
   },
   "publishConfig": {

package/skills/svelte-core-bestpractices/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: svelte-core-bestpractices
+description: Guidance on writing fast, robust, modern Svelte code. Load this skill whenever in a Svelte project and asked to write/edit or analyze a Svelte component or module. Covers reactivity, event handling, styling, integration with libraries and more.
+---
+
+## `$state`
+
+Only use the `$state` rune for variables that should be _reactive_ — in other words, variables that cause an `$effect`, `$derived` or template expression to update. Everything else can be a normal variable.
+
+Objects and arrays (`$state({...})` or `$state([...])`) are made deeply reactive, meaning mutation will trigger updates. This has a trade-off: in exchange for fine-grained reactivity, the objects must be proxied, which has performance overhead. In cases where you're dealing with large objects that are only ever reassigned (rather than mutated), use `$state.raw` instead. This is often the case with API responses, for example.
+
+## `$derived`
+
+To compute something from state, use `$derived` rather than `$effect`:
+
+```js
+// do this
+let square = $derived(num * num);
+
+// don't do this
+let square;
+
+$effect(() => {
+	square = num * num;
+});
+```
+
+> [!NOTE] `$derived` is given an expression, _not_ a function. If you need to use a function (because the expression is complex, for example) use `$derived.by`.
+
+Deriveds are writable — you can assign to them, just like `$state`, except that they will re-evaluate when their expression changes.
+
+If the derived expression is an object or array, it will be returned as-is — it is _not_ made deeply reactive. You can, however, use `$state` inside `$derived.by` in the rare cases that you need this.
+
+## `$effect`
+
+Effects are an escape hatch and should mostly be avoided. In particular, avoid updating state inside effects.
+
+- If you need to sync state to an external library such as D3, it is often neater to use [`{@attach ...}`](references/@attach.md)
+- If you need to run some code in response to user interaction, put the code directly in an event handler or use a [function binding](references/bind.md) as appropriate
+- If you need to log values for debugging purposes, use [`$inspect`](references/$inspect.md)
+- If you need to observe something external to Svelte, use [`createSubscriber`](references/svelte-reactivity.md)
+
+Never wrap the contents of an effect in `if (browser) {...}` or similar — effects do not run on the server.
+
+## `$props`
+
+Treat props as though they will change. For example, values that depend on props should usually use `$derived`:
+
+```js
+// @errors: 2451
+let { type } = $props();
+
+// do this
+let color = $derived(type === 'danger' ? 'red' : 'green');
+
+// don't do this — `color` will not update if `type` changes
+let color = type === 'danger' ? 'red' : 'green';
+```
+
+## `$inspect.trace`
+
+`$inspect.trace` is a debugging tool for reactivity. If something is not updating properly or running more than it should you can add `$inspect.trace(label)` as the first line of an `$effect` or `$derived.by` (or any function they call) to trace their dependencies and discover which one triggered an update.
+
+## Events
+
+Any element attribute starting with `on` is treated as an event listener:
+
+```svelte
+<button onclick={() => {...}}>click me</button>
+
+<!-- attribute shorthand also works -->
+<button {onclick}>...</button>
+
+<!-- so do spread attributes -->
+<button {...props}>...</button>
+```
+
+If you need to attach listeners to `window` or `document` you can use `<svelte:window>` and `<svelte:document>`:
+
+```svelte
+<svelte:window onkeydown={...} />
+<svelte:document onvisibilitychange={...} />
+```
+
+Avoid using `onMount` or `$effect` for this.
+
+## Snippets
+
+[Snippets](references/snippet.md) are a way to define reusable chunks of markup that can be instantiated with the [`{@render ...}`](references/@render.md) tag, or passed to components as props. They must be declared within the template.
+
+```svelte
+{#snippet greeting(name)}
+	<p>hello {name}!</p>
+{/snippet}
+
+{@render greeting('world')}
+```
+
+> [!NOTE] Snippets declared at the top level of a component (i.e. not inside elements or blocks) can be referenced inside `<script>`. A snippet that doesn't reference component state is also available in a `<script module>`, in which case it can be exported for use by other components.
+
+## Each blocks
+
+Prefer to use [keyed each blocks](references/each.md) — this improves performance by allowing Svelte to surgically insert or remove items rather than updating the DOM belonging to existing items.
+
+> [!NOTE] The key _must_ uniquely identify the object. Do not use the index as a key.
+
+Avoid destructuring if you need to mutate the item (with something like `bind:value={item.count}`, for example).
+
+## Using JavaScript variables in CSS
+
+If you have a JS variable that you want to use inside CSS you can set a CSS custom property with the `style:` directive.
+
+```svelte
+<div style:--columns={columns}>...</div>
+```
+
+You can then reference `var(--columns)` inside the component's `<style>`.
+
+## Styling child components
+
+The CSS in a component's `<style>` is scoped to that component. If a parent component needs to control the child's styles, the preferred way is to use CSS custom properties:
+
+```svelte
+<!-- Parent.svelte -->
+<Child --color="red" />
+
+<!-- Child.svelte -->
+<h1>Hello</h1>
+
+<style>
+	h1 {
+		color: var(--color);
+	}
+</style>
+```
+
+If this impossible (for example, the child component comes from a library) you can use `:global` to override styles:
+
+```svelte
+<div>
+	<Child />
+</div>
+
+<style>
+	div :global {
+		h1 {
+			color: red;
+		}
+	}
+</style>
+```
+
+## Context
+
+Consider using context instead of declaring state in a shared module. This will scope the state to the part of the app that needs it, and eliminate the possibility of it leaking between users when server-side rendering.
+
+Use `createContext` rather than `setContext` and `getContext`, as it provides type safety.
+
+## Async Svelte
+
+If using version 5.36 or higher, you can use [await expressions](references/await-expressions.md) and [hydratable](references/hydratable.md) to use promises directly inside components. Note that these require the `experimental.async` option to be enabled in `svelte.config.js` as they are not yet considered fully stable.
+
+## Avoid legacy features
+
+Always use runes mode for new code, and avoid features that have more modern replacements:
+
+- use `$state` instead of implicit reactivity (e.g. `let count = 0; count += 1`)
+- use `$derived` and `$effect` instead of `$:` assignments and statements (but only use effects when there is no better solution)
+- use `$props` instead of `export let`, `$$props` and `$$restProps`
+- use `onclick={...}` instead of `on:click={...}`
+- use `{#snippet ...}` and `{@render ...}` instead of `<slot>` and `$$slots` and `<svelte:fragment>`
+- use `<DynamicComponent>` instead of `<svelte:component this={DynamicComponent}>`
+- use `import Self from './ThisComponent.svelte'` and `<Self>` instead of `<svelte:self>`
+- use classes with `$state` fields to share reactivity between components, instead of using stores
+- use `{@attach ...}` instead of `use:action`
+- use clsx-style arrays and objects in `class` attributes, instead of the `class:` directive

package/skills/svelte-core-bestpractices/references/$inspect.md

@@ -0,0 +1,53 @@
+> [!NOTE] `$inspect` only works during development. In a production build it becomes a noop.
+
+The `$inspect` rune is roughly equivalent to `console.log`, with the exception that it will re-run whenever its argument changes. `$inspect` tracks reactive state deeply, meaning that updating something inside an object or array using fine-grained reactivity will cause it to re-fire (demo:
+
+```svelte
+<script>
+	let count = $state(0);
+	let message = $state('hello');
+
+	$inspect(count, message); // will console.log when `count` or `message` change
+</script>
+
+<button onclick={() => count++}>Increment</button>
+<input bind:value={message} />
+```
+
+On updates, a stack trace will be printed, making it easy to find the origin of a state change (unless you're in the playground, due to technical limitations).
+
+## $inspect(...).with
+
+`$inspect` returns a property `with`, which you can invoke with a callback, which will then be invoked instead of `console.log`. The first argument to the callback is either `"init"` or `"update"`; subsequent arguments are the values passed to `$inspect` (demo:
+
+```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>
+```
+
+## $inspect.trace(...)
+
+This rune, added in 5.14, causes the surrounding function to be _traced_ in development. Any time the function re-runs as part of an [effect]($effect) or a [derived]($derived), information will be printed to the console about which pieces of reactive state caused the effect to fire.
+
+```svelte
+<script>
+	import { doSomeWork } from './elsewhere';
+
+	$effect(() => {
+		+++// $inspect.trace must be the first statement of a function body+++
+		+++$inspect.trace();+++
+		doSomeWork();
+	});
+</script>
+```
+
+`$inspect.trace` takes an optional first argument which will be used as the label.

package/skills/svelte-core-bestpractices/references/@attach.md

@@ -0,0 +1,166 @@
+Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates.
+
+Optionally, they can return a function that is called before the attachment re-runs, or after the element is later removed from the DOM.
+
+> [!NOTE]
+> Attachments are available in Svelte 5.29 and newer.
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	/** @type {import('svelte/attachments').Attachment} */
+	function myAttachment(element) {
+		console.log(element.nodeName); // 'DIV'
+
+		return () => {
+			console.log('cleaning up');
+		};
+	}
+</script>
+
+<div {@attach myAttachment}>...</div>
+```
+
+An element can have any number of attachments.
+
+## Attachment factories
+
+A useful pattern is for a function, such as `tooltip` in this example, to _return_ an attachment (demo:
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import tippy from 'tippy.js';
+
+	let content = $state('Hello!');
+
+	/**
+	 * @param {string} content
+	 * @returns {import('svelte/attachments').Attachment}
+	 */
+	function tooltip(content) {
+		return (element) => {
+			const tooltip = tippy(element, { content });
+			return tooltip.destroy;
+		};
+	}
+</script>
+
+<input bind:value={content} />
+
+<button {@attach tooltip(content)}> Hover me </button>
+```
+
+Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read _inside_ the attachment function when it first runs. (If this isn't what you want, see [Controlling when attachments re-run](#Controlling-when-attachments-re-run).)
+
+## Inline attachments
+
+Attachments can also be created inline (demo:
+
+```svelte
+<!--- file: App.svelte --->
+<canvas
+	width={32}
+	height={32}
+	{@attach (canvas) => {
+		const context = canvas.getContext('2d');
+
+		$effect(() => {
+			context.fillStyle = color;
+			context.fillRect(0, 0, canvas.width, canvas.height);
+		});
+	}}
+></canvas>
+```
+
+> [!NOTE]
+> The nested effect runs whenever `color` changes, while the outer effect (where `canvas.getContext(...)` is called) only runs once, since it doesn't read any reactive state.
+
+## Conditional attachments
+
+Falsy values like `false` or `undefined` are treated as no attachment, enabling conditional usage:
+
+```svelte
+<div {@attach enabled && myAttachment}>...</div>
+```
+
+## Passing attachments to components
+
+When used on a component, `{@attach ...}` will create a prop whose key is a [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol). If the component then [spreads](/tutorial/svelte/spread-props) props onto an element, the element will receive those attachments.
+
+This allows you to create _wrapper components_ that augment elements (demo:
+
+```svelte
+<!--- file: Button.svelte --->
+<script>
+	/** @type {import('svelte/elements').HTMLButtonAttributes} */
+	let { children, ...props } = $props();
+</script>
+
+<!-- `props` includes attachments -->
+<button {...props}>
+	{@render children?.()}
+</button>
+```
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import tippy from 'tippy.js';
+	import Button from './Button.svelte';
+
+	let content = $state('Hello!');
+
+	/**
+	 * @param {string} content
+	 * @returns {import('svelte/attachments').Attachment}
+	 */
+	function tooltip(content) {
+		return (element) => {
+			const tooltip = tippy(element, { content });
+			return tooltip.destroy;
+		};
+	}
+</script>
+
+<input bind:value={content} />
+
+<Button {@attach tooltip(content)}>Hover me</Button>
+```
+
+## Controlling when attachments re-run
+
+Attachments, unlike [actions](use), are fully reactive: `{@attach foo(bar)}` will re-run on changes to `foo` _or_ `bar` (or any state read inside `foo`):
+
+```js
+// @errors: 7006 2304 2552
+function foo(bar) {
+	return (node) => {
+		veryExpensiveSetupWork(node);
+		update(node, bar);
+	};
+}
+```
+
+In the rare case that this is a problem (for example, if `foo` does expensive and unavoidable setup work) consider passing the data inside a function and reading it in a child effect:
+
+```js
+// @errors: 7006 2304 2552
+function foo(+++getBar+++) {
+	return (node) => {
+		veryExpensiveSetupWork(node);
+
++++		$effect(() => {
+			update(node, getBar());
+		});+++
+	}
+}
+```
+
+## Creating attachments programmatically
+
+To add attachments to an object that will be spread onto a component or element, use [`createAttachmentKey`](svelte-attachments#createAttachmentKey).
+
+## Converting actions to attachments
+
+If you're using a library that only provides actions, you can convert them to attachments with [`fromAction`](svelte-attachments#fromAction), allowing you to (for example) use them with components.

package/skills/svelte-core-bestpractices/references/@render.md

@@ -0,0 +1,35 @@
+To render a [snippet](snippet), use a `{@render ...}` tag.
+
+```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 like `sum`, or an arbitrary JavaScript expression:
+
+```svelte
+{@render (cool ? coolSnippet : lameSnippet)()}
+```
+
+## Optional snippets
+
+If the snippet is potentially undefined — for example, because it's an incoming prop — then you can use optional chaining to only render it when it _is_ defined:
+
+```svelte
+{@render children?.()}
+```
+
+Alternatively, use an [`{#if ...}`](if) block with an `:else` clause to render fallback content:
+
+```svelte
+{#if children}
+	{@render children()}
+{:else}
+	<p>fallback content</p>
+{/if}
+```

package/skills/svelte-core-bestpractices/references/await-expressions.md

@@ -0,0 +1,180 @@
+As of Svelte 5.36, you can use the `await` keyword inside your components in three places where it was previously unavailable:
+
+- at the top level of your component's `<script>`
+- inside `$derived(...)` declarations
+- inside your markup
+
+This feature is currently experimental, and you must opt in by adding the `experimental.async` option wherever you [configure](/docs/kit/configuration) Svelte, usually `svelte.config.js`:
+
+```js
+/// file: svelte.config.js
+export default {
+	compilerOptions: {
+		experimental: {
+			async: true,
+		},
+	},
+};
+```
+
+The experimental flag will be removed in Svelte 6.
+
+## Synchronized updates
+
+When an `await` expression depends on a particular piece of state, changes to that state will not be reflected in the UI until the asynchronous work has completed, so that the UI is not left in an inconsistent state. In other words, in an example like this...
+
+```svelte
+<script>
+	let a = $state(1);
+	let b = $state(2);
+
+	async function add(a, b) {
+		await new Promise((f) => setTimeout(f, 500)); // artificial delay
+		return a + b;
+	}
+</script>
+
+<input type="number" bind:value={a} />
+<input type="number" bind:value={b} />
+
+<p>{a} + {b} = {await add(a, b)}</p>
+```
+
+...if you increment `a`, the contents of the `<p>` will _not_ immediately update to read this —
+
+```html
+<p>2 + 2 = 3</p>
+```
+
+— instead, the text will update to `2 + 2 = 4` when `add(a, b)` resolves.
+
+Updates can overlap — a fast update will be reflected in the UI while an earlier slow update is still ongoing.
+
+## Concurrency
+
+Svelte will do as much asynchronous work as it can in parallel. For example if you have two `await` expressions in your markup...
+
+```svelte
+<p>{await one()}</p><p>{await two()}</p>
+```
+
+...both functions will run at the same time, as they are independent expressions, even though they are _visually_ sequential.
+
+This does not apply to sequential `await` expressions inside your `<script>` or inside async functions — these run like any other asynchronous JavaScript. An exception is that independent `$derived` expressions will update independently, even though they will run sequentially when they are first created:
+
+```js
+// these will run sequentially the first time,
+// but will update independently
+let a = $derived(await one());
+let b = $derived(await two());
+```
+
+> [!NOTE] If you write code like this, expect Svelte to give you an [`await_waterfall`](runtime-warnings#Client-warnings-await_waterfall) warning
+
+## Indicating loading states
+
+To render placeholder UI, you can wrap content in a `<svelte:boundary>` with a [`pending`](svelte-boundary#Properties-pending) snippet. This will be shown when the boundary is first created, but not for subsequent updates, which are globally coordinated.
+
+After the contents of a boundary have resolved for the first time and have replaced the `pending` snippet, you can detect subsequent async work with [`$effect.pending()`]($effect#$effect.pending). This is what you would use to display a "we're asynchronously validating your input" spinner next to a form field, for example.
+
+You can also use [`settled()`](svelte#settled) to get a promise that resolves when the current update is complete:
+
+```js
+import { tick, settled } from 'svelte';
+
+async function onclick() {
+	updating = true;
+
+	// without this, the change to `updating` will be
+	// grouped with the other changes, meaning it
+	// won't be reflected in the UI
+	await tick();
+
+	color = 'octarine';
+	answer = 42;
+
+	await settled();
+
+	// any updates affected by `color` or `answer`
+	// have now been applied
+	updating = false;
+}
+```
+
+## Error handling
+
+Errors in `await` expressions will bubble to the nearest [error boundary](svelte-boundary).
+
+## Server-side rendering
+
+Svelte supports asynchronous server-side rendering (SSR) with the `render(...)` API. To use it, simply await the return value:
+
+```js
+/// file: server.js
+import { render } from 'svelte/server';
+import App from './App.svelte';
+
+const { head, body } = +++await+++ render(App);
+```
+
+> [!NOTE] If you're using a framework like SvelteKit, this is done on your behalf.
+
+If a `<svelte:boundary>` with a `pending` snippet is encountered during SSR, that snippet will be rendered while the rest of the content is ignored. All `await` expressions encountered outside boundaries with `pending` snippets will resolve and render their contents prior to `await render(...)` returning.
+
+> [!NOTE] In the future, we plan to add a streaming implementation that renders the content in the background.
+
+## Forking
+
+The [`fork(...)`](svelte#fork) API, added in 5.42, makes it possible to run `await` expressions that you _expect_ to happen in the near future. This is mainly intended for frameworks like SvelteKit to implement preloading when (for example) users signal an intent to navigate.
+
+```svelte
+<script>
+	import { fork } from 'svelte';
+	import Menu from './Menu.svelte';
+
+	let open = $state(false);
+
+	/** @type {import('svelte').Fork | null} */
+	let pending = null;
+
+	function preload() {
+		pending ??= fork(() => {
+			open = true;
+		});
+	}
+
+	function discard() {
+		pending?.discard();
+		pending = null;
+	}
+</script>
+
+<button
+	onfocusin={preload}
+	onfocusout={discard}
+	onpointerenter={preload}
+	onpointerleave={discard}
+	onclick={() => {
+		pending?.commit();
+		pending = null;
+
+		// in case `pending` didn't exist
+		// (if it did, this is a no-op)
+		open = true;
+	}}>open menu</button
+>
+
+{#if open}
+	<!-- any async work inside this component will start
+	     as soon as the fork is created -->
+	<Menu onclose={() => (open = false)} />
+{/if}
+```
+
+## Caveats
+
+As an experimental feature, the details of how `await` is handled (and related APIs like `$effect.pending()`) are subject to breaking changes outside of a semver major release, though we intend to keep such changes to a bare minimum.
+
+## Breaking changes
+
+Effects run in a slightly different order when the `experimental.async` option is `true`. Specifically, _block_ effects like `{#if ...}` and `{#each ...}` now run before an `$effect.pre` or `beforeUpdate` in the same component, which means that in very rare situations.

package/skills/svelte-core-bestpractices/references/bind.md

@@ -0,0 +1,16 @@
+## Function bindings
+
+You can also use `bind:property={get, set}`, where `get` and `set` are functions, allowing you to perform validation and transformation:
+
+```svelte
+<input bind:value={() => value, (v) => (value = v.toLowerCase())} />
+```
+
+In the case of readonly bindings like [dimension bindings](#Dimensions), the `get` value should be `null`:
+
+```svelte
+<div bind:clientWidth={null, redraw} bind:clientHeight={null, redraw}>...</div>
+```
+
+> [!NOTE]
+> Function bindings are available in Svelte 5.9.0 and newer.

package/skills/svelte-core-bestpractices/references/each.md

@@ -0,0 +1,42 @@
+## Keyed each blocks
+
+```svelte
+<!--- copy: false  --->
+{#each expression as name (key)}...{/each}
+```
+
+```svelte
+<!--- copy: false  --->
+{#each expression as name, index (key)}...{/each}
+```
+
+If a _key_ expression is provided — which must uniquely identify each list item — Svelte will use it to intelligently update the list when data changes by inserting, moving and deleting items, rather than adding or removing items at the end and updating the state in the middle.
+
+The key can be any object, but strings and numbers are recommended since they allow identity to persist when the objects themselves change.
+
+```svelte
+{#each items as item (item.id)}
+	<li>{item.name} x {item.qty}</li>
+{/each}
+
+<!-- or with additional index value -->
+{#each items as item, i (item.id)}
+	<li>{i + 1}: {item.name} x {item.qty}</li>
+{/each}
+```
+
+You can freely use destructuring and rest patterns in each blocks.
+
+```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}
+```

package/skills/svelte-core-bestpractices/references/hydratable.md

@@ -0,0 +1,100 @@
+In Svelte, when you want to render asynchronous content data on the server, you can simply `await` it. This is great! However, it comes with a pitfall: when hydrating that content on the client, Svelte has to redo the asynchronous work, which blocks hydration for however long it takes:
+
+```svelte
+<script>
+	import { getUser } from 'my-database-library';
+
+	// This will get the user on the server, render the user's name into the h1,
+	// and then, during hydration on the client, it will get the user _again_,
+	// blocking hydration until it's done.
+	const user = await getUser();
+</script>
+
+<h1>{user.name}</h1>
+```
+
+That's silly, though. If we've already done the hard work of getting the data on the server, we don't want to get it again during hydration on the client. `hydratable` is a low-level API built to solve this problem. You probably won't need this very often — it will be used behind the scenes by whatever datafetching library you use. For example, it powers [remote functions in SvelteKit](/docs/kit/remote-functions).
+
+To fix the example above:
+
+```svelte
+<script>
+	import { hydratable } from 'svelte';
+	import { getUser } from 'my-database-library';
+
+	// During server rendering, this will serialize and stash the result of `getUser`, associating
+	// it with the provided key and baking it into the `head` content. During hydration, it will
+	// look for the serialized version, returning it instead of running `getUser`. After hydration
+	// is done, if it's called again, it'll simply invoke `getUser`.
+	const user = await hydratable('user', () => getUser());
+</script>
+
+<h1>{user.name}</h1>
+```
+
+This API can also be used to provide access to random or time-based values that are stable between server rendering and hydration. For example, to get a random number that doesn't update on hydration:
+
+```ts
+import { hydratable } from 'svelte';
+const rand = hydratable('random', () => Math.random());
+```
+
+If you're a library author, be sure to prefix the keys of your `hydratable` values with the name of your library so that your keys don't conflict with other libraries.
+
+## Serialization
+
+All data returned from a `hydratable` function must be serializable. But this doesn't mean you're limited to JSON — Svelte uses [`devalue`](https://npmjs.com/package/devalue), which can serialize all sorts of things including `Map`, `Set`, `URL`, and `BigInt`. Check the documentation page for a full list. In addition to these, thanks to some Svelte magic, you can also fearlessly use promises:
+
+```svelte
+<script>
+	import { hydratable } from 'svelte';
+	const promises = hydratable('random', () => {
+		return {
+			one: Promise.resolve(1),
+			two: Promise.resolve(2),
+		};
+	});
+</script>
+
+{await promises.one}
+{await promises.two}
+```
+
+## CSP
+
+`hydratable` adds an inline `<script>` block to the `head` returned from `render`. If you're using [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) (CSP), this script will likely fail to run. You can provide a `nonce` to `render`:
+
+```js
+const nonce = crypto.randomUUID();
+
+const { head, body } = await render(App, {
+	csp: { nonce },
+});
+```
+
+This will add the `nonce` to the script block, on the assumption that you will later add the same nonce to the CSP header of the document that contains it:
+
+```js
+response.headers.set('Content-Security-Policy', `script-src 'nonce-${nonce}'`);
+```
+
+It's essential that a `nonce` — which, British slang definition aside, means 'number used once' — is only used when dynamically server rendering an individual response.
+
+If instead you are generating static HTML ahead of time, you must use hashes instead:
+
+```js
+const { head, body, hashes } = await render(App, {
+	csp: { hash: true },
+});
+```
+
+`hashes.script` will be an array of strings like `["sha256-abcd123"]`. As with `nonce`, the hashes should be used in your CSP header:
+
+```js
+response.headers.set(
+	'Content-Security-Policy',
+	`script-src ${hashes.script.map((hash) => `'${hash}'`).join(' ')}`,
+);
+```
+
+We recommend using `nonce` over hash if you can, as `hash` will interfere with streaming SSR in the future.

package/skills/svelte-core-bestpractices/references/snippet.md

@@ -0,0 +1,276 @@
+```svelte
+<!--- copy: false  --->
+{#snippet name()}...{/snippet}
+```
+
+```svelte
+<!--- copy: false  --->
+{#snippet name(param1, param2, paramN)}...{/snippet}
+```
+
+Snippets, and [render tags](@render), are a way to create reusable chunks of markup inside your components. Instead of writing duplicative code like this...
+
+```svelte
+{#each images as image}
+	{#if image.href}
+		<a href={image.href}>
+			<figure>
+				<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
+				<figcaption>{image.caption}</figcaption>
+			</figure>
+		</a>
+	{:else}
+		<figure>
+			<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
+			<figcaption>{image.caption}</figcaption>
+		</figure>
+	{/if}
+{/each}
+```
+
+...you can write this:
+
+```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}
+```
+
+Like function declarations, snippets can have an arbitrary number of parameters, which can have default values, and you can destructure each parameter. You cannot use rest parameters, however.
+
+## Snippet scope
+
+Snippets can be declared anywhere inside your component. They can reference values declared outside themselves, for example in the `<script>` tag or in `{#each ...}` blocks (demo...
+
+```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')}
+```
+
+...and they are 'visible' to everything in the same lexical scope (i.e. siblings, and children of those siblings):
+
+```svelte
+<div>
+	{#snippet x()}
+		{#snippet y()}...{/snippet}
+
+		<!-- this is fine -->
+		{@render y()}
+	{/snippet}
+
+	<!-- this will error, as `y` is not in scope -->
+	{@render y()}
+</div>
+
+<!-- this will also error, as `x` is not in scope -->
+{@render x()}
+```
+
+Snippets can reference themselves and each other (demo:
+
+```svelte
+{#snippet blastoff()}
+	<span>🚀</span>
+{/snippet}
+
+{#snippet countdown(n)}
+	{#if n > 0}
+		<span>{n}...</span>
+		{@render countdown(n - 1)}
+	{:else}
+		{@render blastoff()}
+	{/if}
+{/snippet}
+
+{@render countdown(10)}
+```
+
+## Passing snippets to components
+
+### Explicit props
+
+Within the template, snippets are values just like any other. As such, they can be passed to components as props (demo:
+
+```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} />
+```
+
+Think about it like passing content instead of data to a component. The concept is similar to slots in web components.
+
+### Implicit props
+
+As an authoring convenience, snippets declared directly _inside_ a component implicitly become props _on_ the component (demo:
+
+```svelte
+<!-- this is semantically the same as the above -->
+<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
+
+Any content inside the component tags that is _not_ a snippet declaration implicitly becomes part of the `children` snippet (demo:
+
+```svelte
+<!--- file: App.svelte --->
+<Button>click me</Button>
+```
+
+```svelte
+<!--- file: Button.svelte --->
+<script>
+	let { children } = $props();
+</script>
+
+<!-- result will be <button>click me</button> -->
+<button>{@render children()}</button>
+```
+
+> [!NOTE] Note that you cannot have a prop called `children` if you also have content inside the component — for this reason, you should avoid having props with that name
+
+### Optional snippet props
+
+You can declare snippet props as being optional. You can either use optional chaining to not render anything if the snippet isn't set...
+
+```svelte
+<script>
+	let { children } = $props();
+</script>
+
+{@render children?.()}
+```
+
+...or use an `#if` block to render fallback content:
+
+```svelte
+<script>
+	let { children } = $props();
+</script>
+
+{#if children}
+	{@render children()}
+{:else}
+	fallback content
+{/if}
+```
+
+## Typing snippets
+
+Snippets implement the `Snippet` interface imported from `'svelte'`:
+
+```svelte
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		data: any[];
+		children: Snippet;
+		row: Snippet<[any]>;
+	}
+
+	let { data, children, row }: Props = $props();
+</script>
+```
+
+With this change, red squigglies will appear if you try and use the component without providing a `data` prop and a `row` snippet. Notice that the type argument provided to `Snippet` is a tuple, since snippets can have multiple parameters.
+
+We can tighten things up further by declaring a generic, so that `data` and `row` refer to the same type:
+
+```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
+
+Snippets declared at the top level of a `.svelte` file can be exported from a `<script module>` for use in other components, provided they don't reference any declarations in a non-module `<script>` (whether directly or indirectly, via other snippets) (demo:
+
+```svelte
+<script module>
+	export { add };
+</script>
+
+{#snippet add(a, b)}
+	{a} + {b} = {a + b}
+{/snippet}
+```
+
+> [!NOTE]
+> This requires Svelte 5.5.0 or newer
+
+## Programmatic snippets
+
+Snippets can be created programmatically with the [`createRawSnippet`](svelte#createRawSnippet) API. This is intended for advanced use cases.
+
+## Snippets and slots
+
+In Svelte 4, content can be passed to components using [slots](legacy-slots). Snippets are more powerful and flexible, and so slots have been deprecated in Svelte 5.

package/skills/svelte-core-bestpractices/references/svelte-reactivity.md

@@ -0,0 +1,61 @@
+## createSubscriber
+
+<blockquote class="since note">
+
+Available since 5.7.0
+
+</blockquote>
+
+Returns a `subscribe` function that integrates external event-based systems with Svelte's reactivity.
+It's particularly useful for integrating with web APIs like `MediaQuery`, `IntersectionObserver`, or `WebSocket`.
+
+If `subscribe` is called inside an effect (including indirectly, for example inside a getter),
+the `start` callback will be called with an `update` function. Whenever `update` is called, the effect re-runs.
+
+If `start` returns a cleanup function, it will be called when the effect is destroyed.
+
+If `subscribe` is called in multiple effects, `start` will only be called once as long as the effects
+are active, and the returned teardown function will only be called when all effects are destroyed.
+
+It's best understood with an example. Here's an implementation of [`MediaQuery`](/docs/svelte/svelte-reactivity#MediaQuery):
+
+```js
+// @errors: 7031
+import { createSubscriber } from 'svelte/reactivity';
+import { on } from 'svelte/events';
+
+export class MediaQuery {
+	#query;
+	#subscribe;
+
+	constructor(query) {
+		this.#query = window.matchMedia(`(${query})`);
+
+		this.#subscribe = createSubscriber((update) => {
+			// when the `change` event occurs, re-run any effects that read `this.current`
+			const off = on(this.#query, 'change', update);
+
+			// stop listening when all the effects are destroyed
+			return () => off();
+		});
+	}
+
+	get current() {
+		// This makes the getter reactive, if read in an effect
+		this.#subscribe();
+
+		// Return the current state of the query, whether or not we're in an effect
+		return this.#query.matches;
+	}
+}
+```
+
+<div class="ts-block">
+
+```dts
+function createSubscriber(
+	start: (update: () => void) => (() => void) | void
+): () => void;
+```
+
+</div>