@cratis/scene.react 0.1.0

package/for_SceneElementView/when_rendering_a_tree.tsx

@@ -0,0 +1,53 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { expect } from 'chai';
+import { render, screen } from '@testing-library/react';
+import { Control, ExternalComponent, HorizontalAlignment, VerticalAlignment, Visibility } from '@cratis/scene.model';
+import { SceneElementView } from '../SceneElementView';
+import { coreComponents } from '../core';
+
+function control(id: string): Control {
+    return {
+        id,
+        name: id,
+        properties: {},
+        visibility: Visibility.Visible,
+        isEnabled: true,
+        opacity: 1,
+        size: {},
+        zIndex: 0,
+        minimumSize: {},
+        maximumSize: {},
+        margin: { left: 0, top: 0, right: 0, bottom: 0 },
+        horizontalAlignment: HorizontalAlignment.Stretch,
+        verticalAlignment: VerticalAlignment.Stretch,
+        borderThickness: { left: 0, top: 0, right: 0, bottom: 0 },
+        padding: { left: 0, top: 0, right: 0, bottom: 0 },
+        tabIndex: 0,
+    };
+}
+
+describe('when rendering a tree', () => {
+    describe('and every component resolves', () => {
+        const text: ExternalComponent = { ...control('greeting'), componentName: 'core:text', properties: { text: 'Hello Scene' }, slots: {} };
+        const card: ExternalComponent = { ...control('card'), componentName: 'core:card', slots: { content: [text] } };
+
+        beforeEach(() => {
+            render(<SceneElementView element={card} registry={coreComponents} resolveBinding={() => undefined} />);
+        });
+
+        it('should render the nested core:text content', () => expect(screen.getByText('Hello Scene')).to.exist);
+    });
+
+    describe('and a component does not resolve', () => {
+        const missing: ExternalComponent = { ...control('missing'), componentName: 'vendor:fancy-widget', slots: {} };
+
+        beforeEach(() => {
+            render(<SceneElementView element={missing} registry={coreComponents} resolveBinding={() => undefined} />);
+        });
+
+        it('should render a visible unresolved-component placeholder', () =>
+            expect(screen.getByText('Unresolved component: vendor:fancy-widget')).to.exist);
+    });
+});

package/for_applyThemeTokens/when_switching_themes.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { JSDOM } from 'jsdom';
+import { Theme } from '@cratis/scene.model';
+import { applyThemeTokens } from '../index';
+
+const light: Theme = {
+    name: 'Daylight',
+    compatibleWith: ['core'],
+    tokens: { 'primary.color': '#2563eb', 'surface.background': '#ffffff' },
+};
+
+const dark: Theme = {
+    name: 'Midnight',
+    compatibleWith: ['core'],
+    isDark: true,
+    tokens: { 'primary.color': '#60a5fa' },
+};
+
+describe('when switching themes', () => {
+    const dom = new JSDOM('<div id="root"></div>');
+    const element = dom.window.document.getElementById('root') as unknown as HTMLElement;
+
+    applyThemeTokens(element, light);
+    const afterLight = {
+        primary: element.style.getPropertyValue('--scene-primary-color'),
+        surface: element.style.getPropertyValue('--scene-surface-background'),
+        theme: element.getAttribute('data-scene-theme'),
+        scheme: element.getAttribute('data-scene-color-scheme'),
+    };
+
+    applyThemeTokens(element, dark, light);
+    const afterDark = {
+        primary: element.style.getPropertyValue('--scene-primary-color'),
+        surface: element.style.getPropertyValue('--scene-surface-background'),
+        theme: element.getAttribute('data-scene-theme'),
+        scheme: element.getAttribute('data-scene-color-scheme'),
+    };
+
+    applyThemeTokens(element, undefined, dark);
+    const afterClearing = {
+        primary: element.style.getPropertyValue('--scene-primary-color'),
+        theme: element.getAttribute('data-scene-theme'),
+    };
+
+    it('should write the first theme tokens as custom properties', () => {
+        afterLight.primary.should.equal('#2563eb');
+        afterLight.surface.should.equal('#ffffff');
+    });
+
+    it('should mark the element with the first theme name and scheme', () => {
+        afterLight.theme!.should.equal('Daylight');
+        afterLight.scheme!.should.equal('light');
+    });
+
+    it('should overwrite a token the next theme also defines', () => {
+        afterDark.primary.should.equal('#60a5fa');
+    });
+
+    it('should remove a token the next theme does not define, rather than leaving it stale', () => {
+        afterDark.surface.should.equal('');
+    });
+
+    it('should mark the element as dark for a dark theme', () => {
+        afterDark.theme!.should.equal('Midnight');
+        afterDark.scheme!.should.equal('dark');
+    });
+
+    it('should clear every token and marker when the theme is removed', () => {
+        afterClearing.primary.should.equal('');
+        (afterClearing.theme === null).should.be.true;
+    });
+});

package/for_themeTokens/when_converting_a_token_name.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { themeTokenProperty } from '../index';
+
+describe('when converting a token name', () => {
+    it('should prefix a single-segment name', () => {
+        themeTokenProperty('primary').should.equal('--scene-primary');
+    });
+
+    it('should join dotted segments with dashes', () => {
+        themeTokenProperty('primary.color').should.equal('--scene-primary-color');
+    });
+
+    it('should split camelCase within a segment', () => {
+        themeTokenProperty('surface.borderColor').should.equal('--scene-surface-border-color');
+    });
+
+    it('should handle a segment with a digit boundary', () => {
+        themeTokenProperty('surface.level2Background').should.equal('--scene-surface-level2-background');
+    });
+});

package/for_validatePackageBundle/when_the_bundle_and_manifest_disagree.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind, ScenePackage } from '@cratis/scene.model';
+import { ScenePackageBundle, componentRegistryKey, validatePackageBundle } from '../index';
+import { CoreText } from '../core';
+
+function manifestFor(components: string[], layouts: string[] = [], themes: string[] = [], screenTemplates: string[] = []): ScenePackage {
+    return {
+        name: 'Test',
+        version: '1.0.0',
+        kind: PackageKind.ComponentLibrary,
+        dependencies: [],
+        components,
+        layouts,
+        screenTemplates,
+        dialogTemplates: [],
+        themes,
+    };
+}
+
+describe('when the bundle and manifest disagree', () => {
+    const declaredButNotRegistered = validatePackageBundle({
+        manifest: manifestFor(['text', 'missing']),
+        components: { [componentRegistryKey('Test', 'text')]: CoreText },
+    } as ScenePackageBundle);
+
+    const registeredButNotDeclared = validatePackageBundle({
+        manifest: manifestFor([]),
+        components: { [componentRegistryKey('Test', 'text')]: CoreText },
+    } as ScenePackageBundle);
+
+    const layoutDeclaredButNotProvided = validatePackageBundle({
+        manifest: manifestFor([], ['AppShell']),
+        components: {},
+    } as ScenePackageBundle);
+
+    const screenTemplateDeclaredButNotProvided = validatePackageBundle({
+        manifest: manifestFor([], [], [], ['ModuleWorkspace']),
+        components: {},
+    } as ScenePackageBundle);
+
+    const themeDeclaredButNotProvided = validatePackageBundle({
+        manifest: manifestFor([], [], ['Midnight']),
+        components: {},
+    } as ScenePackageBundle);
+
+    it('should report a component the manifest declares without an implementation', () => {
+        declaredButNotRegistered.should.have.lengthOf(1);
+        declaredButNotRegistered[0].should.contain("'missing'");
+    });
+
+    it('should report a component registered without being declared', () => {
+        registeredButNotDeclared.should.have.lengthOf(1);
+        registeredButNotDeclared[0].should.contain('Test:text');
+    });
+
+    it('should report a layout the manifest declares without a definition', () => {
+        layoutDeclaredButNotProvided.should.have.lengthOf(1);
+        layoutDeclaredButNotProvided[0].should.contain("'AppShell'");
+    });
+
+    it('should report a screen template the manifest declares without a definition', () => {
+        screenTemplateDeclaredButNotProvided.should.have.lengthOf(1);
+        screenTemplateDeclaredButNotProvided[0].should.contain("'ModuleWorkspace'");
+    });
+
+    it('should report a theme the manifest declares without a definition', () => {
+        themeDeclaredButNotProvided.should.have.lengthOf(1);
+        themeDeclaredButNotProvided[0].should.contain("'Midnight'");
+    });
+});

package/for_validatePackageBundle/when_the_bundle_matches_its_manifest.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { corePackage, validatePackageBundle } from '../index';
+
+describe('when the bundle matches its manifest', () => {
+    const problems = validatePackageBundle(corePackage);
+
+    it('should report no problems', () => {
+        problems.should.be.empty;
+    });
+});

package/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './SceneElementView';
+export * from './renderer';
+export * from './core';
+export * from './NavBar';
+export * from './packages';
+export * from './theme';

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@cratis/scene.react",
+    "version": "0.1.0",
+    "description": "The React renderer implementing Scene.Engine's Renderer contract against real React/DOM.",
+    "author": "Cratis",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Cratis/Scene.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "**/*.ts",
+        "**/*.tsx"
+    ],
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/esm/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/esm/index.d.ts",
+            "require": "./dist/cjs/index.js",
+            "import": "./dist/esm/index.js"
+        }
+    },
+    "scripts": {
+        "prepare": "yarn g:build",
+        "clean": "yarn g:clean",
+        "build": "yarn g:build",
+        "lint": "yarn g:lint",
+        "lint:ci": "yarn g:lint:ci",
+        "test": "yarn g:test",
+        "ci": "yarn g:ci",
+        "up": "yarn g:up",
+        "dev": "storybook dev -p 6006",
+        "build-storybook": "storybook build"
+    },
+    "dependencies": {
+        "@cratis/scene.engine": "0.1.0",
+        "@cratis/scene.model": "0.1.0"
+    },
+    "devDependencies": {
+        "@cratis/scene.engine": "0.1.0",
+        "@cratis/scene.model": "0.1.0",
+        "@storybook/addon-links": "^10.4.1",
+        "@storybook/react": "^10.4.1",
+        "@storybook/react-vite": "^10.4.1",
+        "react": "^19.2.6",
+        "react-dom": "^19.2.6",
+        "storybook": "^10.4.1"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+    }
+}

package/packages/ScenePackageBundle.ts

@@ -0,0 +1,137 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DialogTemplate, Layout, ScenePackage, Screen, ScreenTemplate, Theme } from '@cratis/scene.model';
+import { ComponentRegistry } from '../renderer';
+
+/**
+ * What a package actually ships to a React renderer, as opposed to what it *declares*.
+ *
+ * `ScenePackage` is the declaration — a name, a kind, dependencies, and the names of what it
+ * contributes. It is deliberately platform-agnostic and lives in `Scene.Model`, because Stage's build and
+ * Studio's design-time queries both read it without ever loading a component. A bundle is the other half:
+ * the real React components, layouts, screens and themes behind those names, which only a renderer needs.
+ *
+ * A package publishes exactly one bundle, as a named export following its own name —
+ * `primeReactPackage`, `cratisComponentsPackage`, `corePackage`. A host loads it from the module the
+ * declaration's `ScenePackage.module` names.
+ */
+export interface ScenePackageBundle {
+    /**
+     * The package's own declaration. Its `components`, `layouts` and `themes` name lists must agree with
+     * what this bundle actually provides — {@link validatePackageBundle} is what proves they do.
+     */
+    manifest: ScenePackage;
+
+    /**
+     * The components this package provides, keyed by {@link componentRegistryKey}.
+     */
+    components: ComponentRegistry;
+
+    /**
+     * The application shells this package provides, if any. Only a blueprint has these.
+     */
+    layouts?: Layout[];
+
+    /**
+     * The screen templates this package provides — the shapes that go inside a layout, each declaring
+     * which of its parent's slots it fills.
+     */
+    screenTemplates?: ScreenTemplate[];
+
+    /**
+     * The dialog templates this package provides.
+     */
+    dialogTemplates?: DialogTemplate[];
+
+    /**
+     * Sample screens this package ships — a layout package's gallery, so a preview has real content to
+     * put through the real engine rather than a mockup.
+     */
+    screens?: Screen[];
+
+    /**
+     * The themes this package ships, if any.
+     */
+    themes?: Theme[];
+}
+
+/**
+ * The key a component is registered and looked up under: the package that provides it, then the bare name
+ * a screen refers to it by.
+ *
+ * A screen writes a bare name (`button`) or a package-qualified one (`PrimeReact.button`);
+ * `resolveComponentName` turns either into a `{ name, package }` pair, and this turns that pair into the
+ * registry key. Nothing should build this string by hand — the separator is an implementation detail of
+ * the registry, deliberately not the `.` used for qualification in a screen, so a package name containing
+ * dots stays unambiguous.
+ */
+export function componentRegistryKey(packageName: string, componentName: string): string {
+    return `${packageName}:${componentName}`;
+}
+
+/**
+ * Checks that a bundle provides everything its manifest declares, and declares everything it provides.
+ *
+ * A manifest that promises a component the bundle does not register renders as `UnresolvedComponent` at
+ * runtime — a blank box, far from where the mistake was made. A component registered but not declared is
+ * invisible to `resolveComponentName`, so a screen can never name it. Both are silent failures, which is
+ * why every package's specs run this.
+ */
+export function validatePackageBundle(bundle: ScenePackageBundle): string[] {
+    const problems: string[] = [];
+    const { manifest } = bundle;
+
+    for (const name of manifest.components) {
+        if (!(componentRegistryKey(manifest.name, name) in bundle.components)) {
+            problems.push(`declares the component '${name}' but registers no implementation for it`);
+        }
+    }
+
+    const declared = new Set(manifest.components.map((name) => componentRegistryKey(manifest.name, name)));
+    for (const key of Object.keys(bundle.components)) {
+        if (!declared.has(key)) {
+            problems.push(`registers '${key}', which the manifest does not declare`);
+        }
+    }
+
+    const providedLayouts = new Set((bundle.layouts ?? []).map((layout) => layout.name));
+    for (const name of manifest.layouts) {
+        if (!providedLayouts.has(name)) {
+            problems.push(`declares the layout '${name}' but provides no definition for it`);
+        }
+    }
+
+    const providedScreenTemplates = new Set((bundle.screenTemplates ?? []).map((template) => template.name));
+    for (const name of manifest.screenTemplates) {
+        if (!providedScreenTemplates.has(name)) {
+            problems.push(`declares the screen template '${name}' but provides no definition for it`);
+        }
+    }
+
+    const providedDialogTemplates = new Set((bundle.dialogTemplates ?? []).map((template) => template.name));
+    for (const name of manifest.dialogTemplates) {
+        if (!providedDialogTemplates.has(name)) {
+            problems.push(`declares the dialog template '${name}' but provides no definition for it`);
+        }
+    }
+
+    const providedThemes = new Set((bundle.themes ?? []).map((theme) => theme.name));
+    for (const name of manifest.themes) {
+        if (!providedThemes.has(name)) {
+            problems.push(`declares the theme '${name}' but provides no definition for it`);
+        }
+    }
+
+    return problems;
+}
+
+/**
+ * Merges the component registries of several bundles into the single registry a renderer consumes.
+ *
+ * Keys carry their package name, so nothing collides and merge order does not matter — which package wins
+ * a *bare* name is decided earlier, by `resolveComponentName` walking the profile's priority order.
+ */
+export function mergePackageRegistries(bundles: ScenePackageBundle[]): ComponentRegistry {
+    return Object.assign({}, ...bundles.map((bundle) => bundle.components)) as ComponentRegistry;
+}

package/packages/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './ScenePackageBundle';

package/renderer/ComponentRegistry.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentType, ReactNode } from 'react';
+import { ExternalComponent } from '@cratis/scene.model';
+
+/**
+ * The props every registered component receives.
+ */
+export interface RegisteredComponentProps {
+    element: ExternalComponent;
+    slots: Record<string, ReactNode[]>;
+}
+
+/**
+ * Maps a resolved component name (as `ExternalComponent.componentName` already carries it, post
+ * `ui profile` package resolution) to the React component that renders it. Bare-name resolution against a
+ * profile's package list is `resolveComponentName` in `@cratis/scene.engine` (Cratis/Scene#3) - this
+ * registry is keyed by the already-resolved name; wiring the two together (resolving an entire element
+ * tree's component names before it reaches this registry) is Stage#39/StudioIssues#160's job, not this
+ * registry's.
+ */
+export type ComponentRegistry = Record<string, ComponentType<RegisteredComponentProps>>;

package/renderer/UnresolvedComponent.tsx

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from './ComponentRegistry';
+
+/**
+ * The fallback rendered for an {@link ExternalComponent} whose `componentName` is not in the active
+ * {@link ComponentRegistry} - a visibly broken placeholder, never a silent blank, since a missing
+ * component is a real configuration gap the renderer should surface, not hide.
+ */
+export function UnresolvedComponent({ element }: RegisteredComponentProps) {
+    return (
+        <div
+            data-scene-unresolved-component={element.componentName}
+            style={{ border: '1px dashed red', color: 'red', padding: '0.25rem 0.5rem', fontFamily: 'monospace' }}
+        >
+            Unresolved component: {element.componentName}
+        </div>
+    );
+}

package/renderer/createReactRenderer.tsx

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, createElement } from 'react';
+import { Renderer } from '@cratis/scene.engine';
+import { ContentControl, ExternalComponent, ItemsControl, Panel } from '@cratis/scene.model';
+import { ComponentRegistry } from './ComponentRegistry';
+import { UnresolvedComponent } from './UnresolvedComponent';
+
+/**
+ * Creates a {@link Renderer} that turns a Scene element tree into React elements. `Panel`, `ItemsControl`
+ * and `ContentControl` render as plain wrapping `div`s here - arranging them according to a layout's
+ * `flow`/`freeform` arrangement is Scene#4's job, layered on top of this renderer rather than folded
+ * into it.
+ */
+export function createReactRenderer(registry: ComponentRegistry): Renderer<ReactNode> {
+    return {
+        renderContentControl(element: ContentControl, content: ReactNode): ReactNode {
+            return createElement('div', { key: element.id, 'data-scene-id': element.id, 'data-scene-kind': 'ContentControl' }, content);
+        },
+
+        renderItemsControl(element: ItemsControl, items: ReactNode[]): ReactNode {
+            return createElement('div', { key: element.id, 'data-scene-id': element.id, 'data-scene-kind': 'ItemsControl' }, items);
+        },
+
+        renderExternalComponent(element: ExternalComponent, slots: Record<string, ReactNode[]>): ReactNode {
+            const Component = registry[element.componentName] ?? UnresolvedComponent;
+            return createElement(Component, { key: element.id, element, slots });
+        },
+
+        renderPanel(element: Panel, children: ReactNode[]): ReactNode {
+            return createElement('div', { key: element.id, 'data-scene-id': element.id, 'data-scene-kind': 'Panel' }, children);
+        },
+    };
+}

package/renderer/index.ts

@@ -0,0 +1,6 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './ComponentRegistry';
+export * from './UnresolvedComponent';
+export * from './createReactRenderer';

package/theme/SceneThemeProvider.tsx

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode, createContext, useContext, useLayoutEffect, useRef } from 'react';
+import { Theme } from '@cratis/scene.model';
+import { applyThemeTokens } from './themeTokens';
+
+const SceneThemeContext = createContext<Theme | undefined>(undefined);
+
+/**
+ * The theme currently applied by the nearest {@link SceneThemeProvider}, for a package component that has
+ * to make a decision a token cannot express - picking a light or dark logo asset, say.
+ */
+export function useSceneTheme(): Theme | undefined {
+    return useContext(SceneThemeContext);
+}
+
+export interface SceneThemePropsBase {
+    /**
+     * The theme to apply. Changing it re-resolves in place - no reload, no remount of the subtree.
+     */
+    theme?: Theme;
+
+    /**
+     * The content the theme applies to.
+     */
+    children?: ReactNode;
+
+    /**
+     * A class name for the element the tokens land on.
+     */
+    className?: string;
+}
+
+/**
+ * Applies a {@link Theme}'s tokens to a wrapping element and makes the theme available to everything
+ * inside it.
+ *
+ * Theme switching is live re-resolution: the tokens are written onto the same element rather than
+ * swapping a stylesheet, so a preview changes theme without a flash and without losing any state below
+ * it. That is what lets Studio's gallery switch themes as fast as you can click.
+ */
+export function SceneThemeProvider({ theme, children, className }: SceneThemePropsBase) {
+    const elementRef = useRef<HTMLDivElement>(null);
+    const previousRef = useRef<Theme | undefined>(undefined);
+
+    useLayoutEffect(() => {
+        if (!elementRef.current) return;
+        applyThemeTokens(elementRef.current, theme, previousRef.current);
+        previousRef.current = theme;
+    }, [theme]);
+
+    return (
+        <div ref={elementRef} className={className} data-scene-theme-root=''>
+            <SceneThemeContext.Provider value={theme}>{children}</SceneThemeContext.Provider>
+        </div>
+    );
+}

package/theme/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './themeTokens';
+export * from './SceneThemeProvider';

package/theme/themeTokens.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Theme } from '@cratis/scene.model';
+
+/**
+ * The prefix every Scene design token gets as a CSS custom property. A package adapts these to whatever
+ * its own component library expects — the PrimeReact package maps them onto PrimeReact's variables, the
+ * same indirection `@cratis/components` uses for its `--cratis-*` layer — so layout and component CSS
+ * never hardcodes one library's variable names.
+ */
+export const themeTokenPrefix = '--scene';
+
+/**
+ * Turns a semantic token name into its CSS custom property name: `primary.color` becomes
+ * `--scene-primary-color`, `surface.borderColor` becomes `--scene-surface-border-color`.
+ *
+ * Token names are semantic and platform-neutral in `Scene.Model` on purpose; this is the one place that
+ * decides what they look like in CSS, so a non-DOM renderer can make an entirely different choice.
+ */
+export function themeTokenProperty(token: string): string {
+    const kebab = token
+        .split('.')
+        .map((part) => part.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase())
+        .join('-');
+    return `${themeTokenPrefix}-${kebab}`;
+}
+
+/**
+ * Applies a theme to an element, in place.
+ *
+ * Every token becomes a custom property on the element, and the element is marked with the theme's name
+ * and colour scheme so CSS can key off either. Tokens the previous theme set and this one does not are
+ * removed, so switching themes cannot leave a stale value behind.
+ *
+ * This is deliberately a mutation of an existing element rather than a re-render: switching theme has to
+ * be live re-resolution against the running profile, with no reload and no remount, or a gallery preview
+ * flickers every time someone tries a different theme.
+ */
+export function applyThemeTokens(element: HTMLElement, theme: Theme | undefined, previous?: Theme): void {
+    for (const token of Object.keys(previous?.tokens ?? {})) {
+        if (!theme?.tokens || !(token in theme.tokens)) {
+            element.style.removeProperty(themeTokenProperty(token));
+        }
+    }
+
+    if (!theme) {
+        element.removeAttribute('data-scene-theme');
+        element.removeAttribute('data-scene-color-scheme');
+        return;
+    }
+
+    for (const [token, value] of Object.entries(theme.tokens ?? {})) {
+        element.style.setProperty(themeTokenProperty(token), value);
+    }
+
+    element.setAttribute('data-scene-theme', theme.name);
+    element.setAttribute('data-scene-color-scheme', theme.isDark ? 'dark' : 'light');
+}