@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/paletteShowcase.d.ts

@@ -0,0 +1,183 @@
+import { type ContinuumMaterialDefinition, type ContinuumPackage, type ContinuumPackageVersion, type ContinuumPackageVersionReference, type ContinuumSceneDependencyClosure, type RuntimeProfile } from '@hypersoniclabs/helix-manifest';
+import type { ScratchSceneDescription } from './continuum/authoring';
+import type { ScratchWorldPublicationFile } from './continuum/cli';
+import type { ContinuumObjectPublication } from './continuum/types';
+import { type ScenePackageCompilation } from './sceneElements/continuum';
+import { type PaletteShowcaseDeviceBudget } from './paletteShowcaseProfiles';
+export { PALETTE_SHOWCASE_DEFAULT_PROFILE, PALETTE_SHOWCASE_DEVICE_BUDGETS, type PaletteShowcaseDeviceBudget, type PaletteShowcaseProfileId, } from './paletteShowcaseProfiles';
+export declare const PALETTE_SHOWCASE_VERSION = "1.1.0";
+export declare const PALETTE_SHOWCASE_VARIANTS: readonly ["canonical", "practical", "weathered", "hero"];
+export declare const PALETTE_SHOWCASE_LEGACY_RELEASE: {
+    readonly world: {
+        readonly id: "e68b69b9-1d55-4321-88c7-bdc8dbebf889";
+        readonly version: "1.0.5";
+    };
+    readonly scenePackage: {
+        readonly packageId: "b45668d2-e837-5a37-be01-a08a6ca4d509";
+        readonly version: "1.0.5";
+        readonly manifestCid: "cid:sha256:e040c3c0524462f8c11e161ee778914015af1b12268b7b96e9cff44b92cf7681";
+        readonly documentCid: "cid:sha256:60a15bf898d595305254d8d316422dd8639224b0089e140ab1523199ccf9768f";
+    };
+    readonly runtimePackage: {
+        readonly packageId: "04120fb9-cfd8-5a24-9ce4-289778d06582";
+        readonly version: "1.0.5";
+        readonly manifestCid: "cid:sha256:71a68f6a01e6aa5ca958b032c0e7ec1b9b62b34c93501798c47fc5d757bd541f";
+    };
+};
+type PaletteParameter = {
+    key: string;
+    type: string;
+    default: string | number;
+    operation: string;
+    rendererSupport: 'rendered' | 'host-owned' | string;
+    safe: {
+        range?: [number, number];
+        gamut?: string;
+    };
+};
+type Channel = {
+    supported: boolean;
+    required?: boolean;
+};
+export type PaletteShowcaseFamily = {
+    id: string;
+    definitionVersion: string;
+    kind: string;
+    name: string;
+    category: string;
+    residency: 'core' | 'extended';
+    physical: {
+        tiling: {
+            repeatPerMeter: number;
+        };
+    };
+    shader: {
+        model: string;
+        defaults: {
+            roughness: number;
+            metallic: number;
+            normalScale: number;
+        };
+        channels: Record<string, Channel | undefined>;
+    };
+    parameters: PaletteParameter[];
+};
+export type PaletteShowcaseCatalog = {
+    contract: string;
+    schemaVersion: string;
+    palette: {
+        id: string;
+        version: string;
+    };
+    families: PaletteShowcaseFamily[];
+};
+export type PaletteShowcasePublicationLedger = {
+    palette: {
+        id: string;
+        version: string;
+    };
+    activeRelease: string;
+    families: Record<string, {
+        activeVersion: string;
+        versions: Record<string, {
+            packageRef: ContinuumPackageVersionReference;
+        }>;
+    }>;
+};
+export type PaletteShowcaseInput = {
+    palette: PaletteShowcaseCatalog;
+    ledger: PaletteShowcasePublicationLedger;
+    materialClosures: ContinuumSceneDependencyClosure[];
+    materialDefinitions: Record<string, ContinuumMaterialDefinition>;
+    runtime: PaletteShowcaseRuntimePackage;
+    worldId: string;
+    projectId: string;
+};
+type BindingVariation = {
+    tint: [number, number, number, number];
+    roughnessScale: number;
+    metallicScale: number;
+    normalScale: number;
+    emissiveScale: number;
+    opacity: number;
+    tilingScale: number;
+    targets: Record<string, number | [number, number, number, number]>;
+};
+export declare const PALETTE_SHOWCASE_CONTEXT_COUNT: number;
+export declare function paletteShowcaseRuntimeProfiles(): RuntimeProfile[];
+export type PaletteShowcaseMetrics = {
+    textureCount: number;
+    textureTransferBytes: number;
+    decodedGpuMiBEstimate: number;
+    programCount: number;
+    drawCalls: number;
+    transparentDrawCalls: number;
+    materialSlots: number;
+    uniqueMaterialBindings: number;
+};
+export type PaletteShowcasePage = {
+    id: string;
+    category: string;
+    familyIds: string[];
+    source: ScratchSceneDescription;
+    compilation: ScenePackageCompilation;
+    closure: ContinuumSceneDependencyClosure;
+    objects: ContinuumObjectPublication[];
+    packagePublication: {
+        slug: string;
+        visibility: 'public';
+    };
+    parameterTargets: Record<string, BindingVariation['targets']>;
+};
+export type PaletteShowcaseBudgetReceipt = {
+    contract: 'helix.palette-showcase-budget-receipt/2';
+    palette: {
+        id: string;
+        version: string;
+    };
+    showcaseVersion: string;
+    deviceSelection: 'host-selected; the Scene does not implement an in-world switcher';
+    accounting: {
+        scope: 'incremental one mounted page, excluding the root shell';
+        paletteReuseCredit: 'shared CIDs reduce transfer and residency; they do not reduce draw calls';
+    };
+    pages: Array<{
+        id: string;
+        familyCount: number;
+        profiles: Array<{
+            id: string;
+            metrics: PaletteShowcaseMetrics;
+            budget: PaletteShowcaseDeviceBudget;
+            failures: string[];
+            pass: boolean;
+        }>;
+    }>;
+};
+export type PaletteShowcasePublishOrder = {
+    contract: 'helix.palette-showcase-publish-order/1';
+    steps: Array<{
+        id: string;
+        kind: 'runtime-package' | 'scene-page' | 'world-release';
+        descriptor: string;
+        command: string;
+        dependsOn: string[];
+    }>;
+};
+export type PaletteShowcasePublicationPlan = {
+    runtime: PaletteShowcaseRuntimePackage;
+    pages: PaletteShowcasePage[];
+    world: ScratchWorldPublicationFile;
+    budgetReceipt: PaletteShowcaseBudgetReceipt;
+    publishOrder: PaletteShowcasePublishOrder;
+};
+export declare function createPaletteShowcasePublicationPlan(input: PaletteShowcaseInput): PaletteShowcasePublicationPlan;
+/** Backward-compatible entrypoint for callers that only need the root World descriptor. */
+export declare function createPaletteShowcaseDescriptor(input: PaletteShowcaseInput): ScratchWorldPublicationFile;
+export type PaletteShowcaseRuntimePackage = {
+    package: ContinuumPackage;
+    packageVersion: ContinuumPackageVersion;
+    reference: ContinuumPackageVersionReference;
+    closure: ContinuumSceneDependencyClosure;
+    objects: ContinuumObjectPublication[];
+};
+export declare function createPaletteShowcaseRuntimePackage(): PaletteShowcaseRuntimePackage;

package/dist/paletteShowcase.js

@@ -0,0 +1,454 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PALETTE_SHOWCASE_CONTEXT_COUNT = exports.PALETTE_SHOWCASE_LEGACY_RELEASE = exports.PALETTE_SHOWCASE_VARIANTS = exports.PALETTE_SHOWCASE_VERSION = exports.PALETTE_SHOWCASE_DEVICE_BUDGETS = exports.PALETTE_SHOWCASE_DEFAULT_PROFILE = void 0;
+exports.paletteShowcaseRuntimeProfiles = paletteShowcaseRuntimeProfiles;
+exports.createPaletteShowcasePublicationPlan = createPaletteShowcasePublicationPlan;
+exports.createPaletteShowcaseDescriptor = createPaletteShowcaseDescriptor;
+exports.createPaletteShowcaseRuntimePackage = createPaletteShowcaseRuntimePackage;
+const node_crypto_1 = require("node:crypto");
+const helix_manifest_1 = require("@hypersoniclabs/helix-manifest");
+const authoring_1 = require("./continuum/authoring");
+const identity_1 = require("./continuum/identity");
+const continuum_1 = require("./sceneElements/continuum");
+const paletteShowcaseProfiles_1 = require("./paletteShowcaseProfiles");
+var paletteShowcaseProfiles_2 = require("./paletteShowcaseProfiles");
+Object.defineProperty(exports, "PALETTE_SHOWCASE_DEFAULT_PROFILE", { enumerable: true, get: function () { return paletteShowcaseProfiles_2.PALETTE_SHOWCASE_DEFAULT_PROFILE; } });
+Object.defineProperty(exports, "PALETTE_SHOWCASE_DEVICE_BUDGETS", { enumerable: true, get: function () { return paletteShowcaseProfiles_2.PALETTE_SHOWCASE_DEVICE_BUDGETS; } });
+exports.PALETTE_SHOWCASE_VERSION = '1.1.0';
+exports.PALETTE_SHOWCASE_VARIANTS = ['canonical', 'practical', 'weathered', 'hero'];
+exports.PALETTE_SHOWCASE_LEGACY_RELEASE = {
+    world: { id: 'e68b69b9-1d55-4321-88c7-bdc8dbebf889', version: '1.0.5' },
+    scenePackage: {
+        packageId: 'b45668d2-e837-5a37-be01-a08a6ca4d509', version: '1.0.5',
+        manifestCid: 'cid:sha256:e040c3c0524462f8c11e161ee778914015af1b12268b7b96e9cff44b92cf7681',
+        documentCid: 'cid:sha256:60a15bf898d595305254d8d316422dd8639224b0089e140ab1523199ccf9768f',
+    },
+    runtimePackage: {
+        packageId: '04120fb9-cfd8-5a24-9ce4-289778d06582', version: '1.0.5',
+        manifestCid: 'cid:sha256:71a68f6a01e6aa5ca958b032c0e7ec1b9b62b34c93501798c47fc5d757bd541f',
+    },
+};
+const CONTEXT_EXHIBITS = [
+    { id: 'architecture.floor', familyId: 'polished-concrete', variant: 'practical', shape: 'box', position: [0, 0.12, 17], size: [16, 0.24, 12] },
+    { id: 'architecture.wall', familyId: 'red-brick', variant: 'hero', shape: 'box', position: [0, 3.2, 22], size: [16, 6.4, 0.45] },
+    { id: 'architecture.bench', familyId: 'light-oak', variant: 'practical', shape: 'box', position: [0, 1.1, 16], size: [6, 0.5, 1.8] },
+    { id: 'vehicle.body', familyId: 'vehicle-paint-metallic', variant: 'hero', shape: 'box', position: [0, 1.35, 18], size: [8.5, 1.55, 3.4] },
+    { id: 'vehicle.cabin', familyId: 'vehicle-glass', variant: 'practical', shape: 'box', position: [0.4, 2.45, 18], size: [4.2, 1.25, 2.9] },
+    { id: 'vehicle.tire.left', familyId: 'tire-rubber', variant: 'practical', shape: 'cylinder', position: [-3, 0.8, 18], size: [1.25, 0.7, 1.25], rotation: [0.7071068, 0, 0, 0.7071068] },
+    { id: 'vehicle.tire.right', familyId: 'tire-rubber', variant: 'practical', shape: 'cylinder', position: [3, 0.8, 18], size: [1.25, 0.7, 1.25], rotation: [0.7071068, 0, 0, 0.7071068] },
+    { id: 'vehicle.hub', familyId: 'chrome', variant: 'hero', shape: 'cylinder', position: [-3, 0.8, 18], size: [0.65, 0.76, 0.65], rotation: [0.7071068, 0, 0, 0.7071068] },
+    { id: 'character.head', familyId: 'skin-human', variant: 'practical', shape: 'sphere', position: [0, 5.8, 18], size: [1.35, 1.35, 1.35] },
+    { id: 'character.torso', familyId: 'technical-fabric-ripstop', variant: 'hero', shape: 'capsule', position: [0, 3.55, 18], size: [2.1, 3.25, 1.15] },
+    { id: 'character.boot', familyId: 'leather', variant: 'weathered', shape: 'capsule', position: [-0.65, 1.25, 18], size: [0.75, 2.2, 0.9] },
+    { id: 'electronics.shell', familyId: 'plastic-abs', variant: 'practical', shape: 'box', position: [0, 2.1, 18], size: [6.5, 4.2, 0.65] },
+    { id: 'electronics.screen', familyId: 'screen-oled', variant: 'hero', shape: 'box', position: [0, 2.2, 17.62], size: [5.5, 3.2, 0.08] },
+    { id: 'electronics.board', familyId: 'pcb-solder-mask', variant: 'hero', shape: 'box', position: [0, 0.9, 20], size: [4.8, 0.12, 3.4] },
+    { id: 'food.bread', familyId: 'food-bread-crust', variant: 'practical', shape: 'capsule', position: [-2.4, 1.05, 18], size: [2.1, 3.4, 1.7], rotation: [0, 0, 0.7071068, 0.7071068] },
+    { id: 'food.fruit', familyId: 'food-fruit-skin', variant: 'hero', shape: 'sphere', position: [0.3, 1.2, 18], size: [1.8, 1.8, 1.8] },
+    { id: 'food.cheese', familyId: 'food-cheese', variant: 'practical', shape: 'box', position: [2.8, 0.9, 18], size: [2.2, 1.6, 2] },
+    { id: 'scifi.portal', familyId: 'energy-emissive', variant: 'hero', shape: 'capsule', position: [-2.2, 3, 18], size: [0.75, 6, 0.75] },
+    { id: 'scifi.glass', familyId: 'clear-glass', variant: 'hero', shape: 'box', position: [0, 3, 18], size: [3.5, 5.5, 0.18] },
+];
+exports.PALETTE_SHOWCASE_CONTEXT_COUNT = CONTEXT_EXHIBITS.length;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+const CATEGORY_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PROFILE_CAPABILITIES = ['render.primitive/1', 'material.pbr/1', 'material.binding-parameters/1', 'material.metric-tiling/1', 'texture.ktx2/1'];
+const CATEGORY_TINTS = {
+    architecture: [0.94, 0.93, 0.9, 1], terrain: [0.9, 0.92, 0.86, 1], wood: [0.95, 0.86, 0.74, 1],
+    'stone-ceramic': [0.9, 0.93, 0.98, 1], metal: [0.82, 0.9, 1, 1], vehicle: [0.74, 0.86, 1, 1],
+    character: [1, 0.88, 0.84, 1], fabric: [0.82, 0.86, 1, 1], 'polymer-composite': [0.86, 0.95, 1, 1],
+    electronics: [0.72, 0.9, 1, 1], 'glass-liquid': [0.76, 0.92, 1, 0.82], 'paper-packaging': [1, 0.94, 0.8, 1],
+    'food-organic': [1, 0.84, 0.66, 1], 'fantasy-scifi': [0.74, 0.86, 1, 1], 'decal-layer': [0.92, 0.84, 1, 0.82],
+};
+function runtimeProfile(id, quality, capabilities) {
+    return {
+        schema: helix_manifest_1.CONTINUUM_RUNTIME_PROFILE_SCHEMA, id, platform: 'web', renderer: 'three-webgl2', quality,
+        contracts: { continuum: 1, scene: 2 }, capabilities: [...new Set([...PROFILE_CAPABILITIES, ...capabilities])].sort(),
+    };
+}
+function paletteShowcaseRuntimeProfiles() {
+    return paletteShowcaseProfiles_1.PALETTE_SHOWCASE_PROFILE_SPECS.map((profile) => runtimeProfile(profile.id, profile.quality, [...profile.capabilities]));
+}
+function packageKey(reference) {
+    return `${reference.packageId}\0${reference.version}\0${reference.manifestCid}`;
+}
+function reference(packageVersion) {
+    return { packageId: packageVersion.package.id, version: packageVersion.version, manifestCid: (0, helix_manifest_1.continuumPackageVersionCid)(packageVersion) };
+}
+function sameObject(a, b) {
+    return a.cid === b.cid && a.bytes === b.bytes && a.mediaType === b.mediaType && a.role === b.role;
+}
+function sceneClosure(compilation, dependencies) {
+    const objects = new Map([[compilation.packageVersion.root.cid, compilation.packageVersion.root]]);
+    for (const dependency of dependencies) {
+        for (const object of dependency.objects) {
+            const current = objects.get(object.cid);
+            if (current && !sameObject(current, object))
+                throw new TypeError(`CID ${object.cid} has conflicting descriptors`);
+            objects.set(object.cid, object);
+        }
+    }
+    return { package: reference(compilation.packageVersion), root: compilation.packageVersion.root, objects: [...objects.values()].sort((a, b) => a.cid.localeCompare(b.cid)) };
+}
+function assertInput(input) {
+    if (input.palette.contract !== 'helix-palette/4' || input.palette.schemaVersion !== '4')
+        throw new TypeError('Palette showcase requires the v4 Palette contract');
+    if (input.palette.families.length !== 256)
+        throw new TypeError(`Palette showcase requires exactly 256 families; received ${input.palette.families.length}`);
+    if (input.palette.palette.id !== input.ledger.palette.id || input.palette.palette.version !== input.ledger.activeRelease) {
+        throw new TypeError('Palette catalog and publication ledger do not describe the same active release');
+    }
+    const closureKeys = new Set(input.materialClosures.map((closure) => packageKey(closure.package)));
+    const familyIds = new Set();
+    for (const family of input.palette.families) {
+        if (!ID.test(family.id) || familyIds.has(family.id))
+            throw new TypeError(`Invalid or duplicate Palette family id "${family.id}"`);
+        if (!CATEGORY_ID.test(family.category))
+            throw new TypeError(`${family.id} has unsafe category "${family.category}"`);
+        familyIds.add(family.id);
+        if (!(family.physical.tiling.repeatPerMeter > 0))
+            throw new TypeError(`${family.id} requires positive repeatPerMeter`);
+        const published = input.ledger.families[family.id];
+        const packageRef = published?.versions[published.activeVersion]?.packageRef;
+        if (!packageRef)
+            throw new TypeError(`${family.id} has no active published Package reference`);
+        if (published.activeVersion !== family.definitionVersion)
+            throw new TypeError(`${family.id} definitionVersion does not match its active exact Package version`);
+        if (!closureKeys.has(packageKey(packageRef)))
+            throw new TypeError(`${family.id} is missing its exact dependency closure`);
+        if (!input.materialDefinitions[family.id])
+            throw new TypeError(`${family.id} is missing its exact material definition`);
+    }
+}
+function numericParameter(family, key) {
+    const parameter = family.parameters.find((candidate) => candidate.key === key);
+    return parameter?.rendererSupport === 'rendered' && typeof parameter.default === 'number' ? parameter : undefined;
+}
+function clamp(value, range) {
+    return range ? Math.min(range[1], Math.max(range[0], value)) : value;
+}
+function parameterTarget(family, key, multiplier, fallback) {
+    const parameter = numericParameter(family, key);
+    if (!parameter)
+        return fallback;
+    return clamp(parameter.default * multiplier, parameter.safe.range);
+}
+function safeRatio(target, base) {
+    return base === 0 ? 1 : target / base;
+}
+const VARIANT_SPECS = {
+    canonical: { roughness: 1, metallic: 1, normal: 1, emissive: 1, scale: 1, opacity: 1, tint: [1, 1, 1, 1] },
+    practical: { roughness: 0.86, metallic: 1.05, normal: 1.12, emissive: 1.25, scale: 1, opacity: 0.9 },
+    weathered: { roughness: 1.22, metallic: 0.78, normal: 1.35, emissive: 0.7, scale: 1, opacity: 0.78, tint: [0.68, 0.66, 0.62, 1] },
+    hero: { roughness: 0.72, metallic: 1.18, normal: 1.5, emissive: 1.8, scale: 0.5, opacity: 0.94, tint: [0.88, 0.94, 1, 1] },
+};
+function variation(family, definition, index) {
+    const variant = exports.PALETTE_SHOWCASE_VARIANTS[index];
+    const spec = VARIANT_SPECS[variant];
+    const tint = spec.tint ?? CATEGORY_TINTS[family.category] ?? [0.9, 0.92, 1, 1];
+    const roughness = parameterTarget(family, 'roughness', spec.roughness, definition.roughnessFactor);
+    const metallic = parameterTarget(family, 'metallic', spec.metallic, definition.metallicFactor);
+    const normal = parameterTarget(family, 'normalIntensity', spec.normal, definition.normalScale);
+    const emissive = parameterTarget(family, 'emissiveIntensity', spec.emissive, 1);
+    const opacity = parameterTarget(family, 'opacity', spec.opacity, 1);
+    const scale = parameterTarget(family, 'scale', spec.scale, 1);
+    return {
+        tint, roughnessScale: safeRatio(roughness, definition.roughnessFactor), metallicScale: safeRatio(metallic, definition.metallicFactor),
+        normalScale: safeRatio(normal, definition.normalScale), emissiveScale: emissive, opacity,
+        tilingScale: 1 / scale,
+        targets: { tint, roughness, metallic, normalIntensity: normal, emissiveIntensity: emissive, opacity, scale },
+    };
+}
+function displayShape(category, variantIndex) {
+    if (['architecture', 'terrain', 'wood', 'stone-ceramic', 'paper-packaging', 'decal-layer'].includes(category))
+        return 'box';
+    if (['metal', 'vehicle', 'polymer-composite', 'electronics'].includes(category))
+        return variantIndex % 2 === 0 ? 'sphere' : 'cylinder';
+    if (['character', 'fabric', 'food-organic'].includes(category))
+        return variantIndex % 2 === 0 ? 'capsule' : 'sphere';
+    return variantIndex % 2 === 0 ? 'sphere' : 'capsule';
+}
+function displaySize(shape) {
+    if (shape === 'box')
+        return [3.2, 2.5, 0.32];
+    if (shape === 'cylinder')
+        return [1.45, 2.6, 1.45];
+    if (shape === 'capsule')
+        return [1.35, 2.8, 1.35];
+    return [1.5, 1.5, 1.5];
+}
+function selectedTextureSet(definition, profile) {
+    const targetTier = profile.quality === 'minimum' ? 0 : profile.quality === 'balanced' ? 1 : 2;
+    const rank = (tier) => tier === 'proxy' ? 0 : tier === 'standard' ? 1 : 2;
+    const candidates = definition.variants.filter((variant) => variant.runtimeProfileId === profile.id).sort((a, b) => rank(a.tier) - rank(b.tier));
+    const selected = candidates.findLast((candidate) => rank(candidate.tier) <= targetTier) ?? candidates[0];
+    return { ...definition.textures, ...(selected?.textures ?? {}) };
+}
+function textureGpuBytes(texture) {
+    if (!texture.ktx2)
+        return texture.object.bytes * 4;
+    const mipFactor = texture.ktx2.mipLevels > 1 ? 4 / 3 : 1;
+    const bytesPerPixel = texture.ktx2.encoding === 'rgba8' ? 4 : 1;
+    return texture.ktx2.width * texture.ktx2.height * mipFactor * bytesPerPixel;
+}
+function deviceBudget(profileId) {
+    const spec = paletteShowcaseProfiles_1.PALETTE_SHOWCASE_PROFILE_SPECS.find((profile) => profile.id === profileId);
+    if (!spec)
+        throw new TypeError(`Unknown Palette showcase Runtime Profile ${profileId}`);
+    return paletteShowcaseProfiles_1.PALETTE_SHOWCASE_DEVICE_BUDGETS[spec.id];
+}
+function opacityBucket(definition, opacity) {
+    if (definition.opacity.mode === 'mask')
+        return 'mask';
+    return definition.opacity.mode === 'blend' || definition.surfaceModel === 'transparent-dielectric' || opacity < 1 ? 'blend' : 'opaque';
+}
+function pageMetrics(families, input, profile) {
+    const textures = new Map();
+    const programs = new Set();
+    const familyIds = new Set(families.map((family) => family.id));
+    let transparentDrawCalls = 0;
+    for (const family of families) {
+        const definition = input.materialDefinitions[family.id];
+        const selectedTextures = selectedTextureSet(definition, profile);
+        Object.values(selectedTextures).forEach((texture) => { if (texture)
+            textures.set(texture.object.cid, texture); });
+        const roles = Object.keys(selectedTextures).sort().join(',');
+        for (let index = 0; index < exports.PALETTE_SHOWCASE_VARIANTS.length; index += 1) {
+            const values = variation(family, definition, index);
+            const bucket = opacityBucket(definition, values.opacity);
+            programs.add([definition.shaderModel, definition.surfaceModel, bucket, definition.doubleSided, roles].join('|'));
+            if (bucket === 'blend')
+                transparentDrawCalls += 1;
+        }
+    }
+    const context = CONTEXT_EXHIBITS.filter((exhibit) => familyIds.has(exhibit.familyId));
+    for (const exhibit of context) {
+        const family = families.find((candidate) => candidate.id === exhibit.familyId);
+        const definition = input.materialDefinitions[family.id];
+        const values = variation(family, definition, exports.PALETTE_SHOWCASE_VARIANTS.indexOf(exhibit.variant));
+        if (opacityBucket(definition, values.opacity) === 'blend')
+            transparentDrawCalls += 1;
+    }
+    const drawCalls = families.length * exports.PALETTE_SHOWCASE_VARIANTS.length + context.length;
+    const gpuBytes = [...textures.values()].reduce((sum, texture) => sum + textureGpuBytes(texture), 0);
+    return {
+        textureCount: textures.size,
+        textureTransferBytes: [...textures.values()].reduce((sum, texture) => sum + texture.object.bytes, 0),
+        decodedGpuMiBEstimate: Number((gpuBytes / 1024 / 1024).toFixed(3)),
+        programCount: programs.size,
+        drawCalls,
+        transparentDrawCalls,
+        materialSlots: drawCalls,
+        uniqueMaterialBindings: families.length * exports.PALETTE_SHOWCASE_VARIANTS.length,
+    };
+}
+function budgetFailures(metrics, budget) {
+    const failures = [];
+    if (metrics.textureCount > budget.textures)
+        failures.push('textures');
+    if (metrics.textureTransferBytes > budget.residentTransferMiB * 1024 * 1024)
+        failures.push('textureTransferBytes');
+    if (metrics.decodedGpuMiBEstimate > budget.gpuTextureMiB)
+        failures.push('decodedGpuMiBEstimate');
+    if (metrics.programCount > budget.programs)
+        failures.push('programCount');
+    if (metrics.drawCalls > budget.drawCalls)
+        failures.push('drawCalls');
+    if (metrics.transparentDrawCalls > budget.transparentDraws)
+        failures.push('transparentDrawCalls');
+    if (metrics.materialSlots > budget.materialSlots)
+        failures.push('materialSlots');
+    return failures;
+}
+function fitsAllProfiles(families, input, profiles) {
+    return profiles.every((profile) => budgetFailures(pageMetrics(families, input, profile), deviceBudget(profile.id)).length === 0);
+}
+function pageFamilyGroups(input, profiles) {
+    const families = [...input.palette.families].sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+    const result = [];
+    for (const category of [...new Set(families.map((family) => family.category))].sort()) {
+        const categoryFamilies = families.filter((family) => family.category === category);
+        const pages = [];
+        for (const family of categoryFamilies) {
+            const current = pages.at(-1);
+            if (current && current.length < 12 && fitsAllProfiles([...current, family], input, profiles))
+                current.push(family);
+            else {
+                if (!fitsAllProfiles([family], input, profiles))
+                    throw new TypeError(`${family.id} cannot fit the strictest single-page device budget`);
+                pages.push([family]);
+            }
+        }
+        pages.forEach((page, index) => result.push({ id: `${category}-${String(index + 1).padStart(2, '0')}`, category, families: page }));
+    }
+    return result;
+}
+function pageSource(id, category, families, input) {
+    const materials = [];
+    const elements = [
+        { id: `page.${id}.root`, type: 'group', role: 'detail', collision: false, residency: { mode: 'distance', priority: 45 } },
+        { id: `page.${id}.light`, parentId: `page.${id}.root`, type: 'light', kind: 'point', color: '#f3f7ff', luminousIntensityCandela: 400, rangeM: 38, transform: { position: [0, 9, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] } },
+    ];
+    const targets = {};
+    const rows = Math.ceil(families.length / 3);
+    for (const [familyIndex, family] of families.entries()) {
+        const published = input.ledger.families[family.id];
+        const packageRef = published.versions[published.activeVersion].packageRef;
+        const cellX = (familyIndex % 3 - 1) * 16;
+        const cellZ = (Math.floor(familyIndex / 3) - (rows - 1) / 2) * 7;
+        for (let variantIndex = 0; variantIndex < exports.PALETTE_SHOWCASE_VARIANTS.length; variantIndex += 1) {
+            const variantName = exports.PALETTE_SHOWCASE_VARIANTS[variantIndex];
+            const materialId = `${family.id}.${variantName}`;
+            const values = variation(family, input.materialDefinitions[family.id], variantIndex);
+            targets[materialId] = values.targets;
+            materials.push({
+                id: materialId, sourcePackage: { ...packageRef },
+                description: { semanticName: `${family.name} ${variantName}`, roughness: family.shader.defaults.roughness, metalness: family.shader.defaults.metallic, opacityMode: values.opacity < 1 ? 'blend' : 'opaque', maps: [], shaderGraph: 'unknown' },
+                binding: { tint: values.tint, roughnessScale: values.roughnessScale, metallicScale: values.metallicScale, normalScale: values.normalScale, emissiveScale: values.emissiveScale, opacity: values.opacity, uv: { tiling: [values.tilingScale, values.tilingScale] } },
+            });
+            const shape = displayShape(category, variantIndex);
+            elements.push({
+                id: `sample.${family.id}.${variantName}`, parentId: `page.${id}.root`, type: 'primitive', shape, materialId,
+                transform: { position: [cellX + (variantIndex - 1.5) * 3.6, shape === 'box' ? 1.35 : 1.6, cellZ], rotation: [0, 0, 0, 1], scale: [1, 1, 1] }, size: displaySize(shape),
+            });
+        }
+    }
+    const familyIds = new Set(families.map((family) => family.id));
+    for (const exhibit of CONTEXT_EXHIBITS.filter((candidate) => familyIds.has(candidate.familyId))) {
+        elements.push({
+            id: `context.${exhibit.id}`, parentId: `page.${id}.root`, type: 'primitive', shape: exhibit.shape,
+            materialId: `${exhibit.familyId}.${exhibit.variant}`,
+            transform: { position: exhibit.position, rotation: exhibit.rotation ?? [0, 0, 0, 1], scale: [1, 1, 1] }, size: exhibit.size,
+        });
+    }
+    return { source: { id: `helix-palette-showcase-${id}`, title: `HELIX Palette — ${category}`, materials, canonicalMaterialPackages: {}, elements }, targets };
+}
+function createPaletteShowcasePublicationPlan(input) {
+    assertInput(input);
+    const profiles = paletteShowcaseRuntimeProfiles();
+    const familyById = new Map(input.palette.families.map((family) => [family.id, family]));
+    const closureByKey = new Map(input.materialClosures.map((closure) => [packageKey(closure.package), closure]));
+    const pages = pageFamilyGroups(input, profiles).map((group) => {
+        const dependencies = group.families.map((family) => {
+            const published = input.ledger.families[family.id];
+            return closureByKey.get(packageKey(published.versions[published.activeVersion].packageRef));
+        });
+        const { source, targets } = pageSource(group.id, group.category, group.families, input);
+        const imported = (0, authoring_1.importScratchScene)(source);
+        const compilation = (0, continuum_1.compileContinuumScenePackage)({
+            document: imported.document,
+            packageId: (0, identity_1.deterministicContinuumUuid)(`helix.palette.showcase.scene.page.${group.id}`),
+            version: exports.PALETTE_SHOWCASE_VERSION,
+            provenance: { kind: 'generated', source: `HELIX Palette ${input.palette.palette.version}`, sourceId: source.id },
+            dependencyClosures: dependencies,
+            runtimeProfiles: profiles,
+        });
+        const objects = [{
+                reference: compilation.packageVersion.root,
+                source: { kind: 'inline', bytes: compilation.sceneDocumentBytes, filename: `${group.id}.scene.json`, audience: 'public' },
+            }];
+        return {
+            id: group.id, category: group.category, familyIds: group.families.map((family) => family.id), source, compilation,
+            closure: sceneClosure(compilation, dependencies), objects,
+            packagePublication: { slug: `helix-palette-showcase-${group.id}`, visibility: 'public' }, parameterTargets: targets,
+        };
+    });
+    const groundFamily = input.palette.families.find((family) => family.id === 'polished-concrete') ?? input.palette.families[0];
+    const groundPublished = input.ledger.families[groundFamily.id];
+    const groundReference = groundPublished.versions[groundPublished.activeVersion].packageRef;
+    const groundClosure = closureByKey.get(packageKey(groundReference));
+    const rootMaterials = [{
+            id: `${groundFamily.id}.root`, sourcePackage: { ...groundReference },
+            description: { semanticName: `${groundFamily.name} root`, roughness: groundFamily.shader.defaults.roughness, metalness: groundFamily.shader.defaults.metallic, opacityMode: 'opaque', maps: [], shaderGraph: 'unknown' },
+            binding: { tint: [1, 1, 1, 1], roughnessScale: 1, metallicScale: 1, normalScale: 1, emissiveScale: 1, opacity: 1, uv: { tiling: [1, 1] } },
+        }];
+    const columns = Math.ceil(Math.sqrt(pages.length));
+    const spacing = 110;
+    const elements = [
+        { id: 'showcase.root', type: 'building', role: 'exterior', collision: true, residency: { mode: 'eager', priority: 100 } },
+        { id: 'showcase.ground', parentId: 'showcase.root', type: 'primitive', shape: 'box', materialId: `${groundFamily.id}.root`, transform: { position: [0, -0.2, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] }, size: [columns * spacing + 70, 0.4, Math.ceil(pages.length / columns) * spacing + 70] },
+        { id: 'spawn.palette', parentId: 'showcase.root', type: 'gameplay-anchor', anchor: 'spawn.palette', transform: { position: [0, 0.4, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] }, runtimeModule: input.runtime.reference },
+        { id: 'light.sun', parentId: 'showcase.root', type: 'light', kind: 'directional', color: '#fff4e5', illuminanceLux: 3.1, transform: { position: [30, 70, 24], rotation: [-0.31, 0.29, 0.1, 0.9], scale: [1, 1, 1] } },
+    ];
+    pages.forEach((page, index) => {
+        const x = (index % columns - (columns - 1) / 2) * spacing;
+        const z = (Math.floor(index / columns) - (Math.ceil(pages.length / columns) - 1) / 2) * spacing;
+        const groupId = `mount.${page.id}`;
+        elements.push({ id: groupId, parentId: 'showcase.root', type: 'group', role: 'detail', collision: false, residency: { mode: 'distance', priority: page.familyIds.some((id) => familyById.get(id)?.residency === 'core') ? 65 : 35 }, transform: { position: [x, 0, z], rotation: [0, 0, 0, 1], scale: [1, 1, 1] } });
+        elements.push({ id: `${groupId}.scene`, parentId: groupId, type: 'child-scene', mount: page.id, scene: reference(page.compilation.packageVersion), transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] } });
+    });
+    const source = { id: 'helix-palette-showcase', title: 'HELIX Palette', materials: rootMaterials, canonicalMaterialPackages: {}, elements };
+    const rootDependencies = [groundClosure, input.runtime.closure, ...pages.map((page) => page.closure)];
+    const sourceDigestSeed = (0, helix_manifest_1.canonicalJsonBytes)({ contract: 'helix.palette-showcase-source/2', palette: input.palette.palette, worldId: input.worldId, projectId: input.projectId, source, pagePackages: pages.map((page) => page.closure.package), runtimeProfiles: profiles });
+    const world = {
+        projectId: input.projectId,
+        sourceDigest: (0, node_crypto_1.createHash)('sha256').update(sourceDigestSeed).digest('hex'),
+        source,
+        compilation: {
+            packageId: (0, identity_1.deterministicContinuumUuid)('helix.palette.showcase.scene'), version: exports.PALETTE_SHOWCASE_VERSION,
+            provenance: { kind: 'generated', source: `HELIX Palette ${input.palette.palette.version}`, sourceId: 'helix-palette-showcase' },
+            dependencyClosures: rootDependencies, runtimeProfiles: profiles, gameplayPackages: [input.runtime.reference],
+            world: { releaseId: (0, identity_1.deterministicContinuumUuid)(`helix.palette.showcase.release.${exports.PALETTE_SHOWCASE_VERSION}`), worldId: input.worldId, maxPlayers: 24, contentRating: 'everyone', requiredCapabilities: ['render.primitive/1'] },
+        },
+        packagePublication: { slug: 'helix-palette-showcase', visibility: 'public' },
+        defaultRuntimeProfileId: paletteShowcaseProfiles_1.PALETTE_SHOWCASE_DEFAULT_PROFILE, objects: [], listings: [],
+    };
+    const budgetReceipt = {
+        contract: 'helix.palette-showcase-budget-receipt/2', palette: { ...input.palette.palette }, showcaseVersion: exports.PALETTE_SHOWCASE_VERSION,
+        deviceSelection: 'host-selected; the Scene does not implement an in-world switcher',
+        accounting: { scope: 'incremental one mounted page, excluding the root shell', paletteReuseCredit: 'shared CIDs reduce transfer and residency; they do not reduce draw calls' },
+        pages: pages.map((page) => {
+            const pageFamilies = page.familyIds.map((id) => familyById.get(id));
+            return {
+                id: page.id, familyCount: page.familyIds.length,
+                profiles: profiles.map((profile) => {
+                    const metrics = pageMetrics(pageFamilies, input, profile);
+                    const budget = deviceBudget(profile.id);
+                    const failures = budgetFailures(metrics, budget);
+                    return { id: profile.id, metrics, budget, failures, pass: failures.length === 0 };
+                }),
+            };
+        }),
+    };
+    const publishOrder = {
+        contract: 'helix.palette-showcase-publish-order/1',
+        steps: [
+            { id: 'runtime', kind: 'runtime-package', descriptor: 'runtime.publish.json', command: 'helix continuum publish-package runtime.publish.json', dependsOn: [] },
+            ...pages.map((page) => ({ id: `page:${page.id}`, kind: 'scene-page', descriptor: `pages/${page.id}.publish.json`, command: `helix continuum publish-package pages/${page.id}.publish.json`, dependsOn: [] })),
+            { id: 'world', kind: 'world-release', descriptor: 'world.publish.json', command: 'helix continuum publish-scratch world.publish.json', dependsOn: ['runtime', ...pages.map((page) => `page:${page.id}`)] },
+        ],
+    };
+    return { runtime: input.runtime, pages, world, budgetReceipt, publishOrder };
+}
+/** Backward-compatible entrypoint for callers that only need the root World descriptor. */
+function createPaletteShowcaseDescriptor(input) {
+    return createPaletteShowcasePublicationPlan(input).world;
+}
+function createPaletteShowcaseRuntimePackage() {
+    const definitions = [
+        ['runtime', 'application/vnd.helix.runtime-module+json;version=1', 'runtime-module', { schema: 'helix.runtime-module/1', entry: 'palette.showcase.spawn', behavior: 'spawn-anchor' }],
+        ['publisher', 'application/vnd.helix.attestation+json', 'publisher-attestation', { schema: 'helix.attestation/1', kind: 'publisher', authority: 'HELIX' }],
+        ['source', 'application/vnd.helix.attestation+json', 'source-attestation', { schema: 'helix.attestation/1', kind: 'source', source: 'HELIX Palette Showcase' }],
+    ];
+    const objects = definitions.map(([name, mediaType, role, value]) => {
+        const bytes = (0, helix_manifest_1.canonicalJsonBytes)(value);
+        const objectReference = { cid: (0, helix_manifest_1.cidFromBytes)(bytes), bytes: bytes.byteLength, mediaType, role };
+        return { reference: objectReference, source: { kind: 'inline', bytes, filename: `palette-showcase-${name}.json`, audience: 'public' } };
+    });
+    const pkg = { schema: helix_manifest_1.CONTINUUM_PACKAGE_SCHEMA, id: (0, identity_1.deterministicContinuumUuid)('helix.palette.showcase.runtime'), type: 'runtime-module', name: 'HELIX Palette Showcase Runtime' };
+    const packageVersion = {
+        schema: helix_manifest_1.CONTINUUM_PACKAGE_VERSION_SCHEMA, package: { id: pkg.id, type: pkg.type }, version: exports.PALETTE_SHOWCASE_VERSION,
+        root: objects[0].reference, dependencies: [], variants: [], compatibility: { contract: 'helix.runtime-module/1', requires: [], provides: ['spawn-anchor/1'] },
+        provenance: { kind: 'authored', source: 'HELIX Palette Showcase', sourceId: 'palette.showcase.spawn' },
+        expectedClosure: { objectCount: objects.length, totalBytes: objects.reduce((sum, object) => sum + object.reference.bytes, 0) },
+        runtimeModule: {
+            kind: 'system', targets: ['client-worker'], capabilities: { required: [], optional: [] },
+            budget: { memoryMiB: 8, cpuMsPerTick: 1, stateBytes: 4096, networkBytesPerSecond: 1024 },
+            publisherAttestation: objects[1].reference, sourceAttestation: objects[2].reference,
+        },
+    };
+    const packageReference = reference(packageVersion);
+    const closure = { package: packageReference, root: packageVersion.root, objects: objects.map((object) => object.reference) };
+    return { package: pkg, packageVersion, reference: packageReference, closure, objects };
+}
+//# sourceMappingURL=paletteShowcase.js.map