svelte

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 [x] 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 is a new compile configuration option. It can be a or a function that accepts the filename and returns a . 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 , 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 instead of , push the renderer at the beginning of the component and pop it at the end...basically this gets compiled to What does a custom renderer looks like? You can have a look at the one I created for testing in to have a more practical example but basically, you can import from and then specify a series of DOM-like operations in your "world". You can then use the return value to "mount" your component 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: 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. 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: on regular elements is forbidden, since svelte register known DOM events to keep the variables in sync. , , and are forbidden, since, once again, those use DOM manipulation under the hood. , , , ... I mean, do I really need to explain why this is forbidden? is also forbidden since it appends the tag to the document throws a runtime error since it relies on the 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 function on the comment that will receive the fragment/element/text that the component is trying to "mount") Currently is not possible to a snippet compiled with a different renderer from the one that is invoking . 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 as an exported function. This allows the function to check if a 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 could help us with the maintainability of the custom renderers API (now Typescript will yell at us if we try to access 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. https://github.com/user-attachments/assets/92768602-6234-4cd9-a6d9-eb11bf4bc1a1

Summary Add a short cross-link section on the page pointing to for script-side debugging Add the matching section on the page pointing to for template debugging Fixes #15498 Test plan [ ] Confirm the new sections render on both docs pages [ ] Confirm the cross-links resolve to the expected pages

This PR changes how the async reactivity system works when async work overlaps. Previously, we tried to record the current/previous values of each batch, so that each batch runs with the values it "can see" (meaning updates from other batches are held back in the context of that batch). On commit we "rebase" the other batches and rerun block/async effects where necessary. While the idea is somewhat straightforward around batch values, the rebasing part was always a headache and bug magnet. We needed to find overlapping async/block effects to eagerly rerun them, and we also needed to keep track of new effects because we might need to rerun them once another batch commits. Additionally, we kept deriveds as (maybe)dirty while multiple batches existed so that we could always traverse the tree and get the correct value, which overfires. This PR changes how it works. Instead, we now "entangle" (or merge) batches whenever we see that their reactive graphs overlap. This is straightforward by recording for each signal which batch has last touched it (render effects are exempt else too much would entangle). If there's already a batch on that signal that is not finished yet, these two batches will merge and become one unit, i.e. resolve together. I was hoping that this would reduce the overall code size, and this change alone would, but there are two things making it bigger in the end (though a lot of it is comments): First, we need to handle promise starvation: Async work could be repeatedly scheduled, always merging with an existing batch, and so the UI would never update. To battle this, there's a mechanism that after a certain amount of merges containing async work, we put any new work in a property, which is only processed once the existing batch is done. Since stale UI could happen either way (see #18524) we could also be more pragmatic here and just flush at some point, even if it results in possibly weird UI - so that could get the code size down again if we agree on a simpler solution. Second, we need to handle forking, which of course cannot entangle. So in addition to the merging logic we still need overlay logic to keep the world separate from each other. Since the "real world" always entangles now the overlay looks a bit different compared to main. It also fixes a lot of bugs that were discovered during working on this, so I assume that if we were to fix this in the existing system we would also have to add a bunch more code. I also benchmarked this and it's either faster or only a tiny bit slower than main, depending on the benchmark. It's definitely faster than #18035. What I didn't get to yet but would like to do (or someone else), is to check which of the existing issues in the Svelte repo are also fixed through this, so we know this is all worth it and not just shifting buggyness from one place to the other. Some I checked so far: Fixes #18355 Fixes #18624 Fixes #18503 Fixes https://github.com/sveltejs/kit/issues/15067 this playground which exists in one of my thousand tabs and I'm not sure which issue (if any) this is related to Closes #18363 (because we don't have the invariant anymore) ... We should also take this for a test drive in SvelteKit with navigation + forking to see if it stabilizes things there.