create-three-blocks-starter 0.0.13 → 0.3.0-alpha.176.g8ff8a72e6369

package/dist/artifacts.js

@@ -0,0 +1,349 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { COMPATIBILITY_VERSIONS } from './constants.js';
+import { TEMPLATE_NAMES, } from './types.js';
+import { snapshotGeneratedShaderInputs } from './shader-inputs.js';
+const TEXT_FILES = [
+    'public/fonts/OFL-1.1.txt',
+    'public/fonts/geist.woff2',
+    'public/fonts/geist.msdf.json',
+    'public/fonts/geist.msdf.ktx2',
+    'public/fonts/geist.msdf.meta.json',
+    'public/fonts/noto-jp.woff2',
+    'public/fonts/noto-jp.msdf.json',
+    'public/fonts/noto-jp.msdf.ktx2',
+    'public/fonts/noto-jp.msdf.meta.json',
+];
+const SHADER_COMPATIBILITY = 'three-webgpu-r185-v1';
+const SHADER_ADDRESS_VERSION = 2;
+const SHADER_RECIPE_VERSION = 1;
+const SHADER_HYDRATION_VERSION = 2;
+const SHADER_TRANSFORM_VERSION = 3;
+const SHA256 = /^[a-f0-9]{64}$/u;
+const SAFE_VERSION = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,127}$/u;
+const MAX_MANIFEST_BYTES = 32 * 1_024 * 1_024;
+const MAX_RECEIPT_BYTES = 2 * 1_024 * 1_024;
+const MAX_INPUTS = 4_096;
+const MAX_ENTRIES = 4_096;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function bytes(content) {
+    return typeof content === 'string' ? Buffer.from(content, 'utf8') : content;
+}
+function text(content, label) {
+    try {
+        return typeof content === 'string' ? content : new TextDecoder('utf-8', { fatal: true }).decode(content);
+    }
+    catch {
+        throw new Error(`${label} must be valid UTF-8.`);
+    }
+}
+function sha256(content) {
+    return createHash('sha256').update(bytes(content)).digest('hex');
+}
+function nonNegativeInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative integer.`);
+    }
+    return value;
+}
+function safeRelativePath(value, label) {
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\\') || path.posix.isAbsolute(value)
+        || path.posix.normalize(value) !== value || value === '..' || value.startsWith('../')
+        || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new Error(`${label} must be a safe project-relative path.`);
+    }
+    return value;
+}
+function coverage(value, label) {
+    if (!isRecord(value))
+        throw new Error(`${label} is missing.`);
+    return {
+        render: nonNegativeInteger(value.render, `${label}.render`),
+        vertex: nonNegativeInteger(value.vertex, `${label}.vertex`),
+        fragment: nonNegativeInteger(value.fragment, `${label}.fragment`),
+        compute: nonNegativeInteger(value.compute, `${label}.compute`),
+    };
+}
+function parseInputs(value, template) {
+    if (!isRecord(value))
+        throw new Error(`Shader receipt inputs for "${template}" are invalid.`);
+    const entries = Object.entries(value);
+    if (entries.length === 0 || entries.length > MAX_INPUTS) {
+        throw new Error(`Shader receipt inputs for "${template}" must contain 1...${MAX_INPUTS} files.`);
+    }
+    const result = {};
+    for (const [inputPath, hash] of entries) {
+        safeRelativePath(inputPath, `Shader receipt input for "${template}"`);
+        if (typeof hash !== 'string' || !SHA256.test(hash))
+            throw new Error(`Shader receipt input hash for "${template}" is invalid.`);
+        result[inputPath] = hash;
+    }
+    return result;
+}
+function parseReceipt(template, content, versions) {
+    if (bytes(content).byteLength > MAX_RECEIPT_BYTES)
+        throw new Error(`Shader metadata for "${template}" exceeds ${MAX_RECEIPT_BYTES} bytes.`);
+    let value;
+    try {
+        value = JSON.parse(text(content, `Shader metadata for "${template}"`));
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.endsWith('must be valid UTF-8.'))
+            throw error;
+        throw new Error(`Shader metadata for "${template}" is not valid JSON.`);
+    }
+    if (!isRecord(value) || value.schemaVersion !== 2 || !isRecord(value.runtime)
+        || value.runtime.three !== versions.three || value.runtime.threeBlocks !== versions.threeBlocks) {
+        throw new Error(`Shader metadata for "${template}" has an incompatible schema or runtime version.`);
+    }
+    if (typeof value.runtime.threeBlocksShaderClosure !== 'string' || !SHA256.test(value.runtime.threeBlocksShaderClosure)) {
+        throw new Error(`Shader metadata for "${template}" has an invalid three-blocks shader runtime closure.`);
+    }
+    if (!isRecord(value.tool) || value.tool.name !== '@three-blocks/devtools'
+        || typeof value.tool.version !== 'string' || !SAFE_VERSION.test(value.tool.version)
+        || value.tool.compatibility !== SHADER_COMPATIBILITY
+        || value.tool.transform !== SHADER_TRANSFORM_VERSION || value.tool.address !== SHADER_ADDRESS_VERSION
+        || value.tool.recipe !== SHADER_RECIPE_VERSION || value.tool.hydration !== SHADER_HYDRATION_VERSION) {
+        throw new Error(`Shader metadata for "${template}" has incompatible public tool metadata.`);
+    }
+    if (!isRecord(value.scenes) || Object.keys(value.scenes).length !== 1 || !isRecord(value.scenes[template])) {
+        throw new Error(`Shader metadata for "${template}" must contain exactly that complete template scene.`);
+    }
+    const raw = value.scenes[template];
+    const expectedArtifact = `${template}.webgpu.ts`;
+    if (raw.artifact !== expectedArtifact || typeof raw.artifactHash !== 'string' || !SHA256.test(raw.artifactHash)) {
+        throw new Error(`Shader receipt for "${template}" references an invalid artifact.`);
+    }
+    const selectedCoverage = coverage(raw.coverage, `Shader coverage for "${template}"`);
+    if (selectedCoverage.render === 0 || selectedCoverage.vertex === 0 || selectedCoverage.fragment === 0) {
+        throw new Error(`Shader capture for "${template}" has no complete render pipeline coverage.`);
+    }
+    if (!isRecord(raw.skipped))
+        throw new Error(`Shader skipped-build counts for "${template}" are missing.`);
+    const skipped = {
+        render: nonNegativeInteger(raw.skipped.render, `Shader skipped render builds for "${template}"`),
+        compute: nonNegativeInteger(raw.skipped.compute, `Shader skipped compute builds for "${template}"`),
+    };
+    return {
+        schemaVersion: 2,
+        runtime: {
+            three: versions.three,
+            threeBlocks: versions.threeBlocks,
+            threeBlocksShaderClosure: value.runtime.threeBlocksShaderClosure,
+        },
+        tool: {
+            name: '@three-blocks/devtools',
+            version: value.tool.version,
+            compatibility: SHADER_COMPATIBILITY,
+            transform: SHADER_TRANSFORM_VERSION,
+            address: SHADER_ADDRESS_VERSION,
+            recipe: SHADER_RECIPE_VERSION,
+            hydration: SHADER_HYDRATION_VERSION,
+        },
+        scenes: {
+            [template]: {
+                artifact: expectedArtifact,
+                artifactHash: raw.artifactHash,
+                bytes: nonNegativeInteger(raw.bytes, `Shader artifact bytes for "${template}"`),
+                inputs: parseInputs(raw.inputs, template),
+                coverage: selectedCoverage,
+                skipped,
+            },
+        },
+    };
+}
+function parseManifestObject(template, content) {
+    const manifestBytes = bytes(content);
+    if (manifestBytes.byteLength === 0 || manifestBytes.byteLength > MAX_MANIFEST_BYTES) {
+        throw new Error(`Shader manifest for "${template}" must contain 1...${MAX_MANIFEST_BYTES} bytes.`);
+    }
+    const source = text(content, `Shader manifest for "${template}"`);
+    const exportDefault = source.indexOf('export default');
+    const firstBrace = source.indexOf('{', exportDefault);
+    const lastBrace = source.lastIndexOf('}');
+    if (exportDefault < 0 || firstBrace < 0 || lastBrace <= firstBrace) {
+        throw new Error(`Shader manifest for "${template}" is not a generated TypeScript manifest module.`);
+    }
+    for (const match of source.matchAll(/^\s*import(?:\s+type)?[\s\S]*?\sfrom\s+['"]([^'"]+)['"];?\s*$/gmu)) {
+        if (match[1] !== 'three-blocks/shaders')
+            throw new Error(`Shader manifest for "${template}" imports a non-runtime module.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(source.slice(firstBrace, lastBrace + 1));
+    }
+    catch {
+        throw new Error(`Shader manifest for "${template}" does not contain the deterministic JSON payload emitted by public devtools.`);
+    }
+    if (!isRecord(parsed))
+        throw new Error(`Shader manifest for "${template}" has no object payload.`);
+    return parsed;
+}
+function manifestCoverage(template, content, versions) {
+    const manifest = parseManifestObject(template, content);
+    if (manifest.version !== 3 || manifest.scene !== template || manifest.three !== versions.three || manifest.threeBlocks !== versions.threeBlocks
+        || !isRecord(manifest.runtime) || manifest.runtime.id !== SHADER_COMPATIBILITY
+        || manifest.runtime.address !== SHADER_ADDRESS_VERSION || manifest.runtime.recipe !== SHADER_RECIPE_VERSION
+        || manifest.runtime.hydration !== SHADER_HYDRATION_VERSION || !isRecord(manifest.entries)) {
+        throw new Error(`Shader manifest for "${template}" has an incompatible scene, runtime, or schema.`);
+    }
+    const entries = Object.entries(manifest.entries);
+    if (entries.length === 0 || entries.length > MAX_ENTRIES)
+        throw new Error(`Shader manifest for "${template}" must contain 1...${MAX_ENTRIES} entries.`);
+    const states = Array.isArray(manifest.states) ? manifest.states : [];
+    let render = 0;
+    let vertex = 0;
+    let fragment = 0;
+    let compute = 0;
+    for (const [key, stateIndex] of entries) {
+        const state = typeof stateIndex === 'number' ? states[stateIndex] : undefined;
+        if (!isRecord(state))
+            throw new Error(`Shader manifest entry "${key}" for "${template}" references an invalid state.`);
+        for (const stage of ['vertex', 'fragment', 'compute']) {
+            if (state[stage] !== null && typeof state[stage] !== 'number')
+                throw new Error(`Shader manifest entry "${key}" has an invalid ${stage} module reference.`);
+        }
+        const hasVertex = typeof state.vertex === 'number';
+        const hasFragment = typeof state.fragment === 'number';
+        const hasCompute = typeof state.compute === 'number';
+        if (!hasVertex && !hasFragment && !hasCompute)
+            throw new Error(`Shader manifest entry "${key}" has no shader stage.`);
+        if (hasVertex || hasFragment)
+            render++;
+        if (hasVertex)
+            vertex++;
+        if (hasFragment)
+            fragment++;
+        if (hasCompute)
+            compute++;
+    }
+    return { render, vertex, fragment, compute };
+}
+function sameCoverage(left, right) {
+    return left.render === right.render && left.vertex === right.vertex
+        && left.fragment === right.fragment && left.compute === right.compute;
+}
+/** Validate the exact pair emitted by public shader capture before it can become a fresh catalog payload. */
+export function validateShaderArtifactPayload(template, manifest, metadata, versions = COMPATIBILITY_VERSIONS) {
+    const receipt = parseReceipt(template, metadata, versions);
+    const selected = receipt.scenes[template];
+    if (selected === undefined)
+        throw new Error(`Shader receipt for "${template}" is missing.`);
+    if (selected.artifactHash !== sha256(manifest))
+        throw new Error(`Shader manifest checksum for "${template}" does not match metadata.`);
+    if (selected.bytes !== bytes(manifest).byteLength)
+        throw new Error(`Shader manifest byte count for "${template}" does not match metadata.`);
+    if (!sameCoverage(manifestCoverage(template, manifest, versions), selected.coverage)) {
+        throw new Error(`Shader manifest coverage for "${template}" does not match metadata.`);
+    }
+    return receipt;
+}
+export function shaderArtifactPaths(template) {
+    return [`.three-blocks/shaders/${template}.webgpu.ts`, '.three-blocks/shaders/meta.json'];
+}
+function loadShaderArtifact(template) {
+    const directory = new URL(`../template-assets/shaders/${template}/`, import.meta.url);
+    if (!existsSync(directory))
+        return {
+            status: 'pending',
+            files: [],
+            note: 'Pending verified shader capture; runtime behavior must not treat this descriptor as fresh.',
+        };
+    const directoryMetadata = lstatSync(directory);
+    if (directoryMetadata.isSymbolicLink() || !directoryMetadata.isDirectory())
+        throw new Error(`Shader template asset root for "${template}" must be a real directory.`);
+    const expected = [`${template}.webgpu.ts`, 'meta.json'];
+    const entries = readdirSync(directory, { withFileTypes: true });
+    if (entries.length === 0)
+        return {
+            status: 'pending',
+            files: [],
+            note: 'Pending verified shader capture; runtime behavior must not treat this descriptor as fresh.',
+        };
+    const unexpected = entries.filter((entry) => !expected.includes(entry.name)).map((entry) => entry.name);
+    if (unexpected.length > 0)
+        throw new Error(`Shader payload for "${template}" contains non-allowlisted files: ${unexpected.join(', ')}.`);
+    for (const expectedFile of expected) {
+        const entry = entries.find((candidate) => candidate.name === expectedFile);
+        if (entry === undefined || entry.isSymbolicLink() || !entry.isFile())
+            throw new Error(`Shader payload for "${template}" is incomplete: expected ${expected.join(' and ')}.`);
+    }
+    const manifest = readFileSync(new URL(`${template}.webgpu.ts`, directory));
+    const metadata = readFileSync(new URL('meta.json', directory));
+    const metadataValue = JSON.parse(text(metadata, `Shader metadata for "${template}"`));
+    if (isRecord(metadataValue) && isRecord(metadataValue.runtime) && metadataValue.runtime.threeBlocksShaderClosure === undefined) {
+        return {
+            status: 'pending',
+            files: [],
+            note: 'Existing capture predates shader-relevant closure receipts and must be recaptured.',
+        };
+    }
+    const receipt = validateShaderArtifactPayload(template, manifest, metadata);
+    const selected = receipt.scenes[template];
+    if (selected === undefined)
+        throw new Error(`Shader receipt for "${template}" is missing.`);
+    const targets = shaderArtifactPaths(template);
+    return {
+        status: 'fresh',
+        files: [
+            { path: targets[0], content: manifest, owner: 'generator' },
+            { path: targets[1], content: metadata, owner: 'generator' },
+        ],
+        note: `Captured complete ${template} template with ${selected.coverage.render} render and ${selected.coverage.compute} compute pipelines.`,
+    };
+}
+const SHADER_ARTIFACTS = Object.freeze(Object.fromEntries(TEMPLATE_NAMES.map((template) => [template, loadShaderArtifact(template)])));
+export function shaderArtifactFiles(template) {
+    return SHADER_ARTIFACTS[template].files;
+}
+export function shaderArtifactState(template) {
+    const artifact = SHADER_ARTIFACTS[template];
+    return { status: artifact.status, note: artifact.note };
+}
+/** Prove that a fresh payload was captured from the exact fully composed generated template. */
+export function validateShaderArtifactProject(template, files, versions) {
+    const targets = shaderArtifactPaths(template);
+    const manifest = files.get(targets[0]);
+    const metadata = files.get(targets[1]);
+    if (manifest === undefined || metadata === undefined)
+        throw new Error(`Fresh shader artifact for "${template}" is missing its allowlisted manifest or metadata.`);
+    const receipt = validateShaderArtifactPayload(template, manifest.content, metadata.content, versions);
+    const selected = receipt.scenes[template];
+    if (selected === undefined)
+        throw new Error(`Shader receipt for "${template}" is missing.`);
+    const current = snapshotGeneratedShaderInputs(files);
+    // Receipts hash the exact composed source bytes. Keep hash-relevant inputs
+    // ASCII so character representation stays explicit and stable across editors,
+    // archives, and capture runtimes; write other characters as source escapes.
+    for (const input of Object.keys(current)) {
+        const file = files.get(input);
+        if (file === undefined)
+            continue;
+        const content = typeof file.content === 'string' ? Buffer.from(file.content) : file.content;
+        if (content.some((byte) => byte > 0x7f)) {
+            throw new Error(`Shader semantic input "${input}" for "${template}" contains non-ASCII bytes; embed them as escape sequences so composition is runtime-independent.`);
+        }
+    }
+    const recorded = selected.inputs;
+    const changed = Object.keys(current).filter((input) => recorded[input] !== current[input]);
+    const removed = Object.keys(recorded).filter((input) => !Object.hasOwn(current, input));
+    if (changed.length > 0 || removed.length > 0) {
+        throw new Error(`Fresh shader artifact for "${template}" does not match its composed semantic inputs`
+            + ` (${changed.length} added/changed: ${changed.join(', ') || 'none'};`
+            + ` ${removed.length} removed: ${removed.join(', ') || 'none'}).`);
+    }
+}
+function textPayload(relativePath) {
+    return {
+        path: relativePath,
+        content: readFileSync(new URL(`../template-assets/text/${relativePath}`, import.meta.url)),
+        owner: 'generator',
+    };
+}
+export function textArtifactFiles() {
+    return TEXT_FILES.map(textPayload);
+}
+export const textArtifactPaths = TEXT_FILES;

package/dist/bin/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from '../cli.js';
+import { fail } from '../ui.js';
+runCli().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    fail(message);
+    process.exitCode = 1;
+});

package/dist/catalog.d.ts

@@ -0,0 +1,5 @@
+import { type TemplateCatalog, type TemplateInput, type TemplateName } from './types.js';
+export declare function defineTemplateCatalog(catalog: TemplateCatalog): TemplateCatalog;
+export declare const catalog: TemplateCatalog;
+export declare function resolveTemplateName(input: string | undefined, source?: TemplateCatalog): TemplateName;
+export declare function isTemplateInput(input: string): input is TemplateInput;

package/dist/catalog.js

@@ -0,0 +1,80 @@
+import { COMPATIBILITY_VERSIONS } from './constants.js';
+import { shaderArtifactPaths, shaderArtifactState, textArtifactPaths } from './artifacts.js';
+import { LEGACY_TEMPLATE_NAMES, TEMPLATE_NAMES, } from './types.js';
+export function defineTemplateCatalog(catalog) {
+    return catalog;
+}
+function shaderArtifact(template) {
+    const state = shaderArtifactState(template);
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: 'shader',
+        template,
+        status: state.status,
+        capturedWith: {
+            three: COMPATIBILITY_VERSIONS.three,
+            threeBlocks: COMPATIBILITY_VERSIONS.threeBlocks,
+        },
+        files: state.status === 'fresh' ? shaderArtifactPaths(template) : [],
+        note: state.note,
+    });
+}
+function freshTextArtifact() {
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: 'text',
+        template: 'text',
+        status: 'fresh',
+        capturedWith: {
+            three: COMPATIBILITY_VERSIONS.three,
+            threeBlocks: COMPATIBILITY_VERSIONS.threeBlocks,
+        },
+        files: textArtifactPaths,
+        note: 'Validated Geist and Noto Sans JP browser/MSDF outputs generated from the complete text template.',
+    });
+}
+export const catalog = defineTemplateCatalog({
+    schemaVersion: 2,
+    default: 'scene',
+    aliases: {
+        starter: 'scene',
+        minimal: 'scene',
+    },
+    versions: COMPATIBILITY_VERSIONS,
+    templates: {
+        scene: {
+            name: 'scene',
+            label: 'Minimal',
+            description: 'The Three Blocks mark as a pointer-reactive, worker-rendered WebGPU scene',
+            layers: ['core', 'scene'],
+            shaderArtifact: shaderArtifact('scene'),
+        },
+        website: {
+            name: 'website',
+            label: 'Website',
+            description: 'A semantic one-page site that proves worker rendering and precompiled shaders',
+            layers: ['core', 'website'],
+            shaderArtifact: shaderArtifact('website'),
+        },
+        text: {
+            name: 'text',
+            label: 'Text website',
+            description: 'A bilingual type specimen whose selectable DOM text renders on the GPU',
+            layers: ['core', 'website', 'text'],
+            shaderArtifact: shaderArtifact('text'),
+            textArtifact: freshTextArtifact(),
+        },
+    },
+});
+export function resolveTemplateName(input, source = catalog) {
+    const normalized = (input ?? source.default).trim().toLowerCase();
+    if (TEMPLATE_NAMES.includes(normalized))
+        return normalized;
+    if (LEGACY_TEMPLATE_NAMES.includes(normalized)) {
+        return source.aliases[normalized];
+    }
+    throw new Error(`Unknown template "${input}". Expected: ${TEMPLATE_NAMES.join(', ')}.`);
+}
+export function isTemplateInput(input) {
+    return [...TEMPLATE_NAMES, ...LEGACY_TEMPLATE_NAMES].includes(input);
+}

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+import { type PackageManager } from './generate.js';
+interface ParsedArguments {
+    directory: string | undefined;
+    template: string | undefined;
+    mode: string | undefined;
+    resultFile: string | undefined;
+    packageManager: PackageManager | undefined;
+    install: boolean | undefined;
+    git: boolean | undefined;
+    yes: boolean;
+    help: boolean;
+    version: boolean;
+}
+export declare function parseArguments(argv: readonly string[]): ParsedArguments;
+export declare function runCli(argv?: readonly string[]): Promise<void>;
+export {};

package/dist/cli.js

@@ -0,0 +1,122 @@
+import path from 'node:path';
+import { catalog, resolveTemplateName } from './catalog.js';
+import { GENERATOR_VERSION } from './constants.js';
+import { detectPackageManager, generateProject } from './generate.js';
+import { confirm, intro, printCompletion, printHelp, promptProjectDirectory, promptTemplate, step, theme, } from './ui.js';
+function valueAfter(argv, index, option) {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('-'))
+        throw new Error(`${option} requires a value.`);
+    return value;
+}
+export function parseArguments(argv) {
+    const result = {
+        directory: undefined,
+        template: undefined,
+        mode: undefined,
+        resultFile: undefined,
+        packageManager: undefined,
+        install: undefined,
+        git: undefined,
+        yes: false,
+        help: false,
+        version: false,
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        if (argument === undefined || argument === '--')
+            continue;
+        if (argument === '--help' || argument === '-h')
+            result.help = true;
+        else if (argument === '--version' || argument === '-v')
+            result.version = true;
+        else if (argument === '--yes' || argument === '-y')
+            result.yes = true;
+        else if (argument === '--install')
+            result.install = true;
+        else if (argument === '--no-install')
+            result.install = false;
+        else if (argument === '--git')
+            result.git = true;
+        else if (argument === '--no-git')
+            result.git = false;
+        else if (argument === '--template' || argument === '-t')
+            result.template = valueAfter(argv, index++, argument);
+        else if (argument.startsWith('--template='))
+            result.template = argument.slice('--template='.length);
+        else if (argument === '--mode' || argument === '-m')
+            result.mode = valueAfter(argv, index++, argument);
+        else if (argument.startsWith('--mode='))
+            result.mode = argument.slice('--mode='.length);
+        else if (argument === '--name' || argument === '-n')
+            result.directory = valueAfter(argv, index++, argument);
+        else if (argument.startsWith('--name='))
+            result.directory = argument.slice('--name='.length);
+        else if (argument === '--result-file')
+            result.resultFile = valueAfter(argv, index++, argument);
+        else if (argument.startsWith('--result-file='))
+            result.resultFile = argument.slice('--result-file='.length);
+        else if (argument === '--package-manager') {
+            const manager = valueAfter(argv, index++, argument);
+            if (manager !== 'bun' && manager !== 'npm' && manager !== 'pnpm')
+                throw new Error(`Unknown package manager "${manager}".`);
+            result.packageManager = manager;
+        }
+        else if (argument.startsWith('--package-manager=')) {
+            const manager = argument.slice('--package-manager='.length);
+            if (manager !== 'bun' && manager !== 'npm' && manager !== 'pnpm')
+                throw new Error(`Unknown package manager "${manager}".`);
+            result.packageManager = manager;
+        }
+        else if (argument.startsWith('-'))
+            throw new Error(`Unknown option "${argument}".`);
+        else if (result.directory === undefined)
+            result.directory = argument;
+        else
+            throw new Error(`Unexpected argument "${argument}".`);
+    }
+    if (result.template !== undefined && result.mode !== undefined)
+        throw new Error('Use either --template or --mode, not both.');
+    return result;
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    const args = parseArguments(argv);
+    if (args.help) {
+        printHelp(GENERATOR_VERSION);
+        return;
+    }
+    if (args.version) {
+        process.stdout.write(`${GENERATOR_VERSION}\n`);
+        return;
+    }
+    intro(GENERATOR_VERSION);
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !args.yes);
+    const directory = args.directory ?? (interactive ? await promptProjectDirectory() : 'my-three-blocks-app');
+    const requested = args.template ?? args.mode;
+    const template = requested === undefined && interactive ? await promptTemplate() : resolveTemplateName(requested, catalog);
+    if (template === null)
+        return;
+    const install = args.install ?? (interactive ? await confirm('Install dependencies?', true) : true);
+    const git = args.git ?? (interactive ? await confirm('Initialize Git with an initial commit?', true) : true);
+    const packageManager = args.packageManager ?? detectPackageManager();
+    const targetDirectory = path.resolve(process.cwd(), directory);
+    step(`Creating ${theme.bold(catalog.templates[template].label)} in ${theme.accent(directory)}`);
+    const outcome = await generateProject({
+        targetDirectory,
+        template,
+        install,
+        git,
+        packageManager,
+        ...(args.resultFile === undefined ? {} : { resultFile: args.resultFile }),
+    });
+    printCompletion({
+        projectName: outcome.project.name,
+        templateLabel: catalog.templates[template].label,
+        directory,
+        packageManager,
+        installed: install,
+        git,
+        shaderStatus: outcome.project.artifacts.shader.status,
+        ...(outcome.project.artifacts.text === undefined ? {} : { textStatus: outcome.project.artifacts.text.status }),
+    });
+}

package/dist/compose.d.ts

@@ -0,0 +1,10 @@
+import { type GeneratedMetadata, type LayerDefinition, type LayerName, type PackageManager, type ResolvedProject, type TemplateCatalog } from './types.js';
+export interface ResolveProjectOptions {
+    readonly catalog?: TemplateCatalog;
+    readonly layers?: Readonly<Record<LayerName, LayerDefinition>>;
+    readonly packageManager?: PackageManager;
+}
+export declare function normalizeProjectName(input: string): string;
+export declare function createMetadata(project: Omit<ResolvedProject, 'files'>): GeneratedMetadata;
+export declare function validateResolvedProject(project: ResolvedProject, source?: TemplateCatalog): void;
+export declare function resolveProject(templateInput: string | undefined, projectName: string, options?: ResolveProjectOptions): ResolvedProject;