@cratis/scene.engine 0.1.0

package/packageCatalog.ts

@@ -0,0 +1,65 @@
+// 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';
+
+/**
+ * The packages of a given kind.
+ */
+export function packagesOfKind(catalog: ScenePackage[], kind: PackageKind): ScenePackage[] {
+    return catalog.filter((scenePackage) => scenePackage.kind === kind);
+}
+
+/**
+ * The component libraries a profile can be founded on — the ones that do not themselves layer on another
+ * component library.
+ *
+ * "Base" is not a declared property; it falls out of the dependency graph. PrimeReact depends on a
+ * styling package but on no other component library, so it is a base. `@cratis/components` depends on
+ * PrimeReact, so it is not — it is something you add on top of a base you already picked. Deriving it
+ * this way means a third party shipping their own library gets classified correctly without having to
+ * declare anything extra.
+ */
+export function baseComponentLibraries(catalog: ScenePackage[]): ScenePackage[] {
+    const libraries = packagesOfKind(catalog, PackageKind.ComponentLibrary);
+    const names = new Set(libraries.map((scenePackage) => scenePackage.name));
+    return libraries.filter((scenePackage) => !scenePackage.dependencies.some((dependency) => names.has(dependency.name)));
+}
+
+/**
+ * The packages that can be added to a selection without pulling anything else in — every dependency they
+ * declare is already selected.
+ *
+ * This is the "what else works with what I have picked" list: choose PrimeReact and Tailwind, and
+ * `@cratis/components` becomes available because both of its dependencies are now met. It is
+ * deliberately stricter than {@link resolvePackageDependencies}, which will happily add the missing
+ * dependencies for you — a picker wants to show what fits, not what would drag more in.
+ */
+export function availablePackagesFor(catalog: ScenePackage[], selected: string[]): ScenePackage[] {
+    const chosen = new Set(selected);
+    return catalog.filter(
+        (scenePackage) => !chosen.has(scenePackage.name) && scenePackage.dependencies.every((dependency) => chosen.has(dependency.name))
+    );
+}
+
+/**
+ * Every component name the selected packages declare between them, without duplicates, sorted so a
+ * component picker has a stable list to show.
+ */
+export function componentsForPackages(catalog: ScenePackage[], selected: string[]): string[] {
+    const chosen = new Set(selected);
+    const components = catalog.filter((scenePackage) => chosen.has(scenePackage.name)).flatMap((scenePackage) => scenePackage.components);
+    return [...new Set(components)].sort();
+}
+
+/**
+ * Builds the component-name catalog `resolveComponentName` resolves against.
+ */
+export function toComponentCatalog(catalog: ScenePackage[]): Record<string, string[]> {
+    const components: Record<string, string[]> = {};
+    for (const scenePackage of catalog) {
+        components[scenePackage.name] = scenePackage.components;
+    }
+
+    return components;
+}

package/packageVersionRange.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Checks a {@link PackageDependency.versionRange} against a package's actual version. A deliberately
+ * small subset of semver — enough to express what a package declaration realistically needs, and small
+ * enough that the C# twin in `Cratis.Scene.Engine` can match it exactly rather than approximately. Both
+ * sides are asserted against the same shared fixture corpus.
+ *
+ * Supported: an empty range or `*` (anything), a bare or `=`-prefixed exact version, `^` (npm caret —
+ * compatible within the leftmost non-zero component), `~` (patch-level changes), and the comparisons
+ * `>=`, `>`, `<=`, `<`. Versions are read as `major.minor.patch` with any pre-release or build metadata
+ * suffix ignored. Anything the parser does not recognize is treated as unsatisfiable rather than as
+ * "anything", so a typo surfaces as a conflict instead of silently passing.
+ */
+export function isVersionSatisfiedBy(version: string, range: string | undefined): boolean {
+    const trimmed = range?.trim();
+    if (!trimmed || trimmed === '*') return true;
+
+    const actual = parseVersion(version);
+    if (!actual) return false;
+
+    const [operator, literal] = splitRange(trimmed);
+    const required = parseVersion(literal);
+    if (!required) return false;
+
+    switch (operator) {
+        case '^':
+            return compare(actual, required) >= 0 && compare(actual, caretUpperBound(required)) < 0;
+        case '~':
+            return compare(actual, required) >= 0 && compare(actual, [required[0], required[1] + 1, 0]) < 0;
+        case '>=':
+            return compare(actual, required) >= 0;
+        case '>':
+            return compare(actual, required) > 0;
+        case '<=':
+            return compare(actual, required) <= 0;
+        case '<':
+            return compare(actual, required) < 0;
+        default:
+            return compare(actual, required) === 0;
+    }
+}
+
+type Version = [number, number, number];
+
+function splitRange(range: string): [string, string] {
+    for (const operator of ['>=', '<=', '^', '~', '>', '<', '=']) {
+        if (range.startsWith(operator)) {
+            return [operator === '=' ? '' : operator, range.substring(operator.length).trim()];
+        }
+    }
+
+    return ['', range];
+}
+
+/**
+ * npm's caret rule: compatibility is bounded by the leftmost non-zero component, so `^1.2.3` allows
+ * anything below `2.0.0`, `^0.2.3` anything below `0.3.0`, and `^0.0.3` only `0.0.3` itself.
+ */
+function caretUpperBound(version: Version): Version {
+    if (version[0] > 0) return [version[0] + 1, 0, 0];
+    if (version[1] > 0) return [0, version[1] + 1, 0];
+    return [0, 0, version[2] + 1];
+}
+
+function compare(left: Version, right: Version): number {
+    if (left[0] !== right[0]) return left[0] - right[0];
+    if (left[1] !== right[1]) return left[1] - right[1];
+    return left[2] - right[2];
+}
+
+function parseVersion(value: string): Version | undefined {
+    let numeric = value.trim();
+    const suffix = numeric.search(/[-+]/);
+    if (suffix >= 0) {
+        numeric = numeric.substring(0, suffix);
+    }
+
+    const parts = numeric.split('.');
+    if (parts.length === 0 || parts.length > 3) return undefined;
+
+    const components: Version = [0, 0, 0];
+    for (let index = 0; index < parts.length; index++) {
+        if (!/^\d+$/.test(parts[index])) return undefined;
+        components[index] = parseInt(parts[index], 10);
+    }
+
+    return components;
+}

package/renderElement.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { Renderer } from './Renderer';
+import { BindingResolver } from './BindingResolver';
+import { isContentControl, isItemsControl, isExternalComponent, isPanel } from './elementKind';
+
+/**
+ * Walks a Scene element tree, rendering each node's children before the node itself, and hands the
+ * result to the supplied {@link Renderer}. This is a structural tree walk only - resolving a `ui
+ * profile`'s package list, aggregating contribution points, and computing layout arrangement are the
+ * jobs of the profile resolution, contribution runtime and layout engines (Scene#3, Scene#2, Scene#4),
+ * layered on top of this walk rather than folded into it.
+ */
+export function renderElement<TOutput>(element: SceneElement, renderer: Renderer<TOutput>, resolveBinding: BindingResolver): TOutput {
+    if (isContentControl(element)) {
+        return renderer.renderContentControl(element, renderElement(element.content, renderer, resolveBinding));
+    }
+
+    if (isItemsControl(element)) {
+        const items = resolveBinding(element.itemsSource);
+        const itemCount = Array.isArray(items) ? items.length : 0;
+        const rendered = Array.from({ length: itemCount }, () => renderElement(element.itemTemplate, renderer, resolveBinding));
+        return renderer.renderItemsControl(element, rendered);
+    }
+
+    if (isExternalComponent(element)) {
+        const slots = Object.fromEntries(
+            Object.entries(element.slots).map(([name, children]) => [name, children.map(child => renderElement(child, renderer, resolveBinding))]),
+        );
+        return renderer.renderExternalComponent(element, slots);
+    }
+
+    if (isPanel(element)) {
+        return renderer.renderPanel(element, element.children.map(child => renderElement(child, renderer, resolveBinding)));
+    }
+
+    throw new Error(`Scene element '${element.id}' is not a recognized concrete kind (ContentControl, ItemsControl, ExternalComponent or Panel).`);
+}

package/resolveComponentName.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UiProfile } from '@cratis/scene.model';
+import { ComponentResolution } from './ComponentResolution';
+
+/** The name of the package that is always present as the final fallback, regardless of what a {@link UiProfile} lists in its own `packages`. */
+export const corePackage = 'core';
+
+/** Every active package's declared component names, keyed by package name. */
+export type PackageCatalog = Record<string, string[]>;
+
+/**
+ * Computes a {@link UiProfile}'s effective package priority order - its own declared packages, with
+ * {@link corePackage} prepended as the final fallback when not already present. {@link corePackage} is
+ * the lowest-priority fallback, so it belongs at the front of the ascending-priority order, not the
+ * back - prepending it (rather than appending) is what makes every explicitly listed package outrank it.
+ *
+ * @returns The packages in ascending priority order - the last entry wins when more than one declares the same name.
+ */
+export function effectivePackages(profile: UiProfile): string[] {
+    return profile.packages.includes(corePackage) ? profile.packages : [corePackage, ...profile.packages];
+}
+
+/**
+ * Resolves a component name against a {@link UiProfile} - the runtime half of Cratis/Scene#3, run
+ * whenever a profile is applied. Studio's design-time tooling and Stage's build-time resolution use the
+ * C# twin of this algorithm in `Cratis.Scene.Engine`; both sides are asserted against the same shared
+ * fixture corpus so they cannot drift apart.
+ *
+ * A name containing a `.` is package-qualified - everything before the last `.` is the package,
+ * everything after is the bare name - and resolves directly against that one package, bypassing shadow
+ * tracking and the profile's priority order entirely (an author naming the package explicitly has
+ * already disambiguated). A name with no `.` is bare and resolves by walking {@link effectivePackages}
+ * from highest to lowest priority; every other active package that also declares the name is recorded in
+ * the result's `shadows`, not discarded, so a caller can explain the pick rather than only report it.
+ *
+ * @param requestedName The name as written on a screen - bare (`button`) or package-qualified (`Internal.Widgets.TrendChart`).
+ * @param profile The {@link UiProfile} whose package list to resolve against.
+ * @param catalog Every active package's declared component names, keyed by package name.
+ * @returns The {@link ComponentResolution}, or `undefined` when nothing in scope declares the name.
+ */
+export function resolveComponentName(requestedName: string, profile: UiProfile, catalog: PackageCatalog): ComponentResolution | undefined {
+    const lastDot = requestedName.lastIndexOf('.');
+    if (lastDot >= 0) {
+        const qualifiedPackage = requestedName.slice(0, lastDot);
+        const qualifiedName = requestedName.slice(lastDot + 1);
+        return declares(catalog, qualifiedPackage, qualifiedName)
+            ? { name: qualifiedName, package: qualifiedPackage, shadows: [] }
+            : undefined;
+    }
+
+    const priority = effectivePackages(profile);
+    const matches: string[] = [];
+    for (let index = priority.length - 1; index >= 0; index--) {
+        if (declares(catalog, priority[index], requestedName)) {
+            matches.push(priority[index]);
+        }
+    }
+
+    return matches.length === 0 ? undefined : { name: requestedName, package: matches[0], shadows: matches.slice(1) };
+}
+
+function declares(catalog: PackageCatalog, packageName: string, name: string): boolean {
+    return catalog[packageName]?.includes(name) ?? false;
+}

package/resolvePackageDependencies.ts

@@ -0,0 +1,156 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ScenePackage } from '@cratis/scene.model';
+import { MissingPackageDependency, PackageSelection, PackageVersionConflict } from './PackageSelection';
+import { isVersionSatisfiedBy } from './packageVersionRange';
+
+/**
+ * Expands a chosen set of package names into the complete, correctly ordered list a {@link UiProfile}
+ * needs — the runtime half. The C# twin in `Cratis.Scene.Engine` implements the same algorithm for
+ * Studio's package picker and Stage's build; both are asserted against the same shared fixture corpus so
+ * they cannot drift apart.
+ *
+ * This is a different concern from `resolveComponentName`, which resolves one component *name* against
+ * an already-decided package list. This decides what that list is.
+ *
+ * Ordering is a stable topological sort: among packages whose dependencies are equally satisfied, the one
+ * the caller named first comes first, and packages pulled in transitively follow in the order they were
+ * discovered. When a cycle makes ordering impossible, the packages involved are reported in `cycles` and
+ * appended in discovery order rather than dropped.
+ */
+export function resolvePackageDependencies(selected: string[], catalog: ScenePackage[]): PackageSelection {
+    const index = new Map(catalog.map((scenePackage) => [scenePackage.name, scenePackage]));
+    const discovered: string[] = [];
+    const seen = new Set<string>(selected);
+    const missing: MissingPackageDependency[] = [];
+    const versionConflicts: PackageVersionConflict[] = [];
+
+    const pending = [...selected];
+    while (pending.length > 0) {
+        const name = pending.shift()!;
+        discovered.push(name);
+
+        const scenePackage = index.get(name);
+        if (!scenePackage) continue;
+
+        for (const dependency of scenePackage.dependencies) {
+            const dependedOn = index.get(dependency.name);
+            if (!dependedOn) {
+                missing.push({ package: scenePackage.name, dependsOn: dependency.name });
+                continue;
+            }
+
+            if (!isVersionSatisfiedBy(dependedOn.version, dependency.versionRange)) {
+                versionConflicts.push({
+                    package: scenePackage.name,
+                    dependsOn: dependency.name,
+                    requiredRange: dependency.versionRange!,
+                    actualVersion: dependedOn.version,
+                });
+            }
+
+            if (!seen.has(dependency.name)) {
+                seen.add(dependency.name);
+                pending.push(dependency.name);
+            }
+        }
+    }
+
+    const cycles = findCycles(discovered, index);
+    const packages = topologicallyOrder(discovered, index);
+    const chosen = new Set(selected);
+
+    return {
+        packages,
+        added: packages.filter((name) => !chosen.has(name)),
+        missing,
+        versionConflicts,
+        cycles,
+    };
+}
+
+function dependenciesWithin(name: string, index: Map<string, ScenePackage>, within: Set<string>): string[] {
+    const scenePackage = index.get(name);
+    if (!scenePackage) return [];
+    const names = scenePackage.dependencies.map((dependency) => dependency.name).filter((dependency) => within.has(dependency));
+    return [...new Set(names)];
+}
+
+/**
+ * Orders an already-closed set of package names so each follows the packages it depends on.
+ */
+function topologicallyOrder(names: string[], index: Map<string, ScenePackage>): string[] {
+    const within = new Set(names);
+    const remaining = new Map(names.map((name) => [name, dependenciesWithin(name, index, within).length]));
+
+    const ordered: string[] = [];
+    const placed = new Set<string>();
+    let progressed = true;
+    while (progressed) {
+        progressed = false;
+        for (const name of names) {
+            if (placed.has(name) || remaining.get(name) !== 0) continue;
+
+            ordered.push(name);
+            placed.add(name);
+            progressed = true;
+
+            for (const other of names) {
+                if (placed.has(other)) continue;
+                if (dependenciesWithin(other, index, within).includes(name)) {
+                    remaining.set(other, remaining.get(other)! - 1);
+                }
+            }
+        }
+    }
+
+    // Anything left is inside a cycle, or downstream of one. It is reported through `cycles`; keeping it
+    // in the list means a package picker never silently loses a package it was told about.
+    ordered.push(...names.filter((name) => !placed.has(name)));
+    return ordered;
+}
+
+/**
+ * Finds every dependency cycle, walking depth-first from each package in discovery order so the result
+ * is deterministic. A cycle is recorded once, keyed by the set of packages in it.
+ */
+function findCycles(names: string[], index: Map<string, ScenePackage>): string[][] {
+    const within = new Set(names);
+    const cycles: string[][] = [];
+    const recorded = new Set<string>();
+    const path: string[] = [];
+    const onPath = new Set<string>();
+    const explored = new Set<string>();
+
+    const walk = (name: string) => {
+        if (onPath.has(name)) {
+            const cycle = path.slice(path.indexOf(name));
+            const key = [...cycle].sort().join(' ');
+            if (!recorded.has(key)) {
+                recorded.add(key);
+                cycles.push(cycle);
+            }
+
+            return;
+        }
+
+        if (explored.has(name)) return;
+        explored.add(name);
+
+        path.push(name);
+        onPath.add(name);
+        for (const dependency of dependenciesWithin(name, index, within)) {
+            walk(dependency);
+        }
+
+        onPath.delete(name);
+        path.pop();
+    };
+
+    for (const name of names) {
+        walk(name);
+    }
+
+    return cycles;
+}

package/resolveScreenTemplates.ts

@@ -0,0 +1,191 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Layout, ScreenTemplate } from '@cratis/scene.model';
+
+/**
+ * Where one {@link ScreenTemplate} ended up: the slot it declared, and the layout or template that turned
+ * out to declare that slot.
+ */
+export interface ScreenTemplatePlacement {
+    /** The template being placed. */
+    template: string;
+    /** The slot name the template declared it fits. */
+    slot: string;
+    /** The name of the {@link Layout} or {@link ScreenTemplate} declaring that slot. */
+    container: string;
+    /** How far below the layout the template sits — 1 directly inside the layout, 2 inside a template that is. */
+    depth: number;
+}
+
+/**
+ * A template that names a slot, where the set of containers in scope does not agree on exactly one home for
+ * it.
+ */
+export interface UnplacedScreenTemplate {
+    /** The template that could not be placed. */
+    template: string;
+    /** The slot name it declared it fits. */
+    slot: string;
+    /**
+     * The containers declaring a slot of that name. Empty when nothing declares it; more than one when the
+     * name is ambiguous. Never exactly one — that case is a {@link ScreenTemplatePlacement} instead.
+     */
+    candidates: string[];
+}
+
+/**
+ * The outcome of working out how a blueprint's templates nest inside its layout.
+ */
+export interface ScreenTemplateResolution {
+    /** Every template that found exactly one home, ordered shallowest first so a caller can build the tree top-down. */
+    placements: ScreenTemplatePlacement[];
+    /**
+     * Templates that found none or several. Reported rather than guessed: placing a template in the wrong
+     * parent renders content in the wrong region, which is far harder to diagnose than being told the slot
+     * name is ambiguous.
+     */
+    unplaced: UnplacedScreenTemplate[];
+    /** Template nesting cycles — a template that transitively contains itself. */
+    cycles: string[][];
+}
+
+/**
+ * Whether every template found exactly one home and nothing nests inside itself.
+ */
+export function isScreenTemplateResolutionValid(resolution: ScreenTemplateResolution): boolean {
+    return resolution.unplaced.length === 0 && resolution.cycles.length === 0;
+}
+
+/**
+ * Works out how a blueprint's {@link ScreenTemplate}s nest inside its {@link Layout}.
+ *
+ * A template declares only the *name* of the slot it fits, never which container owns that slot. That is
+ * what makes templates reusable — a feature's template says "I go in the module content area", not "I go
+ * inside this specific module". Resolution is the step that turns those names into a tree, by finding which
+ * layout or template declares each name.
+ *
+ * The same rule applies at every level, so nesting has no depth limit and no separate mechanism per level.
+ * The C# twin in `Cratis.Scene.Engine` implements the same algorithm; both are asserted against the same
+ * shared fixture corpus so they cannot drift apart.
+ */
+export function resolveScreenTemplates(layout: Layout, templates: ScreenTemplate[]): ScreenTemplateResolution {
+    const containersBySlot = buildSlotIndex(layout, templates);
+    const parents = new Map<string, string>();
+    const slots = new Map<string, string>();
+    const unplaced: UnplacedScreenTemplate[] = [];
+
+    for (const template of templates) {
+        if (template.fitsSlot === undefined) continue;
+
+        const [qualifier, slot] = splitQualifiedSlot(template.fitsSlot);
+
+        const candidates = (containersBySlot.get(slot) ?? []).filter(
+            (container) => container !== template.name && (qualifier === undefined || container === qualifier)
+        );
+
+        if (candidates.length === 1) {
+            parents.set(template.name, candidates[0]);
+            slots.set(template.name, slot);
+        } else {
+            unplaced.push({ template: template.name, slot: template.fitsSlot, candidates });
+        }
+    }
+
+    const cycles = findCycles(parents);
+    const inCycle = new Set(cycles.flat());
+
+    const placements: ScreenTemplatePlacement[] = [];
+    for (const template of templates) {
+        const container = parents.get(template.name);
+        if (container === undefined || inCycle.has(template.name)) continue;
+
+        placements.push({
+            template: template.name,
+            slot: slots.get(template.name)!,
+            container,
+            depth: depthOf(template.name, parents, layout.name),
+        });
+    }
+
+    placements.sort((left, right) => left.depth - right.depth || left.template.localeCompare(right.template));
+
+    return { placements, unplaced, cycles };
+}
+
+/**
+ * Splits a `fitsSlot` into the container it names and the slot within it.
+ *
+ * The same rule component names use: a bare name searches, a qualified one goes straight to what it names.
+ * A slot called `body` is a good name at every level of a nesting chain, so several templates legitimately
+ * declare one — and a bare `body` then has no single answer. Qualifying it says which, without forcing
+ * every slot in an application to carry a unique name.
+ */
+function splitQualifiedSlot(fitsSlot: string): [string | undefined, string] {
+    const lastDot = fitsSlot.lastIndexOf('.');
+    return lastDot < 0 ? [undefined, fitsSlot] : [fitsSlot.substring(0, lastDot), fitsSlot.substring(lastDot + 1)];
+}
+
+function buildSlotIndex(layout: Layout, templates: ScreenTemplate[]): Map<string, string[]> {
+    const index = new Map<string, string[]>();
+
+    const declare = (slot: string, container: string) => {
+        const containers = index.get(slot) ?? [];
+        if (!containers.includes(container)) containers.push(container);
+        index.set(slot, containers);
+    };
+
+    for (const slot of layout.slots) declare(slot.name, layout.name);
+    for (const template of templates) {
+        for (const slot of template.slots) declare(slot.name, template.name);
+    }
+
+    return index;
+}
+
+function findCycles(parents: Map<string, string>): string[][] {
+    const cycles: string[][] = [];
+    const recorded = new Set<string>();
+
+    for (const start of [...parents.keys()].sort()) {
+        const path: string[] = [];
+        const onPath = new Set<string>();
+        let current = start;
+
+        for (;;) {
+            const parent = parents.get(current);
+            if (parent === undefined) break;
+
+            path.push(current);
+            onPath.add(current);
+            if (onPath.has(parent)) {
+                const cycle = path.slice(path.indexOf(parent));
+                const key = [...cycle].sort().join(' ');
+                if (!recorded.has(key)) {
+                    recorded.add(key);
+                    cycles.push(cycle);
+                }
+
+                break;
+            }
+
+            onPath.add(parent);
+            current = parent;
+        }
+    }
+
+    return cycles;
+}
+
+function depthOf(template: string, parents: Map<string, string>, layoutName: string): number {
+    let depth = 0;
+    let current = template;
+    while (parents.has(current) && depth <= parents.size) {
+        depth++;
+        const parent = parents.get(current)!;
+        if (parent === layoutName) break;
+        current = parent;
+    }
+
+    return depth;
+}

package/themeCompatibility.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Theme, UiProfile } from '@cratis/scene.model';
+
+/**
+ * Finds the packages a {@link UiProfile} declares that a {@link Theme} is not declared compatible with -
+ * part of Cratis/Scene#5, the same rule Screenplay's compiler already applies to warn on an incompatible
+ * `ui profile`/`theme` pairing, reused here so `Scene.React` knows which packages to actually apply a
+ * theme's tokens to, and so Studio's design-time tooling and Stage's build-time checks don't each
+ * reimplement it. There is deliberately no implicit exemption for `core`: a theme wanting broad
+ * applicability declares `compatible with core` itself, exactly like the profile/package resolver has no
+ * implicit special case for it either.
+ *
+ * @param theme The {@link Theme} to check.
+ * @param profile The {@link UiProfile} whose packages to check against.
+ * @returns The packages in `profile.packages` that `theme` does not declare compatibility with.
+ */
+export function incompatiblePackages(theme: Theme, profile: UiProfile): string[] {
+    return profile.packages.filter(package_ => !theme.compatibleWith.includes(package_));
+}
+
+/**
+ * Whether a {@link Theme} is compatible with every package a {@link UiProfile} declares.
+ *
+ * @param theme The {@link Theme} to check.
+ * @param profile The {@link UiProfile} whose packages to check against.
+ * @returns `true` when `theme` declares compatibility with every package `profile` lists.
+ */
+export function isThemeCompatible(theme: Theme, profile: UiProfile): boolean {
+    return incompatiblePackages(theme, profile).length === 0;
+}
+
+/**
+ * Finds the packages a {@link Theme}'s tokens actually apply to for a given {@link UiProfile} - the
+ * packages the profile activates that the theme also declares compatibility with. This is what a
+ * renderer scopes token application to, rather than applying a theme's tokens globally - and is
+ * recomputed on every theme switch for the live re-resolution Cratis/Scene#5 requires (no reload).
+ *
+ * @param theme The {@link Theme} to apply.
+ * @param profile The active {@link UiProfile}.
+ * @returns The packages both active in `profile` and declared compatible by `theme`.
+ */
+export function applicableThemePackages(theme: Theme, profile: UiProfile): string[] {
+    return profile.packages.filter(package_ => theme.compatibleWith.includes(package_));
+}