pixifact 0.4.0 → 0.6.0

package/dist/compiler-node/runtimeVite.js

@@ -0,0 +1,420 @@
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pixifactRuntimeProtocolVersion, } from '../runtime-dev/protocol.js';
+export const runtimeSessionProtocolVersion = pixifactRuntimeProtocolVersion;
+const runtimeAnnounceEvent = 'pixifact:runtime:announce';
+const runtimeRequestEvent = 'pixifact:runtime:request';
+const runtimeResponseEvent = 'pixifact:runtime:response';
+const runtimeApiRoot = '/__pixifact_runtime__';
+const virtualRuntimeClientId = 'virtual:pixifact-runtime-client';
+const resolvedVirtualRuntimeClientId = `\0${virtualRuntimeClientId}`;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function jsonResponse(value, status = 200) {
+    return Response.json(value, { status });
+}
+function authorizationMatches(request, token) {
+    return request.headers.get('authorization') === `Bearer ${token}`;
+}
+function isRuntimePageDescriptor(value) {
+    return isRecord(value)
+        && typeof value.runtimeId === 'string'
+        && value.runtimeId.length > 0
+        && typeof value.url === 'string'
+        && typeof value.title === 'string'
+        && typeof value.ready === 'boolean';
+}
+function isRuntimeHmrResponse(value) {
+    if (!isRecord(value)
+        || typeof value.requestId !== 'string'
+        || typeof value.runtimeId !== 'string'
+        || typeof value.ok !== 'boolean') {
+        return false;
+    }
+    return value.ok ? 'result' in value : typeof value.error === 'string';
+}
+function isRuntimeRequest(value) {
+    if (!isRecord(value) || typeof value.type !== 'string')
+        return false;
+    if (value.type === 'tree' || value.type === 'state')
+        return true;
+    if (value.type === 'node')
+        return Number.isInteger(value.uid) && Number(value.uid) >= 0;
+    if (value.type === 'logs') {
+        return (value.after === undefined || (Number.isInteger(value.after) && Number(value.after) >= 0))
+            && (value.level === undefined || ['debug', 'log', 'info', 'warn', 'error'].includes(String(value.level)));
+    }
+    if (value.type !== 'input' || typeof value.action !== 'string')
+        return false;
+    if (value.action === 'click' || value.action === 'move') {
+        return typeof value.x === 'number' && typeof value.y === 'number';
+    }
+    return ['key', 'keydown', 'keyup'].includes(value.action)
+        && typeof value.key === 'string'
+        && value.key.length > 0;
+}
+export function createRuntimeHostSession(options) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? 5_000;
+    const now = options.now ?? (() => new Date());
+    const sockets = new Set();
+    const runtimeIdBySocket = new Map();
+    const runtimes = new Map();
+    const pending = new Map();
+    let requestSequence = 0;
+    function settle(requestId, response) {
+        const current = pending.get(requestId);
+        if (!current)
+            return;
+        pending.delete(requestId);
+        clearTimeout(current.timeout);
+        current.resolve(response);
+    }
+    function removeSocketRuntime(socket) {
+        const runtimeId = runtimeIdBySocket.get(socket);
+        if (!runtimeId)
+            return;
+        runtimeIdBySocket.delete(socket);
+        if (runtimes.get(runtimeId)?.socket === socket)
+            runtimes.delete(runtimeId);
+    }
+    function open(socket) {
+        sockets.add(socket);
+    }
+    function close(socket) {
+        sockets.delete(socket);
+        removeSocketRuntime(socket);
+        for (const [requestId, current] of pending) {
+            if (current.socket === socket) {
+                settle(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Pixifact Runtime page disconnected during the request.',
+                }, 409));
+            }
+        }
+    }
+    function message(socket, event, data) {
+        if (!sockets.has(socket))
+            return;
+        if (event === runtimeAnnounceEvent) {
+            if (!isRuntimePageDescriptor(data)) {
+                throw new Error('Pixifact Runtime page descriptor is invalid.');
+            }
+            const previousId = runtimeIdBySocket.get(socket);
+            const previous = runtimes.get(data.runtimeId);
+            if (previousId && previousId !== data.runtimeId)
+                runtimes.delete(previousId);
+            if (previous && previous.socket !== socket)
+                runtimeIdBySocket.delete(previous.socket);
+            runtimeIdBySocket.set(socket, data.runtimeId);
+            runtimes.set(data.runtimeId, {
+                ...data,
+                connectedAt: previous?.connectedAt ?? now().toISOString(),
+                socket,
+            });
+            return;
+        }
+        if (event !== runtimeResponseEvent || !isRuntimeHmrResponse(data))
+            return;
+        const current = pending.get(data.requestId);
+        if (!current || current.socket !== socket || current.runtimeId !== data.runtimeId)
+            return;
+        settle(data.requestId, data.ok
+            ? jsonResponse(data.result)
+            : jsonResponse({ ok: false, error: data.error }, 422));
+    }
+    async function fetchRequest(request) {
+        const pathname = new URL(request.url).pathname;
+        if (!pathname.startsWith(`${runtimeApiRoot}/`))
+            return undefined;
+        if (!authorizationMatches(request, options.token)) {
+            return jsonResponse({
+                ok: false,
+                error: 'Pixifact Runtime session token is invalid.',
+            }, 401);
+        }
+        if (pathname === `${runtimeApiRoot}/health`) {
+            return jsonResponse({
+                protocolVersion: runtimeSessionProtocolVersion,
+                projectRoot: options.projectRoot,
+            });
+        }
+        if (pathname === `${runtimeApiRoot}/list`) {
+            return jsonResponse({
+                ok: true,
+                runtimes: [...runtimes.values()]
+                    .map(({ socket: _socket, ...runtime }) => runtime)
+                    .sort((left, right) => left.connectedAt.localeCompare(right.connectedAt)),
+            });
+        }
+        if (pathname !== `${runtimeApiRoot}/request`)
+            return undefined;
+        if (request.method !== 'POST') {
+            return jsonResponse({ ok: false, error: 'Pixifact Runtime requests require POST.' }, 405);
+        }
+        const body = await request.json();
+        if (!isRecord(body) || typeof body.runtimeId !== 'string' || !isRuntimeRequest(body.request)) {
+            return jsonResponse({ ok: false, error: 'Pixifact Runtime request is invalid.' }, 400);
+        }
+        const runtime = runtimes.get(body.runtimeId);
+        if (!runtime) {
+            return jsonResponse({
+                ok: false,
+                error: `Pixifact Runtime "${body.runtimeId}" is not connected.`,
+            }, 404);
+        }
+        const requestId = `runtime-${++requestSequence}`;
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                settle(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Pixifact Runtime request timed out.',
+                }, 504));
+            }, requestTimeoutMs);
+            pending.set(requestId, {
+                resolve,
+                runtimeId: runtime.runtimeId,
+                socket: runtime.socket,
+                timeout,
+            });
+            runtime.socket.send(runtimeRequestEvent, {
+                requestId,
+                runtimeId: runtime.runtimeId,
+                request: body.request,
+            });
+        });
+    }
+    return {
+        open,
+        close,
+        message,
+        fetch: fetchRequest,
+    };
+}
+export function defaultRuntimeSessionsRoot() {
+    return path.join(os.tmpdir(), 'pixifact', 'runtime-sessions');
+}
+export function runtimeSessionDescriptorPath(projectRoot, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const canonicalRoot = fs.realpathSync(projectRoot);
+    const projectHash = createHash('sha256').update(canonicalRoot).digest('hex');
+    return path.join(sessionsRoot, `${projectHash}.json`);
+}
+function isLoopbackOrigin(origin) {
+    const hostname = new URL(origin).hostname;
+    return hostname === 'localhost' || hostname === '::1' || hostname.startsWith('127.');
+}
+function validateRuntimeSessionDescriptor(value) {
+    if (!isRecord(value)
+        || value.protocolVersion !== runtimeSessionProtocolVersion
+        || typeof value.projectRoot !== 'string'
+        || typeof value.pid !== 'number'
+        || typeof value.origin !== 'string'
+        || typeof value.token !== 'string'
+        || !isLoopbackOrigin(value.origin)) {
+        throw new Error('Pixifact Runtime session descriptor is invalid.');
+    }
+    return value;
+}
+export function readRuntimeSessionDescriptor(projectRoot, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const descriptorPath = runtimeSessionDescriptorPath(projectRoot, sessionsRoot);
+    if (!fs.existsSync(descriptorPath))
+        return undefined;
+    return validateRuntimeSessionDescriptor(JSON.parse(fs.readFileSync(descriptorPath, 'utf8')));
+}
+export function writeRuntimeSessionDescriptor(descriptor, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const canonicalRoot = fs.realpathSync(descriptor.projectRoot);
+    const stored = validateRuntimeSessionDescriptor({ ...descriptor, projectRoot: canonicalRoot });
+    fs.mkdirSync(sessionsRoot, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(runtimeSessionDescriptorPath(canonicalRoot, sessionsRoot), `${JSON.stringify(stored, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+}
+export function removeRuntimeSessionDescriptor(descriptor, sessionsRoot = defaultRuntimeSessionsRoot()) {
+    const descriptorPath = runtimeSessionDescriptorPath(descriptor.projectRoot, sessionsRoot);
+    if (!fs.existsSync(descriptorPath))
+        return;
+    const current = readRuntimeSessionDescriptor(descriptor.projectRoot, sessionsRoot);
+    if (current?.token === descriptor.token)
+        fs.unlinkSync(descriptorPath);
+}
+function validateRuntimeHealth(value) {
+    if (!isRecord(value)
+        || value.protocolVersion !== runtimeSessionProtocolVersion
+        || typeof value.projectRoot !== 'string') {
+        throw new Error('Pixifact Runtime Host health response is invalid.');
+    }
+    return value;
+}
+export async function findActiveRuntimeSession(options) {
+    const projectRoot = fs.realpathSync(options.projectRoot);
+    const descriptor = readRuntimeSessionDescriptor(projectRoot, options.sessionsRoot);
+    if (!descriptor)
+        return undefined;
+    if (descriptor.projectRoot !== projectRoot) {
+        throw new Error('Pixifact Runtime session belongs to a different project.');
+    }
+    const fetcher = options.fetch ?? fetch;
+    try {
+        const response = await fetcher(`${descriptor.origin}${runtimeApiRoot}/health`, {
+            headers: { authorization: `Bearer ${descriptor.token}` },
+        });
+        if (!response.ok)
+            return undefined;
+        const health = validateRuntimeHealth(await response.json());
+        if (health.projectRoot !== projectRoot) {
+            throw new Error('Pixifact Runtime Host health check returned a different project.');
+        }
+        return descriptor;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('different project'))
+            throw error;
+        return undefined;
+    }
+}
+export async function claimRuntimeSession(options) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const current = readRuntimeSessionDescriptor(options.projectRoot, options.sessionsRoot);
+        const active = await findActiveRuntimeSession(options);
+        if (active)
+            return { descriptor: active, owned: false };
+        if (current)
+            removeRuntimeSessionDescriptor(current, options.sessionsRoot);
+        try {
+            writeRuntimeSessionDescriptor(options.descriptor, options.sessionsRoot);
+            return { descriptor: options.descriptor, owned: true };
+        }
+        catch (error) {
+            if (!isRecord(error) || error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    throw new Error('Pixifact Runtime session could not be registered.');
+}
+function projectRootPath(projectRoot, viteRoot) {
+    if (typeof projectRoot === 'string')
+        return projectRoot;
+    if (projectRoot)
+        return fileURLToPath(projectRoot);
+    return viteRoot;
+}
+function serverOrigin(server) {
+    const address = server.httpServer?.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Pixifact Runtime requires a listening Vite HTTP server.');
+    }
+    if (!(address.address === '::1' || address.address.startsWith('127.'))) {
+        throw new Error('Pixifact Runtime requires the Vite server to bind to a loopback address.');
+    }
+    const hostname = address.address === '::1' ? '[::1]' : address.address;
+    const protocol = server.config.server.https ? 'https' : 'http';
+    return `${protocol}://${hostname}:${address.port}`;
+}
+async function webRequestFromNode(request, origin) {
+    const chunks = [];
+    for await (const chunk of request) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    const body = chunks.length > 0 ? Buffer.concat(chunks) : undefined;
+    return new Request(new URL(request.url ?? '/', origin), {
+        method: request.method,
+        headers: request.headers,
+        ...(body ? { body } : {}),
+    });
+}
+async function writeNodeResponse(response, result) {
+    response.statusCode = result.status;
+    result.headers.forEach((value, name) => response.setHeader(name, value));
+    response.end(Buffer.from(await result.arrayBuffer()));
+}
+export function pixifactRuntimePlugin(options = {}) {
+    let projectRoot = '';
+    const token = randomBytes(32).toString('hex');
+    return {
+        name: 'pixifact-runtime',
+        apply: 'serve',
+        configResolved(config) {
+            projectRoot = fs.realpathSync(projectRootPath(options.projectRoot, config.root));
+        },
+        resolveId(id) {
+            return id === virtualRuntimeClientId ? resolvedVirtualRuntimeClientId : undefined;
+        },
+        load(id) {
+            if (id !== resolvedVirtualRuntimeClientId)
+                return undefined;
+            return [
+                "const runtimeHotKey = Symbol.for('pixifact.runtime.hot');",
+                'globalThis[runtimeHotKey] = import.meta.hot;',
+                "await import('pixifact/runtime-dev');",
+                'delete globalThis[runtimeHotKey];',
+            ].join('\n');
+        },
+        transformIndexHtml() {
+            return [{
+                    tag: 'script',
+                    attrs: {
+                        type: 'module',
+                        src: `/@id/${virtualRuntimeClientId}`,
+                    },
+                    injectTo: 'head-prepend',
+                }];
+        },
+        configureServer(server) {
+            const host = createRuntimeHostSession({ projectRoot, token });
+            const openedClients = new WeakSet();
+            function openClient(client) {
+                if (openedClients.has(client))
+                    return;
+                openedClients.add(client);
+                host.open(client);
+                client.socket.once('close', () => host.close(client));
+            }
+            server.ws.on(runtimeAnnounceEvent, (data, client) => {
+                openClient(client);
+                host.message(client, runtimeAnnounceEvent, data);
+            });
+            server.ws.on(runtimeResponseEvent, (data, client) => {
+                openClient(client);
+                host.message(client, runtimeResponseEvent, data);
+            });
+            server.middlewares.use((request, response, next) => {
+                void (async () => {
+                    const webRequest = await webRequestFromNode(request, serverOrigin(server));
+                    const result = await host.fetch(webRequest);
+                    if (!result) {
+                        next();
+                        return;
+                    }
+                    await writeNodeResponse(response, result);
+                })().catch(next);
+            });
+            const httpServer = server.httpServer;
+            if (!httpServer)
+                throw new Error('Pixifact Runtime requires the Vite HTTP server.');
+            let descriptor;
+            httpServer.once('listening', () => {
+                void (async () => {
+                    const candidate = {
+                        protocolVersion: runtimeSessionProtocolVersion,
+                        projectRoot,
+                        pid: process.pid,
+                        origin: serverOrigin(server),
+                        token,
+                    };
+                    const claim = await claimRuntimeSession({ projectRoot, descriptor: candidate });
+                    if (!claim.owned) {
+                        throw new Error('Another Pixifact Runtime Vite server is already running for this project.');
+                    }
+                    descriptor = candidate;
+                })().catch((error) => {
+                    server.config.logger.error(error instanceof Error ? error.message : String(error));
+                });
+            });
+            httpServer.once('close', () => {
+                if (descriptor)
+                    removeRuntimeSessionDescriptor(descriptor);
+            });
+        },
+    };
+}

package/dist/{compiler → compiler-node}/scriptInterfaceExtractor.d.ts

@@ -1,4 +1,4 @@
-import type { SceneScriptInterface } from './spec.js';
+import type { SceneScriptInterface } from '../compiler/spec.js';
 export interface ExtractSceneScriptInterfaceOptions {
     scene: string;
 }

package/dist/{compiler → compiler-node}/scriptInterfaceExtractor.js

@@ -15,6 +15,7 @@ function extractSceneScriptClasses(source, fileName, options) {
     const sourceId = normalizeScriptSourceId(fileName);
     const imports = collectNamedImports(sourceFile, sourceId);
     const structClasses = collectStructClasses(sourceFile);
+    const variantDeclarations = collectVariantDeclarations(sourceFile);
     const classes = [];
     for (const statement of sourceFile.statements) {
         if (!ts.isClassDeclaration(statement)) {
@@ -42,7 +43,8 @@ function extractSceneScriptClasses(source, fileName, options) {
             }
             const prop = memberDecoratorOptions(member, 'prop');
             if (prop) {
-                props[name] = propContract(prop, structClasses);
+                assertStaticPropMember(member, name);
+                props[name] = propContract(prop, member, structClasses, variantDeclarations);
             }
             const event = memberDecoratorOptions(member, 'event');
             if (event) {
@@ -318,6 +320,88 @@ function memberName(name) {
     }
     return undefined;
 }
+function collectVariantDeclarations(sourceFile) {
+    const variants = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) {
+            continue;
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {
+                continue;
+            }
+            const initializer = unwrapExpression(declaration.initializer);
+            if (!ts.isCallExpression(initializer)
+                || !ts.isIdentifier(initializer.expression)
+                || initializer.expression.text !== 'defineVariants') {
+                continue;
+            }
+            if (initializer.arguments.length !== 1) {
+                throw new Error('defineVariants accepts exactly one argument.');
+            }
+            variants.set(declaration.name.text, variantObjectValue(initializer.arguments[0], 'defineVariants argument'));
+        }
+    }
+    return variants;
+}
+function variantObjectValue(expression, label) {
+    const object = unwrapExpression(expression);
+    if (!ts.isObjectLiteralExpression(object)) {
+        throw new Error(`${label} must be an object literal.`);
+    }
+    const variants = {};
+    let expectedFields;
+    for (const property of object.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            throw new Error(`${label} only supports property assignments.`);
+        }
+        const name = memberName(property.name);
+        if (!name) {
+            throw new Error(`${label} only supports literal case names.`);
+        }
+        const caseExpression = unwrapExpression(property.initializer);
+        if (!ts.isObjectLiteralExpression(caseExpression)) {
+            throw new Error(`${label}.${name} must be an object literal.`);
+        }
+        const fields = {};
+        for (const field of caseExpression.properties) {
+            if (!ts.isPropertyAssignment(field)) {
+                throw new Error(`${label}.${name} only supports property assignments.`);
+            }
+            const fieldName = memberName(field.name);
+            if (!fieldName) {
+                throw new Error(`${label}.${name} only supports literal field names.`);
+            }
+            fields[fieldName] = literalValue(field.initializer, `${label}.${name}.${fieldName}`);
+        }
+        const fieldTypes = Object.fromEntries(Object.entries(fields).map(([field, value]) => [field, typeof value]));
+        if (!expectedFields) {
+            expectedFields = fieldTypes;
+        }
+        else if (!sameFieldTypes(expectedFields, fieldTypes)) {
+            throw new Error(`defineVariants case "${name}" must contain the same fields and field types as the first case.`);
+        }
+        variants[name] = fields;
+    }
+    if (Object.keys(variants).length === 0) {
+        throw new Error('defineVariants requires at least one case.');
+    }
+    return variants;
+}
+function sameFieldTypes(left, right) {
+    const leftEntries = Object.entries(left);
+    return leftEntries.length === Object.keys(right).length
+        && leftEntries.every(([name, type]) => right[name] === type);
+}
+function unwrapExpression(expression) {
+    if (ts.isAsExpression(expression)
+        || ts.isTypeAssertionExpression(expression)
+        || ts.isSatisfiesExpression(expression)
+        || ts.isParenthesizedExpression(expression)) {
+        return unwrapExpression(expression.expression);
+    }
+    return expression;
+}
 function collectStructClasses(sourceFile) {
     const classes = new Map();
     for (const statement of sourceFile.statements) {
@@ -355,65 +439,113 @@ function structFields(node) {
     }
     return fields;
 }
-function propContract(prop, structClasses) {
-    const type = prop.type;
-    const defaultValue = prop.default;
-    if (type === 'string' || type === 'number' || type === 'boolean') {
-        throw new Error('@prop type must be String, Number, Boolean, or a struct class.');
+function assertStaticPropMember(member, name) {
+    const isDeclareProperty = ts.isPropertyDeclaration(member)
+        && member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DeclareKeyword)
+        && !member.modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.AccessorKeyword)
+        && !member.initializer;
+    if (!isDeclareProperty) {
+        throw new Error(`@prop "${name}" must decorate a declare property without an initializer.`);
+    }
+    if (!member.type) {
+        throw new Error(`@prop "${name}" requires an explicit TypeScript property type.`);
+    }
+}
+function propContract(prop, member, structClasses, variantDeclarations) {
+    if (!ts.isPropertyDeclaration(member) || !member.type) {
+        throw new Error('@prop requires a typed declare property.');
     }
-    if (!isIdentifierValue(type)) {
-        throw new Error('@prop type must be String, Number, Boolean, or a struct class.');
+    if (prop.type !== undefined) {
+        throw new Error('@prop type is inferred from the TypeScript property declaration; remove the type option.');
+    }
+    const defaultValue = prop.default;
+    const variantsReference = prop.variants;
+    if (variantsReference !== undefined) {
+        if (!isIdentifierValue(variantsReference)) {
+            throw new Error('@prop variants must reference a local defineVariants declaration.');
+        }
+        const variants = variantDeclarations.get(variantsReference.text);
+        if (!variants) {
+            throw new Error(`@prop variants "${variantsReference.text}" must reference a local defineVariants declaration.`);
+        }
+        if (typeof defaultValue !== 'string' || !variants[defaultValue]) {
+            throw new Error('@prop Variant default must name an existing defineVariants case.');
+        }
+        assertVariantPropertyType(member.type, variantsReference.text);
+        return {
+            type: 'variant',
+            default: defaultValue,
+            variants,
+        };
     }
-    const primitiveType = primitiveConstructorType(type.text);
+    const primitiveType = primitivePropertyType(member.type);
     if (primitiveType) {
         if (defaultValue !== undefined && (!isSceneTemplateScalarValue(defaultValue) || sceneTemplateScalarType(defaultValue) !== primitiveType)) {
-            throw new Error(`@prop default for ${type.text} must be a ${primitiveType} literal.`);
+            throw new Error(`@prop default must be a ${primitiveType} literal.`);
         }
         return {
             type: primitiveType,
             ...(defaultValue !== undefined ? { default: defaultValue } : {}),
         };
     }
-    const structClass = structClasses.get(type.text);
+    const structName = typeReferenceName(member.type);
+    if (!structName) {
+        throw new Error('@prop type must be string, number, boolean, a local struct class, or keyof a local defineVariants declaration.');
+    }
+    const structClass = structClasses.get(structName);
     if (!structClass) {
-        throw new Error(`Struct prop type ${type.text} was not found.`);
+        throw new Error(`Struct prop type ${structName} was not found.`);
     }
     if (!structClass.exported) {
-        throw new Error(`Struct prop type ${type.text} must be exported.`);
+        throw new Error(`Struct prop type ${structName} must be exported.`);
     }
     if (defaultValue !== undefined) {
         throw new Error('@prop default is only supported for primitive props.');
     }
     const struct = structContractInfo(structClass.node);
     if (struct.hasRequiredConstructorParameters) {
-        throw new Error(`Struct prop type ${type.text} must be constructable with no required parameters.`);
+        throw new Error(`Struct prop type ${structName} must be constructable with no required parameters.`);
     }
     return {
         type: 'struct',
-        struct: type.text,
+        struct: structName,
         fields: struct.fields,
     };
 }
-function structContractInfo(node) {
-    return {
-        fields: structFields(node),
-        hasRequiredConstructorParameters: node.members.some((member) => ts.isConstructorDeclaration(member) && member.parameters.some((parameter) => !parameter.questionToken && !parameter.initializer)),
-    };
+function assertVariantPropertyType(type, variantsName) {
+    if (!ts.isTypeOperatorNode(type)
+        || type.operator !== ts.SyntaxKind.KeyOfKeyword
+        || !ts.isTypeQueryNode(type.type)
+        || !ts.isIdentifier(type.type.exprName)
+        || type.type.exprName.text !== variantsName) {
+        throw new Error(`@prop Variant type must be "keyof typeof ${variantsName}".`);
+    }
 }
-function primitiveConstructorType(name) {
-    if (name === 'String') {
+function primitivePropertyType(type) {
+    if (type.kind === ts.SyntaxKind.StringKeyword) {
         return 'string';
     }
-    if (name === 'Number') {
+    if (type.kind === ts.SyntaxKind.NumberKeyword) {
         return 'number';
     }
-    if (name === 'Boolean') {
+    if (type.kind === ts.SyntaxKind.BooleanKeyword) {
         return 'boolean';
     }
     return undefined;
 }
+function typeReferenceName(type) {
+    return ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName)
+        ? type.typeName.text
+        : undefined;
+}
+function structContractInfo(node) {
+    return {
+        fields: structFields(node),
+        hasRequiredConstructorParameters: node.members.some((member) => ts.isConstructorDeclaration(member) && member.parameters.some((parameter) => !parameter.questionToken && !parameter.initializer)),
+    };
+}
 function isIdentifierValue(value) {
-    return ts.isIdentifier(value);
+    return typeof value === 'object' && ts.isIdentifier(value);
 }
 function isSceneTemplateScalarValue(value) {
     return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';

package/dist/errors.d.ts

@@ -1 +1 @@
-export declare function hintForCommandError(error: string): "Use a project-relative scene path that stays inside projectRoot." | "Choose a different scene path or inspect the existing file before writing." | "Use one of: button, progressBar, scrollView, loginForm." | "Re-run scene get or node inspect to refresh locators before regenerating the command." | "Choose a container node as the parent, or create a container template before adding children." | "Verify that the field belongs to the target node or component schema before retrying." | "Check the target schema and send a value with the expected type." | undefined;
+export declare function hintForCommandError(error: string): "Use a project-relative scene path that stays inside projectRoot." | "Choose a different scene path or inspect the existing file before writing." | "Use one of: button, progressBar, scrollView, loginForm." | "Run scene inspect --scene <scene-path> and pass one of the returned node locator values." | "Inspect the current project state again before regenerating the command." | "Choose a container node as the parent, or create a container template before adding children." | "Verify that the field belongs to the target node or component schema before retrying." | "Check the target schema and send a value with the expected type." | undefined;