@playcraft/cli 0.1.60-beta → 0.1.61-beta

package/dist/workspace-runtime/workspaces/procedural-3d/render-worker.js

@@ -0,0 +1,159 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chromium } from 'playwright-core';
+import sharp from 'sharp';
+import { digest } from './files.js';
+import { canonicalJson, reviewProfileHash, validateRenderState, } from './review-contracts.js';
+/** Launched as the development user; Vite and Chromium die with the managed process group. */
+async function main() {
+    let raw = '';
+    for await (const chunk of process.stdin) {
+        raw += chunk;
+        if (raw.length > 64 * 1024)
+            throw new Error('render_input_limit');
+    }
+    const input = JSON.parse(raw);
+    if (input.reviewProfile &&
+        reviewProfileHash(input.reviewProfile.profile) !== input.reviewProfile.hash)
+        throw new Error('render_profile_mismatch');
+    const project = createRequire(join(input.projectRoot, 'package.json'));
+    const vite = await import(pathToFileURL(project.resolve('vite')).href);
+    const three = join(dirname(project.resolve('three')), 'three.module.js');
+    const threeVersion = JSON.parse(await readFile(join(dirname(three), '../package.json'), 'utf8')).version;
+    const server = await vite.createServer({
+        configFile: false,
+        root: input.sourceRoot,
+        logLevel: 'silent',
+        resolve: { alias: [{ find: /^three$/, replacement: three }] },
+        server: {
+            host: '127.0.0.1',
+            port: 0,
+            strictPort: false,
+            fs: { strict: true, allow: [input.sourceRoot, dirname(three)] },
+        },
+    });
+    let browser;
+    try {
+        await server.listen();
+        const address = server.httpServer.address();
+        const origin = `http://127.0.0.1:${address.port}`;
+        browser = await chromium.launch({
+            executablePath: process.env.PLAYCRAFT_CHROMIUM_PATH || '/usr/bin/chromium',
+            headless: true,
+            args: [
+                '--disable-dev-shm-usage',
+                '--enable-unsafe-swiftshader',
+                '--use-gl=angle',
+                '--use-angle=swiftshader',
+            ],
+        });
+        const context = await browser.newContext({
+            viewport: { width: 768, height: 768 },
+            deviceScaleFactor: 1,
+            serviceWorkers: 'block',
+        });
+        const errors = [];
+        await context.route('**/*', (route) => {
+            const url = route.request().url();
+            if (url === `${origin}/favicon.ico`)
+                return route.fulfill({ status: 204 });
+            return url.startsWith(`${origin}/`) || /^(data|blob):/.test(url)
+                ? route.continue()
+                : route.abort('blockedbyclient');
+        });
+        const page = await context.newPage();
+        page.on('pageerror', (error) => errors.push(error.message));
+        page.on('console', (message) => {
+            if (message.type() === 'error')
+                errors.push(message.text());
+        });
+        page.on('requestfailed', (request) => errors.push(`${request.url()}: ${request.failure()?.errorText}`));
+        await page.goto(`${origin}/${input.pagePath.split('/').map(encodeURIComponent).join('/')}`, {
+            waitUntil: 'networkidle',
+            timeout: 30_000,
+        });
+        await page.waitForFunction('Boolean(window.__PLAYCRAFT_SCULPT__?.ready)', undefined, {
+            timeout: 30_000,
+        });
+        await page.evaluate('Promise.resolve(window.__PLAYCRAFT_SCULPT__.ready)');
+        const renderer = await page.evaluate(`(() => {const c=document.querySelector('canvas'); const g=c?.getContext('webgl2')||c?.getContext('webgl'); if(!g) throw new Error('webgl_unavailable'); const e=g.getExtension('WEBGL_debug_renderer_info'); return {renderer:g.getParameter(e?e.UNMASKED_RENDERER_WEBGL:g.RENDERER),vendor:g.getParameter(e?e.UNMASKED_VENDOR_WEBGL:g.VENDOR)};})()`);
+        await mkdir(input.outputRoot, { recursive: true });
+        const captures = [];
+        const states = {};
+        const captureState = async (view, stripped = false) => {
+            if (!input.reviewProfile)
+                return;
+            states[view] = validateRenderState(await page.evaluate('window.__PLAYCRAFT_SCULPT__.getRenderState()'), input.reviewProfile.profile, view, stripped);
+        };
+        for (const view of input.views) {
+            await page.evaluate(`Promise.resolve(window.__PLAYCRAFT_SCULPT__.setView(${JSON.stringify(view)})).then(()=>new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r))))`);
+            await page.screenshot({
+                path: join(input.outputRoot, `${view}.png`),
+                animations: 'disabled',
+            });
+            await captureState(view);
+            captures.push({ view, file: `${view}.png` });
+        }
+        await page.evaluate(`Promise.resolve(window.__PLAYCRAFT_SCULPT__.setView('hero')).then(()=>window.__PLAYCRAFT_SCULPT__.setMapStripped(true)).then(()=>new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r))))`);
+        await page.screenshot({
+            path: join(input.outputRoot, 'map-stripped.png'),
+            animations: 'disabled',
+        });
+        captures.push({ view: 'map-stripped', file: 'map-stripped.png' });
+        await captureState('map-stripped', true);
+        const reference = await sharp(input.referencePath)
+            .resize(768, 768, { fit: 'contain', background: '#e9e9e9' })
+            .png()
+            .toBuffer();
+        const hero = await sharp(join(input.outputRoot, `${input.views.includes('hero') ? 'hero' : input.views[0]}.png`))
+            .resize(768, 768)
+            .png()
+            .toBuffer();
+        await sharp({ create: { width: 1536, height: 768, channels: 3, background: '#e9e9e9' } })
+            .composite([
+            { input: reference, left: 0, top: 0 },
+            { input: hero, left: 768, top: 0 },
+        ])
+            .png()
+            .toFile(join(input.outputRoot, 'comparison.png'));
+        captures.push({ view: 'comparison', file: 'comparison.png' });
+        let renderReceipt;
+        if (input.reviewProfile) {
+            const bytes = canonicalJson({
+                schemaVersion: 1,
+                reviewProfileHash: input.reviewProfile.hash,
+                profile: input.reviewProfile.profile,
+                views: states,
+            });
+            await writeFile(join(input.outputRoot, 'render-state.json'), bytes, { flag: 'wx' });
+            renderReceipt = { file: 'render-state.json', hash: digest(bytes) };
+        }
+        await page.evaluate('window.__PLAYCRAFT_SCULPT__.dispose?.()');
+        if (errors.length)
+            throw new Error(`render_errors: ${errors.join('\n').slice(0, 4000)}`);
+        return {
+            captures,
+            renderer,
+            browser: browser.version(),
+            node: process.version,
+            three: threeVersion,
+            vite: vite.version,
+            viewport: { width: 768, height: 768, deviceScaleFactor: 1 },
+            ready: true,
+            ...(renderReceipt ? { renderReceipt } : {}),
+            errors,
+        };
+    }
+    finally {
+        await browser?.close();
+        await server.close();
+    }
+}
+main()
+    .then((result) => process.stdout.write(JSON.stringify({ ok: true, result })))
+    .catch((error) => {
+    process.stderr.write(String(error));
+    process.exitCode = 1;
+});

package/dist/workspace-runtime/workspaces/procedural-3d/review-contracts.js

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+import { digest, relativeFile } from './files.js';
+export const REVIEW_DIRECTORY = '__playcraft-review';
+export const REVIEW_PAGE = `${REVIEW_DIRECTORY}/index.html`;
+export const REVIEW_VIEWS = ['front', 'right', 'back', 'left', 'hero'];
+const finite = z.number().finite();
+const coordinate = finite.min(-100000).max(100000);
+const vector = z.tuple([coordinate, coordinate, coordinate]);
+const projectedVector = z.tuple([finite, finite, finite]);
+const matrix = z.array(finite).length(16);
+export const reviewProfileSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    fovDegrees: finite.min(1).max(120),
+    near: finite.min(0.0001).max(1000),
+    far: finite.max(100000),
+    target: vector,
+    views: z
+        .object({ front: vector, right: vector, back: vector, left: vector, hero: vector })
+        .strict(),
+    background: z
+        .string()
+        .regex(/^#[a-fA-F0-9]{6}$/)
+        .transform((value) => value.toLowerCase()),
+    keyLightPosition: vector,
+    referenceCameraStatus: z.literal('estimated'),
+})
+    .strict()
+    .superRefine((profile, context) => {
+    if (profile.far < profile.near + 0.0001)
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'invalid camera range' });
+    for (const position of Object.values(profile.views)) {
+        const distance = Math.hypot(...position.map((value, index) => value - profile.target[index]));
+        if (distance <= profile.near || distance >= profile.far)
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'invalid camera target distance',
+            });
+    }
+});
+/** A bounded canonical JSON (JavaScript Object Notation, JavaScript对象表示法) encoding. */
+export function canonicalJson(value) {
+    let nodes = 0;
+    const normalize = (input, depth = 0) => {
+        if (++nodes > 4096 || depth > 12)
+            throw new Error('procedural_skill_invalid_review_json');
+        if (input === null || typeof input === 'string' || typeof input === 'boolean')
+            return input;
+        if (typeof input === 'number' && Number.isFinite(input))
+            return input;
+        if (Array.isArray(input))
+            return input.map((item) => normalize(item, depth + 1));
+        if (input && typeof input === 'object' && Object.getPrototypeOf(input) === Object.prototype)
+            return Object.fromEntries(Object.keys(input)
+                .sort()
+                .map((key) => [key, normalize(input[key], depth + 1)]));
+        throw new Error('procedural_skill_invalid_review_json');
+    };
+    const encoded = JSON.stringify(normalize(value));
+    if (Buffer.byteLength(encoded) > 64 * 1024)
+        throw new Error('procedural_skill_invalid_review_json');
+    return encoded;
+}
+export const reviewProfileHash = (profile) => digest(canonicalJson(profile));
+export const captureV2Schema = z
+    .object({
+    files: z.array(z.string()).min(1).max(252),
+    sourcePaths: z.array(z.string()).min(1).max(128),
+    views: z.array(z.enum(REVIEW_VIEWS)).min(3).max(5).default(['front', 'right', 'hero']),
+    review: z
+        .object({
+        factoryPath: z.string(),
+        exportName: z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]{0,79}$/),
+        parameters: z.record(z.unknown()).optional(),
+        profile: reviewProfileSchema,
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((input, context) => {
+    const invalid = () => context.addIssue({ code: z.ZodIssueCode.custom, message: 'invalid controlled review input' });
+    if (new Set(input.views).size !== input.views.length || !input.views.includes('hero'))
+        invalid();
+    if (!input.sourcePaths.includes(input.review.factoryPath) ||
+        !/\.(?:[cm]?[jt]sx?)$/.test(input.review.factoryPath))
+        invalid();
+    if (input.files.some((path) => path.toLowerCase() === REVIEW_DIRECTORY ||
+        path.toLowerCase().startsWith(`${REVIEW_DIRECTORY}/`)))
+        invalid();
+    try {
+        relativeFile(input.review.factoryPath);
+        if (input.review.parameters &&
+            Buffer.byteLength(canonicalJson(input.review.parameters)) > 16 * 1024)
+            invalid();
+    }
+    catch {
+        invalid();
+    }
+});
+const renderStateSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    view: z.enum(REVIEW_VIEWS),
+    mapStripped: z.boolean(),
+    profile: reviewProfileSchema,
+    viewport: z
+        .object({ width: z.literal(768), height: z.literal(768), deviceScaleFactor: z.literal(1) })
+        .strict(),
+    camera: z
+        .object({
+        position: vector,
+        target: vector,
+        fovDegrees: finite,
+        near: finite,
+        far: finite,
+        projectionMatrix: matrix,
+        matrixWorld: matrix,
+        matrixWorldInverse: matrix,
+    })
+        .strict(),
+    modelBounds: z.object({ min: vector, max: vector }).strict(),
+    projectedBounds: z
+        .object({ min: projectedVector, max: projectedVector, conservative: z.literal(true) })
+        .strict()
+        .nullable(),
+    framing: z.enum(['contained', 'bounds-overflow', 'unknown']),
+})
+    .strict();
+const close = (a, b) => Math.abs(a - b) <= 1e-7 * Math.max(1, Math.abs(a), Math.abs(b));
+const same = (a, b) => a.length === b.length && a.every((value, index) => close(value, b[index]));
+const cross = (a, b) => [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+];
+const norm = (a) => {
+    const length = Math.hypot(...a);
+    return a.map((value) => value / length);
+};
+const dot = (a, b) => a.reduce((sum, value, index) => sum + value * b[index], 0);
+/** Independently check the actual helper state against the fixed camera, never fit model bounds. */
+export function validateRenderState(value, profile, view, stripped = false) {
+    const state = renderStateSchema.parse(value);
+    const expectedView = stripped ? 'hero' : view;
+    const position = profile.views[expectedView];
+    const fail = () => {
+        throw new Error('procedural_skill_review_state_mismatch');
+    };
+    if (!position ||
+        state.view !== expectedView ||
+        state.mapStripped !== stripped ||
+        canonicalJson(state.profile) !== canonicalJson(profile) ||
+        !same(state.camera.position, position) ||
+        !same(state.camera.target, profile.target) ||
+        !close(state.camera.fovDegrees, profile.fovDegrees) ||
+        !close(state.camera.near, profile.near) ||
+        !close(state.camera.far, profile.far))
+        fail();
+    let zAxis = norm(position.map((value, index) => value - profile.target[index]));
+    if (Math.hypot(...cross([0, 1, 0], zAxis)) === 0) {
+        zAxis[2] += 0.0001;
+        zAxis = norm(zAxis);
+    }
+    const xAxis = norm(cross([0, 1, 0], zAxis)), yAxis = cross(zAxis, xAxis);
+    const world = [...xAxis, 0, ...yAxis, 0, ...zAxis, 0, ...position, 1];
+    const inverse = [
+        xAxis[0],
+        yAxis[0],
+        zAxis[0],
+        0,
+        xAxis[1],
+        yAxis[1],
+        zAxis[1],
+        0,
+        xAxis[2],
+        yAxis[2],
+        zAxis[2],
+        0,
+        -dot(xAxis, position),
+        -dot(yAxis, position),
+        -dot(zAxis, position),
+        1,
+    ];
+    const scale = 1 / Math.tan((profile.fovDegrees * Math.PI) / 360);
+    const projection = [
+        scale,
+        0,
+        0,
+        0,
+        0,
+        scale,
+        0,
+        0,
+        0,
+        0,
+        -(profile.far + profile.near) / (profile.far - profile.near),
+        -1,
+        0,
+        0,
+        (-2 * profile.far * profile.near) / (profile.far - profile.near),
+        0,
+    ];
+    if (!same(state.camera.matrixWorld, world) ||
+        !same(state.camera.matrixWorldInverse, inverse) ||
+        !same(state.camera.projectionMatrix, projection))
+        fail();
+    if (state.modelBounds.min.some((entry, index) => entry > state.modelBounds.max[index]))
+        fail();
+    const multiply = (m, p) => [0, 1, 2, 3].map((row) => p.reduce((sum, entry, column) => sum + m[column * 4 + row] * entry, 0));
+    const points = [];
+    for (const x of [state.modelBounds.min[0], state.modelBounds.max[0]])
+        for (const y of [state.modelBounds.min[1], state.modelBounds.max[1]])
+            for (const z of [state.modelBounds.min[2], state.modelBounds.max[2]]) {
+                const clip = multiply(projection, multiply(inverse, [x, y, z, 1]));
+                if (!clip.every(Number.isFinite) || clip[3] <= 1e-9) {
+                    if (state.projectedBounds !== null || state.framing !== 'unknown')
+                        fail();
+                    return state;
+                }
+                points.push(clip.slice(0, 3).map((entry) => entry / clip[3]));
+            }
+    const min = [0, 1, 2].map((axis) => Math.min(...points.map((point) => point[axis])));
+    const max = [0, 1, 2].map((axis) => Math.max(...points.map((point) => point[axis])));
+    const framing = min.every((value) => value >= -1) && max.every((value) => value <= 1)
+        ? 'contained'
+        : 'bounds-overflow';
+    if (!state.projectedBounds ||
+        !same(state.projectedBounds.min, min) ||
+        !same(state.projectedBounds.max, max) ||
+        state.framing !== framing)
+        fail();
+    return state;
+}
+export function validateRenderReceipt(value, profile, views) {
+    const receipt = z
+        .object({
+        schemaVersion: z.literal(1),
+        reviewProfileHash: z.string().regex(/^[a-f0-9]{64}$/),
+        profile: reviewProfileSchema,
+        views: z.record(z.unknown()),
+    })
+        .strict()
+        .parse(value);
+    const expected = [...views, 'map-stripped'];
+    if (receipt.reviewProfileHash !== reviewProfileHash(profile) ||
+        canonicalJson(receipt.profile) !== canonicalJson(profile) ||
+        Object.keys(receipt.views).length !== expected.length ||
+        expected.some((view) => !Object.hasOwn(receipt.views, view)))
+        throw new Error('procedural_skill_review_receipt_mismatch');
+    return {
+        ...receipt,
+        views: Object.fromEntries(expected.map((view) => [
+            view,
+            validateRenderState(receipt.views[view], profile, view, view === 'map-stripped'),
+        ])),
+    };
+}

package/dist/workspace-runtime/workspaces/procedural-3d/review-page.js

@@ -0,0 +1,26 @@
+import { canonicalJson, REVIEW_DIRECTORY, REVIEW_PAGE, } from './review-contracts.js';
+const literal = (value) => JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+/** Only locked helpers and declarative factory data enter the host-owned review page. */
+export function createHostReviewFiles(review, helpers) {
+    const factory = `/${review.factoryPath.split('/').map(encodeURIComponent).join('/')}`;
+    const profile = canonicalJson(review.profile);
+    const page = `<!doctype html><html><head><meta charset="utf-8"><base href="/"><style>html,body{margin:0;width:768px;height:768px;overflow:hidden}</style></head><body><script type="module">
+import { createReviewScene } from '/${REVIEW_DIRECTORY}/review-scene.mjs';
+import * as factory from ${literal(factory)};
+const createModel = factory[${literal(review.exportName)}];
+if (typeof createModel !== 'function') throw new Error('review_factory_missing');
+const parameters = JSON.parse(${literal(canonicalJson(review.parameters ?? {}))});
+const profile = JSON.parse(${literal(profile)});
+const api = createReviewScene(() => createModel(parameters), { profile });
+Object.defineProperty(window, '__PLAYCRAFT_SCULPT__', { value: api, writable: false, configurable: false });
+</script></body></html>`;
+    return [
+        { path: REVIEW_PAGE, bytes: Buffer.from(page) },
+        { path: `${REVIEW_DIRECTORY}/review-scene.mjs`, bytes: helpers.scene },
+        { path: `${REVIEW_DIRECTORY}/review-profile.mjs`, bytes: helpers.profile },
+        { path: `${REVIEW_DIRECTORY}/profile.json`, bytes: Buffer.from(profile) },
+    ];
+}

package/dist/workspace-runtime/workspaces/skill-execution-context.js

@@ -0,0 +1,69 @@
+import { realpath } from 'node:fs/promises';
+import { PROCEDURAL_3D_SKILL_REF, resolveWorkspaceSkillExecutionPolicy, workspaceComposerSelectionSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { assertOperationDirectoryAccess } from '../server/directory-access.js';
+import { sessionWorkspaceRoot } from './registry.js';
+import { readWorkspaceSkillSnapshot } from './skills.js';
+/** Read-only preflight. It must precede the directory gate and cannot install or freeze files. */
+export async function preflightSkillExecution(state, request) {
+    if (request.kind !== 'session.turn')
+        return undefined;
+    const body = request.payload && typeof request.payload === 'object'
+        ? request.payload
+        : {};
+    if ('directoryAccessMode' in body || 'skillExecutionPolicyVersion' in body)
+        throw new Error('untrusted_runtime_field');
+    const selection = workspaceComposerSelectionSchema.safeParse({
+        context: body.context,
+        workMode: body.workMode,
+    });
+    if (!selection.success)
+        throw new Error('invalid_composer_context');
+    if (!selection.data.context?.skills.length)
+        return undefined;
+    if (request.directoryName === 'root')
+        throw new Error('context_directory_mismatch');
+    const root = await sessionWorkspaceRoot(state, request.workspaceId, request.directoryName);
+    return resolveWorkspaceSkillExecutionPolicy(await readWorkspaceSkillSnapshot(root), selection.data.context.skills);
+}
+/** Native tool callers supply the actual thread/turn binding, never shell-provided identity. */
+export async function resolveActiveSkillExecutionContext(state, input) {
+    const skillRef = input.skillRef ?? PROCEDURAL_3D_SKILL_REF;
+    if (state.journal.destroyed())
+        throw new Error('skill_execution_identity_mismatch');
+    if (skillRef !== PROCEDURAL_3D_SKILL_REF)
+        throw new Error('context_skill_unavailable');
+    const session = state.journal.getSession(input.sessionId);
+    const matches = state.journal
+        .listOperations()
+        .map((item) => item.operation)
+        .filter((operation) => operation.kind === 'session.turn' &&
+        ['dispatched', 'accepted'].includes(operation.status) &&
+        operation.sessionId === input.sessionId &&
+        operation.nativeThreadId === input.nativeThreadId &&
+        operation.nativeTurnId === input.nativeTurnId &&
+        operation.generation === state.config.generation &&
+        operation.runtimeEpoch === state.runtimeEpoch &&
+        operation.userId === state.config.userId &&
+        operation.environment === state.config.environment);
+    const operation = matches.length === 1 ? matches[0] : undefined;
+    if (!operation ||
+        !session ||
+        session.threadId !== input.nativeThreadId ||
+        (session.activeTurnId !== undefined && session.activeTurnId !== input.nativeTurnId) ||
+        session.workspaceId !== operation.workspaceId ||
+        (session.directoryName ?? 'basic') !== (operation.directoryName ?? 'basic'))
+        throw new Error('skill_execution_identity_mismatch');
+    if (operation.directoryAccessMode !== 'exclusive' || operation.skillExecutionPolicyVersion !== 1)
+        throw new Error('requires-exclusive-turn');
+    if (operation.workMode === 'plan' || operation.permissionMode === 'read-only')
+        throw new Error('skill_execution_readonly');
+    await assertOperationDirectoryAccess(state, operation, 'exclusive');
+    const root = await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName);
+    if ((await realpath(root)) !== (await realpath(input.root)))
+        throw new Error('skill_execution_identity_mismatch');
+    const policy = resolveWorkspaceSkillExecutionPolicy(await readWorkspaceSkillSnapshot(root), operation.context?.skills ?? []);
+    const entry = policy.entries.find((item) => item.revision.skillRef === skillRef);
+    if (!entry || policy.directoryAccessMode !== 'exclusive')
+        throw new Error('requires-exclusive-turn');
+    return { operation, entry, lockHash: policy.lockHash, declarationHash: policy.declarationHash };
+}

package/dist/workspace-runtime/workspaces/skills.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { cp, lstat, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { cp, lstat, open, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { load } from 'js-yaml';
 import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
@@ -156,13 +157,22 @@ export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
             expectedFiles.add(relative);
             await safeDirectory(generation, dirname(relative));
             // shared
-            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
+            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(error => {
                 if (error.code !== 'EEXIST')
                     throw error;
-                const stat = await lstat(target);
-                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || !file.data.equals(await readFile(target)))
-                    throw new Error('workspace_skills_digest_mismatch');
             });
+            const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.nlink !== 1 || !file.data.equals(await handle.readFile()))
+                    throw new Error('workspace_skills_digest_mismatch');
+                // A private controller umask must not remove the developer's read access.
+                // Repair only the verified inode, keeping every frozen byte read-only.
+                await handle.chmod(0o444);
+            }
+            finally {
+                await handle.close();
+            }
         }
         const body = files.find(file => file.path === 'SKILL.md');
         if (!body)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.60-beta",
+  "version": "0.1.61-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -53,8 +53,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.60-beta",
-    "@playcraft/common": "0.1.60-beta",
+    "@playcraft/build": "0.1.61-beta",
+    "@playcraft/common": "0.1.61-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",

package/project-template-v2/.playcraft/skills.lock.json

@@ -141,6 +141,13 @@
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-prefab"
     },
+    {
+      "skillRef": "remix/playcraft-remix-references",
+      "version": "1.1.0",
+      "artifactHash": "32d4bb3bb6ed2dc0405997161dc65cd535559a71c227f0425612809ee5c178af",
+      "surface": "sandbox-agent",
+      "mountPath": ".playcraft/skills/remix__playcraft-remix-references"
+    },
     {
       "skillRef": "remix/playcraft-remix-workflow",
       "version": "1.0.0",

package/project-templates/empty/AGENTS.md

@@ -42,6 +42,16 @@ Reference snapshots under `references/remixes/` are fixed source material. Their
 
 Use the built-in CLI (Command Line Interface, 命令行界面) commands for platform assets. Run the relevant command's `--help` to inspect its supported parameters. The workspace supplies credentials; keep them out of commands, files, and chat output.
 
+### Asset sourcing
+
+Follow the user's explicit source choice: reuse specified assets or generate new assets when requested, without asking again. Otherwise, when a task needs images, audio, sprites, animation, models, or video, search the shared library before generating. Cover both authorized team assets and public assets. When the current team is known from verified workspace or project context, search it with `--team-id <teamId>` and search public assets separately with `--visibility public`; a team filter does not include public assets. Without verified team context, omit both filters to search the credential's authorized scopes rather than guessing a team identifier.
+
+Inspect promising candidates with `library get` and `library files`, checking their intended use, style, dimensions, format, and required package contents against the task. Reuse suitable assets directly, preferring team assets when candidates are equally suitable, and download the complete file or package into the project's asset directory. Do not substitute a preview for the production files. If a narrow query finds nothing suitable, broaden the keywords or filters and inspect relevant result pages before concluding there is no match. Generate only the missing assets after these searches find no suitable candidate. A failed or unavailable search is not an empty result: report the limitation and recover the search instead of claiming that the library has no suitable assets.
+
+Do not ask the user to choose reuse versus generation for every asset. Ask only when candidate differences materially affect the requested direction or suitability remains unclear; present the relevant candidates and tradeoffs. An execution without user interaction should pass that ambiguity to its coordinating conversation through the existing workflow. Report which assets were actually reused or generated and why.
+
+### Commands
+
 - Shared library: `playcraft library search "<query>" --json`, `library list`, and `library facets` support type, category, tags, team, and pagination filters. `library get <assetId>` reads metadata; `library files <assetId>` lists a complete package. These identifiers belong to the shared library, separate from project assets returned by `tools list-assets`.
 - Download library content: `playcraft library download <assetId> --output <new-path>` saves a file or a complete package directory. `--output-dir <new-directory>` always saves a directory. Packages retain manifests, nested files, and relative dependencies. Download working assets into the project's asset directory; choose `dist/` for final deliverables. Existing output paths are preserved.
 - Layer separation: `playcraft image decompose-layers --input <image> --output-dir <directory>` uses the current workspace layer pipeline and saves a base, separate layers, and metadata with stacking order and bounds. Optional `--prompt`, `--size`, and `--image-model` guide generation. `--engine qwen` selects the legacy pipeline.