Skip to content

feat(react): route element-template background tree via multi-slot #2651

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
upupming wants to merge 12 commits into
base: main
Choose a base branch
from
Open

feat(react): route element-template background tree via multi-slot #2651

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
9d0d09c
feat(react): route element-template background tree via multi-slot
upupming May 16, 2026
72db348
test(react): update element-template fixtures for multi-slot output
upupming May 16, 2026
24dec8f
test(react): fix mockNativePapi schema + drop ET internal import asse…
upupming May 16, 2026
c8e4d49
test(react): cover legacy paths + drop unreachable post-multi-slot br…
upupming May 16, 2026
9563659
refactor(react): drop BackgroundElementTemplateSlot legacy path
upupming May 18, 2026
f1d5971
test(react): drop placeholder hack from hydrate fixtures
upupming May 18, 2026
99a30b4
chore: drop public package bump from ET multi-slot changeset
upupming May 18, 2026
b295b6e
fix(react): keep ET sibling chain in lock-step with cross-slot append…
upupming May 18, 2026
1c9d75c
fix(react): clean source slot when ET child moves between slots + tig…
upupming May 18, 2026
ebdef8f
test(react): restore children.iterates-existing-slots and make it mea…
upupming May 18, 2026
55b44d9
refactor(react): simplify ET multi-slot $N collection to mirror snaps…
upupming May 18, 2026
3fb1c6b
test(react): add Preact-driven cross-slot move test for the removeChi…
upupming May 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/et-multi-slots.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---

---

No package release is required because this change continues the unpublished Element Template runtime path behind the experimental `experimental_useElementTemplate` flag. The SWC `swc_plugin_element_template` lowering now emits `$0`, `$1`, ... named-slot JSX props instead of `__etSlot(N, ...)` wrapper calls, the background runtime routes inserts/removes off `child.__slotIndex` directly, and the legacy `BackgroundElementTemplateSlot` wrapper + `__etSlot` runtime component are removed. Only internal runtime, transform, fixtures, and tests change — public APIs, package exports, and release-facing defaults are unchanged.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
6 changes: 1 addition & 5 deletions packages/react/runtime/__test__/element-template/fixtures/background/instance/_shared.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,7 @@ import {
markElementTemplateHydrated,
resetElementTemplateCommitState,
} from '../../../../../src/element-template/background/commit-hook.js';
import {
BackgroundElementTemplateInstance,
BackgroundElementTemplateSlot,
} from '../../../../../src/element-template/background/instance.js';
import { BackgroundElementTemplateInstance } from '../../../../../src/element-template/background/instance.js';
import { backgroundElementTemplateInstanceManager } from '../../../../../src/element-template/background/manager.js';

export function runCase<T>(runner: () => T): T {
Expand All @@ -27,7 +24,6 @@ export function runCase<T>(runner: () => T): T {

export {
BackgroundElementTemplateInstance,
BackgroundElementTemplateSlot,
globalCommitContext,
markElementTemplateHydrated,
resetGlobalCommitContext,
Expand Down
12 changes: 2 additions & 10 deletions ..._/element-template/fixtures/background/instance/ops/supports-silent-insert-before/case.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,11 @@
import {
BackgroundElementTemplateInstance,
BackgroundElementTemplateSlot,
globalCommitContext,
runCase,
} from '../../_shared.js';
import { BackgroundElementTemplateInstance, globalCommitContext, runCase } from '../../_shared.js';

export function run() {
return runCase(() => {
const root = new BackgroundElementTemplateInstance('root');
const slot = new BackgroundElementTemplateSlot();
slot.setAttribute('id', 0);
root.appendChild(slot);

const child = new BackgroundElementTemplateInstance('view');
slot.insertBefore(child, null, true);
root.insertBefore(child, null, true);

return globalCommitContext.ops;
});
Expand Down
18 changes: 6 additions & 12 deletions ...lement-template/fixtures/background/render/supports-slot-component-materiality/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,12 @@
Object {
"tree": "<root>
<_et_a94a8_test_3>
<slot id=0>
<_et_a94a8_test_2>
<slot id=0>
<_et_a94a8_test_4 />
</slot>
</_et_a94a8_test_2>
<_et_a94a8_test_2>
<slot id=0>
<_et_a94a8_test_5 />
</slot>
</_et_a94a8_test_2>
</slot>
<_et_a94a8_test_2>
<_et_a94a8_test_4 />
</_et_a94a8_test_2>
<_et_a94a8_test_2>
<_et_a94a8_test_5 />
</_et_a94a8_test_2>
</_et_a94a8_test_3>
</root>
",
Expand Down
4 changes: 2 additions & 2 deletions .../fixtures/hydrate/background-hydrate-compiled/children.creates-and-inserts-new/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
Object {
"stream": Array [
1,
4,
3,
"_et_77307_test_2",
null,
Array [],
Array [],
3,
-1,
0,
4,
3,
0,
],
}
4 changes: 2 additions & 2 deletions ...s/hydrate/background-hydrate-compiled/children.inserts-before-existing-sibling/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
Object {
"stream": Array [
1,
4,
3,
"_et_f9aab_test_2",
null,
Array [],
Array [],
3,
-3,
0,
4,
3,
-1,
],
}
4 changes: 2 additions & 2 deletions ...emplate/fixtures/hydrate/background-hydrate-compiled/children.mixed-operations/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ Object {
-1,
],
1,
5,
4,
"_et_04991_test_3",
null,
Array [],
Array [],
3,
-3,
0,
5,
4,
0,
],
}
4 changes: 2 additions & 2 deletions ...s/hydrate/background-hydrate-compiled/children.non-string-raw-text-key-on-main/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Object {
"stream": Array [
1,
4,
3,
"_et_builtin_raw_text",
null,
Array [
Expand All @@ -11,7 +11,7 @@ Object {
3,
-2,
0,
4,
3,
0,
],
}
4 changes: 2 additions & 2 deletions ...ydrate/background-hydrate-compiled/complex-trees.deeply-nested-dynamic-content/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@ Object {
0,
"BG",
1,
10,
7,
"_et_c2579_test_5",
null,
Array [],
Array [],
3,
-4,
0,
10,
7,
0,
],
}
59 changes: 19 additions & 40 deletions ...s/react/runtime/__test__/element-template/fixtures/hydrate/background-hydrate/_shared.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ import {
import '../../../../../src/element-template/native/index.js';
import {
BackgroundElementTemplateInstance,
BackgroundElementTemplateSlot,
BUILTIN_RAW_TEXT_TEMPLATE_KEY,
} from '../../../../../src/element-template/background/instance.js';
import { backgroundElementTemplateInstanceManager } from '../../../../../src/element-template/background/manager.js';
Expand Down Expand Up @@ -378,11 +377,8 @@ export function runCaseByName(name: string): unknown {
backgroundElementTemplateInstanceManager.nextId = 0;

const rootInstance = new BackgroundElementTemplateInstance('root');
const slot0 = new BackgroundElementTemplateSlot();
slot0.setAttribute('id', 0);
const child = new BackgroundElementTemplateInstance('child');
slot0.appendChild(child);
rootInstance.appendChild(slot0);
rootInstance.appendChild(child);

const before = createHydrationTemplate(-1, 'root');
const stream = hydrateBackground(before, rootInstance);
Expand Down Expand Up @@ -410,21 +406,15 @@ export function runCaseByName(name: string): unknown {
backgroundElementTemplateInstanceManager.nextId = 0;

const rootInstance = new BackgroundElementTemplateInstance('root');
const slot0 = new BackgroundElementTemplateSlot();
slot0.setAttribute('id', 0);
rootInstance.appendChild(slot0);

const existing = new BackgroundElementTemplateInstance('existing');
slot0.appendChild(existing);
rootInstance.appendChild(existing);

const card = new BackgroundElementTemplateInstance('card');
card.setAttribute('attributeSlots', [{ id: 'card' }]);
const cardSlot = new BackgroundElementTemplateSlot();
cardSlot.setAttribute('id', 0);
const text = createTextNode('NEW');
cardSlot.appendChild(text);
card.appendChild(cardSlot);
slot0.insertBefore(card, existing);
card.appendChild(text);
rootInstance.insertBefore(card, existing);

const beforeExisting = createHydrationChild(-2, 'existing');
const beforeRemoved = createHydrationChild(-3, 'removed');
Expand All @@ -443,11 +433,8 @@ export function runCaseByName(name: string): unknown {
backgroundElementTemplateInstanceManager.nextId = 0;

const rootInstance = new BackgroundElementTemplateInstance('root');
const slot0 = new BackgroundElementTemplateSlot();
slot0.setAttribute('id', 0);
rootInstance.appendChild(slot0);
const rawText = createTextNode('');
slot0.appendChild(rawText);
rootInstance.appendChild(rawText);

const before = createHydrationTemplate(-1, 'root', {
elementSlots: [[createHydrationRawTextChild(3, '')]],
Expand All @@ -467,14 +454,11 @@ export function runCaseByName(name: string): unknown {
backgroundElementTemplateInstanceManager.nextId = 0;

const rootInstance = new BackgroundElementTemplateInstance('root');
const slot0 = new BackgroundElementTemplateSlot();
slot0.setAttribute('id', 0);
rootInstance.appendChild(slot0);

const rawTextText = createTextNode('bg');
const rawTextInstance = new BackgroundElementTemplateInstance(BUILTIN_RAW_TEXT_TEMPLATE_KEY);
slot0.appendChild(rawTextText);
slot0.appendChild(rawTextInstance);
rootInstance.appendChild(rawTextText);
rootInstance.appendChild(rawTextInstance);

const beforeExistingString = createHydrationRawTextChild(rawTextText.instanceId, 'bg');
const beforeExistingNonString = createHydrationRawTextChild(rawTextInstance.instanceId, 123);
Expand All @@ -500,15 +484,16 @@ export function runCaseByName(name: string): unknown {
backgroundElementTemplateInstanceManager.clear();
backgroundElementTemplateInstanceManager.nextId = 0;

// Background side has children at slot 1 but serialized side only ships
// slot 0. `slotCount = Math.max(serialized.length, instance.length)` must
// visit slot 1 too so the background-only child gets reported as an
// insertion to the main thread.
const rootInstance = new BackgroundElementTemplateInstance('root');
const slot0 = new BackgroundElementTemplateSlot();
slot0.setAttribute('id', 0);
rootInstance.appendChild(slot0);
const slot1 = new BackgroundElementTemplateSlot();
slot1.setAttribute('id', 1);
Copy link
Copy Markdown
Collaborator

@Yradex Yradex May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This fixture name looks stale now. The setup no longer creates any existing background slot entry, so it is not really testing “existing slots” anymore. Can we either rename it or materialize an actual empty/sparse background slot?

Copy link
Copy Markdown
Collaborator Author

@upupming upupming May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Renamed in 1c9d75c to children.no-op-when-both-sides-have-empty-slots. The setup matches the new name — rootInstance.elementSlots starts empty, serialized side ships [[], []], and the assertion verifies the hydrate loop iterates both empty arrays without emitting anything. Fixture directory and runCaseByName(...) reference were updated together.

Copy link
Copy Markdown
Collaborator Author

@upupming upupming May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following up — after the rename @upupming noticed offline that the renamed case was now functionally identical to children.missing-attrs-element (both ended up as trivial no-ops once the slot-wrapper materialization was removed). Reverted the rename in ebdef8f and instead made the test actually exercise the Math.max(serializedLen, instanceLen) branch in hydrate.ts:

const rootInstance = new BackgroundElementTemplateInstance('root');
const slot1Child = new BackgroundElementTemplateInstance('child');
slot1Child.__slotIndex = 1;
rootInstance.appendChild(slot1Child);

const before = createHydrationTemplate(-1, 'root', { elementSlots: [[]] });

Background side has a child at slot 1, serialized only ships slot 0. The hydrate loop now visits slot 1 (background-only) and emits an insertion for the background-only child:

stream: [
  1, 2, "child", null, [], [],   // createTemplate
  3, -1, 1, 2, 0,                // insertNode(parent=-1, slot=1, child=2, beforeId=0)
]

Original name preserved, semantic now matches it.

rootInstance.appendChild(slot1);

const before = createHydrationTemplate(-1, 'root', { elementSlots: [[], []] });
const slot1Child = new BackgroundElementTemplateInstance('child');
slot1Child.__slotIndex = 1;
rootInstance.appendChild(slot1Child);

const before = createHydrationTemplate(-1, 'root', { elementSlots: [[]] });
const stream = hydrateBackground(before, rootInstance);
return { stream };
});
Expand All @@ -520,9 +505,6 @@ export function runCaseByName(name: string): unknown {
backgroundElementTemplateInstanceManager.nextId = 0;

const rootInstance = new BackgroundElementTemplateInstance('root');
const slot0 = new BackgroundElementTemplateSlot();
slot0.setAttribute('id', 0);
rootInstance.appendChild(slot0);

const before = createHydrationTemplate(-1, 'root', { elementSlots: [[]] });
const stream = hydrateBackground(before, rootInstance);
Expand All @@ -536,16 +518,13 @@ export function runCaseByName(name: string): unknown {
backgroundElementTemplateInstanceManager.nextId = 0;

const rootInstance = new BackgroundElementTemplateInstance('root');
const slot0 = new BackgroundElementTemplateSlot();
slot0.setAttribute('id', 0);
rootInstance.appendChild(slot0);

const childA = new BackgroundElementTemplateInstance('a');
const childB = new BackgroundElementTemplateInstance('b');
const childC = new BackgroundElementTemplateInstance('c');
slot0.appendChild(childB);
slot0.appendChild(childA);
slot0.appendChild(childC);
rootInstance.appendChild(childB);
rootInstance.appendChild(childA);
rootInstance.appendChild(childC);

const beforeChildA = createHydrationChild(childA.instanceId, 'a');
const beforeChildB = createHydrationChild(childB.instanceId, 'b');
Expand Down
8 changes: 4 additions & 4 deletions ...fixtures/hydrate/background-hydrate/children.creates-missing-nodes-recursively/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
Object {
"stream": Array [
1,
6,
4,
"_et_builtin_raw_text",
null,
Array [
"NEW",
],
Array [],
1,
4,
3,
"card",
null,
Array [
Expand All @@ -19,13 +19,13 @@ Object {
],
Array [
Array [
6,
4,
],
],
3,
-1,
0,
4,
3,
-2,
4,
-1,
Expand Down
14 changes: 13 additions & 1 deletion ...-template/fixtures/hydrate/background-hydrate/children.iterates-existing-slots/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
Object {
"stream": Array [],
"stream": Array [
1,
2,
"child",
null,
Array [],
Array [],
3,
-1,
1,
2,
0,
],
}
4 changes: 2 additions & 2 deletions ...plate/fixtures/hydrate/background-hydrate/children.missing-slot-record-on-main/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
Object {
"stream": Array [
1,
3,
2,
"child",
null,
Array [],
Array [],
3,
-1,
0,
3,
2,
0,
],
}
4 changes: 2 additions & 2 deletions ...lement-template/fixtures/hydrate/background-hydrate/coverage.move-before-child/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Object {
3,
1,
0,
3,
5,
2,
4,
],
}
2 changes: 1 addition & 1 deletion ...nt-template/fixtures/hydrate/background-hydrate/coverage.raw-text-key-branches/output.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Object {
"stream": Array [
2,
4,
3,
0,
null,
4,
Expand Down
4 changes: 2 additions & 2 deletions ...t__/element-template/fixtures/patch-compiled/applies-insert-before-with-reference/ops.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
Array [
1,
4,
3,
"_et_3634f_test_1",
null,
Array [],
Array [],
3,
-3,
0,
4,
3,
-1,
]
Loading
Loading