Closes #15470

We're so back!

Finally, thanks to Syntax and SuppCo that sponsored the Custom Renderers initiative, I was able to work full-time for a bit on this (thanks again to my employer, Mainmatter for allowing me to do this).

This, the fact that we recently revisited the direction we were going (that lead to much less code needed), plus the fact that Claude now is decently good at navigating the Svelte codebase allowed me to do a lot of progress (I was also able to re-use part of the code I already had before).

As you can see, this is a big PR, but I tried to split the commits reasonably so that the review process shouldn't be too bad and there wasn't really a way to verify it worked before having built most of it. There are still a few To-dos but luckily, I also have a few more days to work on this (and at this point is in a place where I can also do it in my spare time).

To-dos

• Documentation
• Lift HTML-specific compiler warnings/errors if a custom renderer is defined
• Write more tests
• (Stretch) figure out if there's a way to use part of the huge test suite for the custom renderers too
• (Stretch) figure out if there's a way to lint the DOM access in the runtime code

How it works

experimental.customRenderer is a new compile configuration option. It can be a string or a function that accepts the filename and returns a string. The value should be an NPM package or a module that exports the renderer as its default export. When this option is defined, the compilation output changes a bit (no delegated events, no inlining of node.nodeValue="", no customizable select, etc...basically we're doing a lot of optimization that are specific to the DOM which are skipped).

The compilation also changes because now the compiled component imports the module you specify, uses from_tree instead of from_html, push the renderer at the beginning of the component and pop it at the end...basically this

<p>hello</p>

gets compiled to

import * as $ from 'svelte/internal/client';
import $renderer from 'your-custom-renderer';

var root = $.from_tree([['p', null, 'hello']]);

export default function Main($$anchor) {
	var $$pop_renderer = $.push_renderer($renderer);
	var p = root();

	$.append($$anchor, p);
	$$pop_renderer();
}

What does a custom renderer looks like? You can have a look at the one I created for testing in packages/svelte/tests/custom-renderers/renderer.js to have a more practical example but basically, you can import createRenderer from svelte/renderer and then specify a series of DOM-like operations in your "world".

import { createRenderer } from 'svelte/renderer';

const renderer = createRenderer({
	createFragment() {},
	createElement(name) {},
	createTextNode(data) {},
	createComment(data) {},
	nodeType(node) {},
	getNodeValue(node) {},
	getAttribute(el, name) {},
	setAttribute(el, key, value) {},
	removeAttribute(el, name) {},
	hasAttribute(el, name) {},
	setText(node, text) {},
	getFirstChild(el) {},
	getLastChild(el) {},
	getNextSibling(node) {},
	insert(parent, node, anchor) {},
	remove(node) {},
	getParent(node) {},
	addEventListener(target, type, handler, options) {},
	removeEventListener(target, type, handler, options) {}
});

You can then use the return value to "mount" your component

const root = renderer.createFragment();

const unmount = renderer.render(MyComponent, {
	target: root,
	props: {
		/* ... */
	},
	context: new Map()
});

A good custom renderer is crucial to make svelte works properly so we will need to document this correctly (even though I don't expect people to create custom renderers in their day to day and the Svelte team will likely be the primary user of this API).

A few examples of this:

• insert assumes that the insertion works like the DOM: if you insert something that already has a parent it should be removed from where it is.
• insert-ing a fragment means inserting all the children of the fragment in the parent.
• If your system doesn't have the concept of a parent/child you will need to keep track of the relationship yourself
• a comment or a fragment can literally just be objects you tuck information to (in case your system doesn't have those concepts

Limits

A few features of Svelte are designed specifically for the DOM and thus are disabled if you try to compile a component with a custom renderer:

• bind: on regular elements is forbidden, since svelte register known DOM events to keep the variables in sync.
• transition:, animate:, in: and out: are forbidden, since, once again, those use DOM manipulation under the hood.
• svelte:window, svelte:body, svelte:document, svelte:head ... I mean, do I really need to explain why this is forbidden?
• css: injected is also forbidden since it appends the style tag to the document
• createRawSnippet throws a runtime error since it relies on the template tag to generate the HTML elements from the string you return
• You can't hydrate a custom renderer compiled component (because in most cases it doesn't make sense since there's no SSR)

Another quirk is that you can technically interleave components compiled with different renderers (imagine a DOM component into a Threlte one) but:

• it requires a bit of manual handling (the custom renderer need to have a before function on the comment that will receive the fragment/element/text that the component is trying to "mount")
• Currently is not possible to @render a snippet compiled with a different renderer from the one that is invoking @render. This means if I'm mounting a DOM component into a Threlte component I can't pass a snippet (unless that snippet is exported from a component compiled without a renderer and imported into the Threlte component)

These limitations might change before we merge if we find a way to make them work.

What this PR does?

The main job of this PR is to centralize every DOM operation in operations.js as an exported function. This allows the function to check if a renderer is available so that it can call the method on the renderer instead of the DOM method. The renderer is also captured in every effect created in the component, since it needs to be "pushed" again before the effect execute. The same is true for boundaries, batches and each blocks.

I've also added a somewhat decent test suite that uses a render-to-object renderer that renders the svelte components to...well...an object. This allows the tests to be "similar" to the rest of the test suite (there's even an object-to-HTML string helper to assert the shape of the component) but is executed in a node environment, so every access to DOM API will actually throw.

I've changed some of the validation in place, but there's still a few warnings and errors that don't make sense, which I plan to fix before merging.

A few questions

• Right now, there are some places that are guaranteed to never be touched by the custom renderers paths (either because it's behind a hydration flag or because it's part of a feature that is forbidden at compile time). I didn't touch the DOM access in those part of the codebase. The advantage of this is that the diff is smaller and is much more clear what the intent is. The disadvantage is that now we don't have a clear rule of "never access the DOM in the runtime folder".
• Right now, Typescript is a big fat lie in the whole codebase: we always assume what we are dealing with is a Node/HTMLElement, but in reality it could be anything by the moment we drop the custom renderers API. Changing the types to be object could help us with the maintainability of the custom renderers API (now Typescript will yell at us if we try to access element.value without checking)...but it could make the maintainability of DOM Svelte a nightmare (because now you have to check everything and everywhere). Should we keep it a lie?
• We technically could produce shorter compiled code with custom renderers (there are a few methods that literally do nothing and bail immediately if there's a custom renderer). However, that would mean a more messy (and thus less maintainable) compiler code... I would say having the same output weights more than a few bytes of compiler output.

Extra

To test this out, I (admittedly Claude) built an opentui custom renderer to render svelte component to the terminal...here's a small preview.