ripple 0.3.125 → 0.3.126

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # ripple
 
+## 0.3.126
+
+### Patch Changes
+
+- [#1441](https://github.com/Ripple-TS/ripple/pull/1441)
+  [`2404ad4`](https://github.com/Ripple-TS/ripple/commit/2404ad4a4fcca21a1887bab25bb94671698f0c9d)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Implement sibling-scoped
+  `<style>` blocks, `$class`, and `apply`
+  ([TSRX RFC #1](https://github.com/tsrx-org/RFCs/discussions/1)) for the Ripple
+  target.
+
+  - A `<style>` block is scoped to its siblings: it styles the items beside it and
+    everything below them, never the element that contains it. Blocks among the
+    same children share one hash and one stylesheet; nested children lists that
+    hold blocks are nested scopes, and every element carries the hash of each
+    enclosing scope, outer first. Control-flow branches and templates assigned to
+    variables host scopes too.
+  - Assigning a block to a variable exposes `$class`. Exported, applied, or
+    `$class`-read blocks are themes that keep every selector; other assigned
+    blocks stay class maps. `<style apply={theme} />` attaches a theme to a whole
+    scope, `<style apply={theme}>…</style>` applies and declares in one tag,
+    arrays apply several themes, and a theme may apply other themes. Same-module
+    themes inline as literals; imported themes are read through `theme.$class` at
+    runtime.
+  - CSS is emitted in lexical order (an applied theme before the block that
+    applies it, a scope's blocks together, nested scopes after their parent). On
+    the server a render registers the sheets it needs in that order, class-map
+    reads register their own sheet, and reading `theme.$class` outside a render no
+    longer throws.
+  - The style diagnostics of the RFC (`tsrx-style-*` codes) are reported, and
+    type-only output verifies `apply` targets through a `$class` read.
+  - Fixed: a `@{ … }` block rendered as the child of a DOM element on the client
+    was dropped; it now renders in place. The `#class` spread attribute accepts
+    several class tokens.
+
+  Raw CSS in a `<style>` inside a plain function that returns JSX is now an error
+  (`tsrx-style-standalone-outside-template`): use a `@{ … }` body, or
+  `<style>{css}</style>`. Elements are stamped with the scope class after their
+  authored classes, and every element of a scope carries it, not only those a
+  selector matches.
+
+- Updated dependencies
+  [[`2404ad4`](https://github.com/Ripple-TS/ripple/commit/2404ad4a4fcca21a1887bab25bb94671698f0c9d)]:
+  - @tsrx/ripple@0.1.63
+
 ## 0.3.125
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.125",
+  "version": "0.3.126",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -73,8 +73,8 @@
     "clsx": "^2.1.1",
     "devalue": "^5.8.1",
     "esm-env": "^1.2.2",
-    "@tsrx/core": "^0.1.61",
-    "@tsrx/ripple": "0.1.62"
+    "@tsrx/core": "^0.1.67",
+    "@tsrx/ripple": "0.1.63"
   },
   "devDependencies": {
     "@types/estree": "^1.0.8",

package/src/runtime/internal/client/render.js

@@ -140,8 +140,9 @@ function set_attribute_helper(element, key, value, remove_listeners, prev) {
 	} else if (key === 'style') {
 		set_style(element, value, prev.style);
 	} else if (key === '#class') {
-		// Special case for static class when spreading props
-		element.classList.add(value);
+		// Special case for the scope classes of an element that spreads props:
+		// one token per scope hash and applied theme.
+		element.classList.add(...String(value).split(' ').filter(Boolean));
 	} else if (typeof key === 'string' && is_event_attribute(key)) {
 		// Handle event handlers in spread props
 		if (remove_listeners[key]) {

package/src/runtime/internal/server/index.js

@@ -1252,7 +1252,12 @@ export function set_output_target(target) {
  * @returns {void}
  */
 export function output_register_css(hash) {
-	/** @type {Block} */ (active_block).o.register_css(hash);
+	// A style class map is read wherever its value is used, including outside
+	// a render (a module-level `theme.$class` read); only a render has a
+	// request to register the CSS with.
+	if (active_block !== null) {
+		active_block.o.register_css(hash);
+	}
 }
 
 /**

package/tests/client/basic/basic.styling.test.tsrx

@@ -2,8 +2,8 @@ import { compile } from '@tsrx/ripple';
 
 describe('basic client > styling', () => {
 	it('renders with styling scoped to component', () => {
-		function Basic() {
-			return <>
+		function Basic() @{
+			<>
 				<div class="styled-container">
 					<h1>{'Styled heading'}</h1>
 					<p class="text">{'Styled paragraph'}</p>
@@ -24,7 +24,7 @@ describe('basic client > styling', () => {
 						font-size: 14px;
 					}
 				</style>
-			</>;
+			</>
 		}
 
 		render(Basic);

package/tests/client/css/scoped-styles.test.tsrx

@@ -0,0 +1,652 @@
+import { track, flushSync } from 'ripple';
+import { compile } from '@tsrx/ripple';
+import {
+	base as importedBase,
+	theme as importedTheme,
+} from '../../fixtures/scoped-styles/theme.tsrx';
+
+// RFC tsrx-org/RFCs#1: a `<style>` block is scoped to its siblings — it styles
+// the items beside it and everything below them, never the element that
+// contains it. Sibling blocks share one hash, nested children lists that hold
+// blocks are nested scopes, assigned blocks expose `$class`, and `apply`
+// attaches a theme to a whole scope.
+
+function hashes(element: Element | null): string[] {
+	return Array.from(element?.classList ?? []).filter((cls) => cls.startsWith('tsrx-'));
+}
+
+function tokens(value: string): string[] {
+	return value.split(' ').filter(Boolean);
+}
+
+const one = <style>
+	div {
+		color: red;
+	}
+	.one {
+		margin: 0;
+	}
+</style>;
+
+const two = <style>
+	div {
+		color: blue;
+	}
+</style>;
+
+const localBase = <style>
+	p {
+		margin: 0;
+	}
+</style>;
+
+const accent = <style apply={localBase}>
+	p {
+		color: purple;
+	}
+</style>;
+
+const bundle = <style apply={[two, accent]} />;
+
+describe('sibling-scoped style blocks', () => {
+	it('styles the items beside a block and everything below them, never the container', () => {
+		function Status() @{
+			let &[ready] = track(false);
+			<>
+				<button onClick={() => (ready = !ready)}>{'toggle'}</button>
+				<style>
+					.status {
+						padding: 0.5rem;
+					}
+				</style>
+				<section id="status" class="status">
+					<style>
+						.title {
+							font-weight: 700;
+						}
+						.status {
+							color: rgb(9, 9, 9);
+						}
+					</style>
+					<h2 id="title" class="title">{'Status'}</h2>
+					@if (ready) {
+						<>
+							<style>
+								.ok {
+									color: green;
+								}
+							</style>
+							<p id="ok" class="ok">{'Ready'}</p>
+						</>
+					} @else {
+						<>
+							<style>
+								.wait {
+									color: gray;
+								}
+							</style>
+							<p id="wait" class="wait">{'Waiting'}</p>
+						</>
+					}
+				</section>
+			</>
+		}
+
+		render(Status);
+
+		const section = container.querySelector('#status');
+		const title = container.querySelector('#title');
+		const wait = container.querySelector('#wait');
+
+		const [A] = hashes(section);
+		expect(A).toBeTruthy();
+		// The section carries only the fragment's scope: the block written
+		// inside it styles its children, not the section. The button is a
+		// sibling of the block too.
+		expect(hashes(section)).toEqual([A]);
+		expect(hashes(container.querySelector('button'))).toEqual([A]);
+		const B = hashes(title)[1];
+		expect(hashes(title)).toEqual([A, B]);
+		const D = hashes(wait)[2];
+		expect(hashes(wait)).toEqual([A, B, D]);
+		expect(new Set([A, B, D]).size).toBe(3);
+		expect(container.querySelector('#ok')).toBeNull();
+
+		container.querySelector('button')?.click();
+		flushSync();
+
+		const ok = container.querySelector('#ok');
+		const C = hashes(ok)[2];
+		expect(hashes(ok)).toEqual([A, B, C]);
+		expect([A, B, D]).not.toContain(C);
+		expect(container.querySelector('#wait')).toBeNull();
+		expect(hashes(container.querySelector('#status'))).toEqual([A]);
+	});
+
+	it('prunes a rule that only matches the container and emits the scopes in source order', () => {
+		const source = `
+export function Status({ ready }: { ready: boolean }) @{
+	<>
+		<style>.status { padding: 0.5rem; }</style>
+		<section class="status">
+			<style>
+				.title { font-weight: 700; }
+				.status { color: rgb(9, 9, 9); }
+			</style>
+			<h2 class="title">{'Status'}</h2>
+			@if (ready) {
+				<>
+					<style>.ok { color: green; }</style>
+					<p class="ok">{'Ready'}</p>
+				</>
+			} @else {
+				<>
+					<style>.wait { color: gray; }</style>
+					<p class="wait">{'Waiting'}</p>
+				</>
+			}
+		</section>
+	</>
+}`;
+		const { css, cssHash } = compile(source, 'test.tsrx');
+		const [A, B, C, D] = cssHash!.split(' ');
+		expect(new Set([A, B, C, D]).size).toBe(4);
+		expect(css).toContain(`.status.${A} { padding: 0.5rem; }`);
+		expect(css).toContain(`.title.${B} { font-weight: 700; }`);
+		expect(css).toContain('/* (unused) .status { color: rgb(9, 9, 9); }*/');
+		expect(css).not.toContain(`.status.${B}`);
+		expect(css).toContain(`.ok.${C}`);
+		expect(css).toContain(`.wait.${D}`);
+		expect(css.indexOf(`.status.${A}`)).toBeLessThan(css.indexOf(`.title.${B}`));
+		expect(css.indexOf(`.title.${B}`)).toBeLessThan(css.indexOf(`.ok.${C}`));
+		expect(css.indexOf(`.ok.${C}`)).toBeLessThan(css.indexOf(`.wait.${D}`));
+	});
+
+	it(
+		'shares one hash between the blocks of one children list, and none with the enclosing list',
+		() => {
+			function Two() @{
+				<>
+					<style>
+						.host {
+							margin: 0;
+						}
+					</style>
+					<div id="host" class="host">
+						<style>
+							.a {
+								color: red;
+							}
+						</style>
+						<i class="a">{'a'}</i>
+						<style>
+							.b {
+								color: blue;
+							}
+						</style>
+						<b class="b">{'b'}</b>
+					</div>
+				</>
+			}
+
+			render(Two);
+
+			const host = container.querySelector('#host');
+			const i = container.querySelector('i');
+			const b = container.querySelector('b');
+			const [H] = hashes(host);
+			expect(hashes(host)).toEqual([H]);
+			const [, C] = hashes(i);
+			expect(C).not.toBe(H);
+			expect(hashes(i)).toEqual([H, C]);
+			expect(hashes(b)).toEqual([H, C]);
+
+			const { css, cssHash } = compile(
+				`export function Two() @{
+	<>
+		<style>.host { margin: 0; }</style>
+		<div class="host">
+			<style>.a { color: red; }</style>
+			<i class="a">{'a'}</i>
+			<style>.b { color: blue; }</style>
+			<b class="b">{'b'}</b>
+		</div>
+	</>
+}`,
+				'test.tsrx',
+			);
+			const [outer, inner] = cssHash!.split(' ');
+			expect(cssHash!.split(' ')).toHaveLength(2);
+			expect(css).toContain(`.host.${outer}`);
+			expect(css).toContain(`.a.${inner}`);
+			expect(css).toContain(`.b.${inner}`);
+		},
+	);
+
+	it('reaches into a nested code block scope, and the nested block never reaches out', () => {
+		function Panel() @{
+			<>
+				<style>
+					div {
+						color: black;
+					}
+				</style>
+				<div id="outer">{'Black'}</div>
+				@{
+					<>
+						<style>
+							div {
+								font-weight: bold;
+							}
+						</style>
+						<div id="inner">{'Black and bold'}</div>
+					</>
+				}
+			</>
+		}
+
+		render(Panel);
+
+		const [A] = hashes(container.querySelector('#outer'));
+		expect(hashes(container.querySelector('#outer'))).toEqual([A]);
+		const inner = hashes(container.querySelector('#inner'));
+		expect(inner).toHaveLength(2);
+		expect(inner[0]).toBe(A);
+		expect(inner[1]).not.toBe(A);
+	});
+
+	it('scopes a block inside a @for branch to the items that branch renders', () => {
+		function List() @{
+			let items = track(['a', 'b']);
+			<>
+				<button onClick={() => (items.value = [])}>{'clear'}</button>
+				<style>
+					li {
+						list-style: none;
+					}
+				</style>
+				<ul>
+					@for (const item of items.value) {
+						<>
+							<style>
+								li {
+									padding: 0.75rem 0;
+								}
+							</style>
+							<li class="item">{item}</li>
+						</>
+					} @empty {
+						<li class="empty">{'none'}</li>
+					}
+				</ul>
+			</>
+		}
+
+		render(List);
+
+		const [first, second] = Array.from(container.querySelectorAll('li.item'));
+		const [A, B] = hashes(first);
+		expect(A).toBeTruthy();
+		expect(B).toBeTruthy();
+		expect(hashes(second)).toEqual([A, B]);
+		expect(hashes(container.querySelector('ul'))).toEqual([A]);
+
+		container.querySelector('button')?.click();
+		flushSync();
+
+		// The `@empty` branch holds no block of its own: only the outer scope.
+		expect(hashes(container.querySelector('li.empty'))).toEqual([A]);
+	});
+
+	it(
+		'keeps the block of an element assigned to a variable, styling its children and not its root',
+		() => {
+			function Templates() @{
+				const card = <div id="root" class="card-root">
+					<style>
+						.text {
+							margin: 0;
+						}
+					</style>
+					<p id="text" class="text">{'card'}</p>
+				</div>;
+				<>
+					{card}
+					<p id="outside">{'outside'}</p>
+				</>
+			}
+
+			render(Templates);
+
+			expect(hashes(container.querySelector('#root'))).toEqual([]);
+			expect(hashes(container.querySelector('#text'))).toHaveLength(1);
+			expect(hashes(container.querySelector('#outside'))).toEqual([]);
+		},
+	);
+
+	it('adds the scope classes of an element that spreads its props, one token per scope', () => {
+		function Button(&{ ...rest }: { id: string; class?: string }) @{
+			<>
+				<style>
+					button {
+						padding: 0;
+					}
+				</style>
+				<div>
+					<style>
+						button {
+							margin: 0;
+						}
+					</style>
+					<button {...rest}>{'b'}</button>
+				</div>
+			</>
+		}
+
+		function App() @{
+			<Button id="btn" class="authored" />
+		}
+
+		render(App);
+
+		const button = container.querySelector('#btn');
+		expect(button?.classList.contains('authored')).toBe(true);
+		expect(hashes(button)).toHaveLength(2);
+		expect(hashes(container.querySelector('div'))).toHaveLength(1);
+	});
+
+	it('keeps the scope classes of a static class when a spread brings its own class', () => {
+		function Card(&{ ...rest }: { class?: string }) @{
+			<>
+				<style apply={importedTheme}>
+					.box {
+						color: red;
+					}
+				</style>
+				<div id="box" class="box" {...rest}>{'x'}</div>
+				<style>
+					.plain {
+						margin: 0;
+					}
+				</style>
+			</>
+		}
+
+		function App() @{
+			<Card class="from-spread" />
+		}
+
+		render(App);
+
+		const box = container.querySelector('#box');
+		const [local] = hashes(box);
+		expect(local).toBeTruthy();
+		expect(hashes(box)).toEqual([local, ...tokens(importedTheme.$class)]);
+		expect(box?.classList.contains('box')).toBe(true);
+	});
+
+	it('keeps the scope classes while a dynamic class value changes', () => {
+		function App() @{
+			let &[active] = track(false);
+			<>
+				<style>
+					.on {
+						color: green;
+					}
+				</style>
+				<button id="toggle" onClick={() => (active = !active)}>{'toggle'}</button>
+				<p id="p" class={active ? 'on' : 'off'}>{'p'}</p>
+			</>
+		}
+
+		render(App);
+
+		const p = container.querySelector('#p');
+		const [A] = hashes(p);
+		expect(A).toBeTruthy();
+		expect(p?.className).toBe(`off ${A}`);
+
+		container.querySelector('#toggle')?.click();
+		flushSync();
+
+		expect(p?.className).toBe(`on ${A}`);
+	});
+});
+
+describe('$class and apply', () => {
+	it('exposes $class on an assigned block and applies it to a whole scope', () => {
+		expect(tokens(one.$class)).toHaveLength(1);
+		expect(one.one).toBe(`${one.$class} one`);
+
+		function SelfClosed() @{
+			<>
+				<style apply={one} />
+				<div id="a1">{'a'}</div>
+				<p id="a2">
+					<span id="a3">{'c'}</span>
+				</p>
+			</>
+		}
+
+		render(SelfClosed);
+
+		for (const id of ['a1', 'a2', 'a3']) {
+			expect(hashes(container.querySelector(`#${id}`))).toEqual(tokens(one.$class));
+		}
+	});
+
+	it('applies a theme and declares the scope block in one tag', () => {
+		function WithBody() @{
+			<>
+				<style apply={one}>
+					.c {
+						margin: 0;
+					}
+				</style>
+				<div id="c1" class="c">{'c'}</div>
+			</>
+		}
+
+		render(WithBody);
+
+		const div = container.querySelector('#c1');
+		const classes = hashes(div);
+		expect(classes).toHaveLength(2);
+		// The scope's own hash comes first, then the applied theme.
+		expect(classes[1]).toBe(one.$class);
+		expect(classes[0]).not.toBe(one.$class);
+		expect(div?.className).toBe(`c ${classes[0]} ${one.$class}`);
+	});
+
+	it('applies several themes with an array and with several blocks', () => {
+		function ArrayForm() @{
+			<>
+				<style apply={[one, two]} />
+				<div id="b1">{'b'}</div>
+			</>
+		}
+
+		function TwoApplies() @{
+			<>
+				<style apply={one} />
+				<style apply={two} />
+				<div id="d1">{'d'}</div>
+			</>
+		}
+
+		render(ArrayForm);
+		expect(hashes(container.querySelector('#b1'))).toEqual([one.$class, two.$class]);
+
+		render(TwoApplies);
+		expect(hashes(container.querySelector('#d1'))).toEqual([one.$class, two.$class]);
+	});
+
+	it('composes themes at their definition and bundles them without CSS of their own', () => {
+		expect(accent.$class).toBe(`${localBase.$class} ${tokens(accent.$class)[1]}`);
+		expect(tokens(accent.$class)).toHaveLength(2);
+		expect(bundle.$class).toBe(`${two.$class} ${accent.$class}`);
+
+		function Composed() @{
+			<>
+				<style apply={accent} />
+				<p id="p">{'composed'}</p>
+			</>
+		}
+
+		render(Composed);
+
+		expect(hashes(container.querySelector('#p'))).toEqual(tokens(accent.$class));
+	});
+
+	it('applies an imported theme through its $class at runtime', () => {
+		expect(importedTheme.$class).toBe(`${importedBase.$class} ${tokens(importedTheme.$class)[1]}`);
+
+		function Card() @{
+			<>
+				<style apply={importedTheme}>
+					h2 {
+						margin: 0;
+					}
+				</style>
+				<article id="card">
+					<h2 id="h2" class={importedTheme.dark}>{'Green, system-ui'}</h2>
+				</article>
+			</>
+		}
+
+		render(Card);
+
+		const card = container.querySelector('#card');
+		const [local] = hashes(card);
+		expect(hashes(card)).toEqual([local, ...tokens(importedTheme.$class)]);
+		expect(container.querySelector('#h2')?.className).toBe(
+			`${importedTheme.dark} ${local} ${importedTheme.$class}`,
+		);
+	});
+
+	it('opts single elements into a theme with $class, including a child through a prop', () => {
+		function Card({ parentClass }: { parentClass: string }) @{
+			<>
+				<style>
+					.local {
+						padding: 0;
+					}
+				</style>
+				<article id="article" class={['local', parentClass]}>
+					<h2 id="h2" class={parentClass}>{'title'}</h2>
+				</article>
+			</>
+		}
+
+		function App() @{
+			const theme = <style>
+				div {
+					color: blue;
+				}
+				.card {
+					color: red;
+				}
+			</style>;
+			<>
+				<Card parentClass={theme.$class} />
+				<div id="opted" class={theme.$class}>{'opted in'}</div>
+				<div id="card" class={theme.card}>{'card'}</div>
+				<p id="untouched">{'untouched'}</p>
+			</>
+		}
+
+		render(App);
+
+		const opted = container.querySelector('#opted');
+		const theme_hash = opted?.className;
+		expect(tokens(theme_hash!)).toHaveLength(1);
+		expect(container.querySelector('#card')?.className).toBe(`${theme_hash} card`);
+		expect(container.querySelector('#untouched')?.className).toBe('');
+
+		const article = container.querySelector('#article');
+		const local = hashes(article).find((cls) => cls !== theme_hash);
+		expect(article?.className).toBe(`local ${theme_hash} ${local}`);
+		expect(container.querySelector('#h2')?.className).toBe(`${theme_hash} ${local}`);
+	});
+
+	it('keeps every selector of a theme and only class selectors of a plain class map', () => {
+		const source = `
+export const theme = <style>
+	div { color: green; }
+	.dark { color: purple; }
+</style>;
+
+const plain = <style>
+	div { color: red; }
+	.card { color: blue; }
+</style>;
+
+const read = <style>
+	span { color: red; }
+</style>;
+
+export function App() @{
+	<>
+		<div class={plain.card}>{'card'}</div>
+		<span class={read.$class}>{'read'}</span>
+	</>
+}`;
+		const { css, code } = compile(source, 'test.tsrx');
+		const [theme_hash, plain_hash, read_hash] = [...css.matchAll(/\.(tsrx-[0-9a-f]+)/g)].map(
+			(match) => match[1],
+		).filter((hash, index, all) => all.indexOf(hash) === index);
+		expect(css).toContain(`div.${theme_hash} { color: green; }`);
+		expect(css).toContain(`.dark.${theme_hash} { color: purple; }`);
+		expect(css).toContain('/* (unused) div { color: red; }*/');
+		expect(css).toContain(`.card.${plain_hash} { color: blue; }`);
+		// Reading `read.$class` makes the block a theme.
+		expect(css).toContain(`span.${read_hash} { color: red; }`);
+		expect(code).toContain(`'$class': '${theme_hash}'`);
+		expect(code).toContain(`'dark': '${theme_hash} dark'`);
+	});
+
+	it(
+		'emits an applied theme before the scope that applies it, and a scope before the scopes nested in it',
+		() => {
+			const source = `
+const theme = <style>
+	div { color: green; }
+</style>;
+
+export function Precedence() @{
+	<>
+		<style apply={theme}>
+			div { color: black; }
+		</style>
+		<div class="outer">{'outer'}</div>
+		@{
+			<>
+				<style>
+					div { color: blue; }
+				</style>
+				<div class="inner">{'inner'}</div>
+			</>
+		}
+		<style>
+			div { font-style: italic; }
+		</style>
+	</>
+}`;
+			const { css, cssHash, code } = compile(source, 'test.tsrx');
+			const [theme_hash, outer, inner] = cssHash!.split(' ');
+			expect(cssHash!.split(' ')).toHaveLength(3);
+			const green = css.indexOf(`div.${theme_hash} { color: green; }`);
+			const black = css.indexOf(`div.${outer} { color: black; }`);
+			const italic = css.indexOf(`div.${outer} { font-style: italic; }`);
+			const blue = css.indexOf(`div.${inner} { color: blue; }`);
+			expect(green).toBeGreaterThanOrEqual(0);
+			expect(green).toBeLessThan(black);
+			// The outer scope's blocks stay one group, even though the second
+			// block is written after the nested scope.
+			expect(black).toBeLessThan(italic);
+			expect(italic).toBeLessThan(blue);
+			expect(code).toContain(`class="outer ${outer} ${theme_hash}"`);
+			expect(code).toContain(`class="inner ${outer} ${inner} ${theme_hash}"`);
+		},
+	);
+});

package/tests/client/dynamic-elements.test.tsrx

@@ -671,7 +671,9 @@ describe('dynamic DOM elements', () => {
 		expect(innerScopes).toHaveLength(1);
 		expect(innerScopes[0]).not.toBe(outerScope);
 
-		expect(innerInnerScopes).toHaveLength(0);
+		// Every element of the child's scope carries the child's hash, and none
+		// of the parent's.
+		expect(innerInnerScopes).toEqual(innerScopes);
 	});
 
 	it('doesn\'t add scoping class to dynamically rendered component', () => {
@@ -708,7 +710,8 @@ describe('dynamic DOM elements', () => {
 		const innerScopes = Array.from(p.classList).filter((c) => c.startsWith('tsrx-'));
 
 		expect(outerScopes).toHaveLength(1);
-		expect(innerScopes).toHaveLength(0);
+		// The child's own scope reaches its <p>; the parent's never does.
+		expect(innerScopes).toEqual(outerScopes);
 	});
 
 	it('handles ref on dynamic element passed through component with reactive props', () => {

package/tests/fixtures/scoped-styles/theme.tsrx

@@ -0,0 +1,20 @@
+// A theme module shared by the scoped-style tests: `base` is applied by
+// `theme`, so `theme.$class` carries both hashes and `theme` keeps every
+// selector (it is exported).
+export const base = <style>
+	article {
+		font-family: system-ui;
+	}
+	.muted {
+		color: gray;
+	}
+</style>;
+
+export const theme = <style apply={base}>
+	article {
+		color: green;
+	}
+	.dark {
+		color: purple;
+	}
+</style>;

package/tests/server/dynamic-elements.test.tsrx

@@ -398,7 +398,9 @@ describe('server dynamic DOM elements', () => {
 		expect(innerScopes).toHaveLength(1);
 		expect(innerScopes[0]).not.toBe(outerScope);
 
-		expect(innerInnerScopes).toHaveLength(0);
+		// Every element of the child's scope carries the child's hash, and none
+		// of the parent's.
+		expect(innerInnerScopes).toEqual(innerScopes);
 	});
 
 	it('doesn\'t add scoping class to dynamically rendered component', async () => {
@@ -437,6 +439,7 @@ describe('server dynamic DOM elements', () => {
 		const innerScopes = Array.from(p.classList).filter((c) => c.startsWith('tsrx-'));
 
 		expect(outerScopes).toHaveLength(1);
-		expect(innerScopes).toHaveLength(0);
+		// The child's own scope reaches its <p>; the parent's never does.
+		expect(innerScopes).toEqual(outerScopes);
 	});
 });

package/tests/server/scoped-styles.test.tsrx

@@ -0,0 +1,299 @@
+import { getCss } from 'ripple/server';
+import { base as importedBase, theme as importedTheme } from '../fixtures/scoped-styles/theme.tsrx';
+
+// RFC tsrx-org/RFCs#1 on the server: the class table matches the client, and
+// a request collects the sheets of the scopes it rendered — an applied theme
+// before the scope that applies it, whichever module the theme lives in.
+
+function hashes(element: Element | null): string[] {
+	return Array.from(element?.classList ?? []).filter((cls) => cls.startsWith('tsrx-'));
+}
+
+function tokens(value: string): string[] {
+	return value.split(' ').filter(Boolean);
+}
+
+const one = <style>
+	div {
+		color: red;
+	}
+</style>;
+
+describe('sibling-scoped style blocks (server)', () => {
+	function Status({ ready }: { ready: boolean }) @{
+		<>
+			<style>
+				.status {
+					padding: 0.5rem;
+				}
+			</style>
+			<section id="status" class="status">
+				<style>
+					.title {
+						font-weight: 700;
+					}
+					.status {
+						color: rgb(9, 9, 9);
+					}
+				</style>
+				<h2 id="title" class="title">{'Status'}</h2>
+				@if (ready) {
+					<>
+						<style>
+							.ok {
+								color: green;
+							}
+						</style>
+						<p id="ok" class="ok">{'Ready'}</p>
+					</>
+				} @else {
+					<>
+						<style>
+							.wait {
+								color: gray;
+							}
+						</style>
+						<p id="wait" class="wait">{'Waiting'}</p>
+					</>
+				}
+			</section>
+		</>
+	}
+
+	it('renders the class table and collects every scope sheet in source order', async () => {
+		function Ready() @{
+			<Status ready={true} />
+		}
+
+		const { body, css } = await render(Ready);
+		const { document } = parseHtml(body);
+
+		const [A] = hashes(document.querySelector('#status'));
+		expect(hashes(document.querySelector('#status'))).toEqual([A]);
+		const B = hashes(document.querySelector('#title'))[1];
+		expect(hashes(document.querySelector('#title'))).toEqual([A, B]);
+		const C = hashes(document.querySelector('#ok'))[2];
+		expect(hashes(document.querySelector('#ok'))).toEqual([A, B, C]);
+		expect(document.querySelector('#wait')).toBeNull();
+
+		// Every scope's CSS ships, the branch never rendered included, and the
+		// sheets follow source order.
+		const collected = [...css];
+		expect(collected).toHaveLength(4);
+		expect(collected.slice(0, 3)).toEqual([A, B, C]);
+		const text = getCss(css);
+		expect(text).toContain(`.status.${A}`);
+		expect(text).toContain(`.title.${B}`);
+		expect(text).toContain('/* (unused) .status {');
+		expect(text).toContain(`.ok.${C}`);
+		expect(text).toContain(`.wait.${collected[3]}`);
+		expect(text.indexOf(`.status.${A}`)).toBeLessThan(text.indexOf(`.title.${B}`));
+		expect(text.indexOf(`.title.${B}`)).toBeLessThan(text.indexOf(`.ok.${C}`));
+	});
+
+	it('stamps the other branch with its own hash', async () => {
+		function Waiting() @{
+			<Status ready={false} />
+		}
+
+		const { body } = await render(Waiting);
+		const { document } = parseHtml(body);
+
+		const wait = hashes(document.querySelector('#wait'));
+		expect(wait).toHaveLength(3);
+		expect(wait.slice(0, 2)).toEqual(hashes(document.querySelector('#title')));
+		expect(document.querySelector('#ok')).toBeNull();
+	});
+
+	it('registers the blocks of one children list as one sheet', async () => {
+		function Two() @{
+			<>
+				<style>
+					.host {
+						margin: 0;
+					}
+				</style>
+				<div id="host" class="host">
+					<style>
+						.a {
+							color: red;
+						}
+					</style>
+					<i class="a">{'a'}</i>
+					<style>
+						.b {
+							color: blue;
+						}
+					</style>
+					<b class="b">{'b'}</b>
+				</div>
+			</>
+		}
+
+		const { body, css } = await render(Two);
+		const { document } = parseHtml(body);
+
+		const [H] = hashes(document.querySelector('#host'));
+		const [, C] = hashes(document.querySelector('i'));
+		expect(hashes(document.querySelector('b'))).toEqual([H, C]);
+		expect([...css]).toEqual([H, C]);
+		const text = getCss(css);
+		expect(text).toContain(`.a.${C}`);
+		expect(text).toContain(`.b.${C}`);
+		expect(text.match(new RegExp(`\\.a\\.${C}`, 'g'))).toHaveLength(1);
+	});
+
+	it('merges the scope classes into a spread', async () => {
+		function Button(&{ ...rest }: { id: string; class?: string }) @{
+			<>
+				<style>
+					button {
+						padding: 0;
+					}
+				</style>
+				<div>
+					<style>
+						button {
+							margin: 0;
+						}
+					</style>
+					<button {...rest}>{'b'}</button>
+				</div>
+			</>
+		}
+
+		function App() @{
+			<Button id="btn" class="authored" />
+		}
+
+		const { body } = await render(App);
+		const { document } = parseHtml(body);
+
+		const button = document.querySelector('#btn');
+		expect(button?.classList.contains('authored')).toBe(true);
+		expect(hashes(button)).toHaveLength(2);
+	});
+});
+
+describe('spreads with an imported theme (server)', () => {
+	it('merges the scope classes of a static class into the spread once', async () => {
+		function Card(&{ ...rest }: { class?: string }) @{
+			<>
+				<style apply={importedTheme}>
+					.box {
+						color: red;
+					}
+				</style>
+				<div id="box" class="box" {...rest}>{'x'}</div>
+			</>
+		}
+
+		function App() @{
+			<Card class="from-spread" />
+		}
+
+		const { body } = await render(App);
+		expect(body.match(/class=/g)).toHaveLength(1);
+		const { document } = parseHtml(body);
+
+		const box = document.querySelector('#box');
+		const [local] = hashes(box);
+		expect(local).toBeTruthy();
+		expect(hashes(box)).toEqual([local, ...tokens(importedTheme.$class)]);
+		expect(box?.classList.contains('box')).toBe(true);
+	});
+});
+
+describe('$class and apply (server)', () => {
+	it(
+		'applies a same-module theme and registers its sheet before the scope that applies it',
+		async () => {
+			function WithBody() @{
+				<>
+					<style apply={one}>
+						.c {
+							margin: 0;
+						}
+					</style>
+					<div id="c1" class="c">{'c'}</div>
+				</>
+			}
+
+			const { body, css } = await render(WithBody);
+			const { document } = parseHtml(body);
+
+			const div = document.querySelector('#c1');
+			const [local, applied] = hashes(div);
+			expect(div?.className).toBe(`c ${local} ${one.$class}`);
+			expect(applied).toBe(one.$class);
+			expect([...css]).toEqual([one.$class, local]);
+			const text = getCss(css);
+			expect(text.indexOf(`div.${one.$class}`)).toBeLessThan(text.indexOf(`.c.${local}`));
+		},
+	);
+
+	it('applies an imported theme through its $class and collects its sheets first', async () => {
+		function Card() @{
+			<>
+				<style apply={importedTheme}>
+					h2 {
+						margin: 0;
+					}
+				</style>
+				<article id="card">
+					<h2 id="h2" class={importedTheme.dark}>{'Green, system-ui'}</h2>
+				</article>
+			</>
+		}
+
+		const { body, css } = await render(Card);
+		const { document } = parseHtml(body);
+
+		const card = document.querySelector('#card');
+		const [local] = hashes(card);
+		expect(hashes(card)).toEqual([local, ...tokens(importedTheme.$class)]);
+		// The class list is normalized on the server, so the theme hash that
+		// `theme.dark` already carries appears once.
+		const h2 = Array.from(document.querySelector('#h2')?.classList ?? []);
+		expect(h2.slice(0, 2)).toEqual(tokens(importedTheme.dark));
+		expect(h2).toContain(local);
+		for (const token of tokens(importedTheme.$class)) expect(h2).toContain(token);
+		// base (applied by theme), theme, then the applying scope.
+		expect([...css]).toEqual([...tokens(importedTheme.$class), local]);
+		const text = getCss(css);
+		expect(text.indexOf(`article.${importedBase.$class}`)).toBeLessThan(
+			text.indexOf(`article.${tokens(importedTheme.$class)[1]}`),
+		);
+		expect(text.indexOf(`.dark.${tokens(importedTheme.$class)[1]}`)).toBeLessThan(
+			text.indexOf(`h2.${local}`),
+		);
+	});
+
+	it('registers a theme only when something reads it', async () => {
+		function App() @{
+			const unused = <style>
+				.u {
+					color: red;
+				}
+			</style>;
+			const theme = <style>
+				div {
+					color: blue;
+				}
+			</style>;
+			<>
+				<div id="opted" class={theme.$class}>{'opted in'}</div>
+				<p id="untouched">{'untouched'}</p>
+			</>
+		}
+
+		const { body, css } = await render(App);
+		const { document } = parseHtml(body);
+
+		const theme_hash = document.querySelector('#opted')?.className;
+		expect(tokens(theme_hash!)).toHaveLength(1);
+		expect(document.querySelector('#untouched')?.className).toBe('');
+		expect([...css]).toEqual([theme_hash]);
+		expect(getCss(css)).toContain(`div.${theme_hash}`);
+	});
+});