@lumenkey/cli 0.3.1 → 0.4.0-rc.1

package/dist/studio/director-contract.js

@@ -0,0 +1,288 @@
+// Browser-safe storage contract. Never import filesystem, network or source stores here.
+import { z } from 'zod';
+import { StudioError } from './errors.js';
+export const DIRECTOR_MAX_SCENE_BYTES = 128 * 1024;
+export const DIRECTOR_ASPECTS = ['自适应', '1:1', '2:1', '3:4', '4:3', '16:9', '21:9', '9:16'];
+export const DIRECTOR_BODY_TYPES = ['mannequin', 'female', 'broad', 'muscular', 'slim', 'teen', 'child', 'chibi'];
+export const DIRECTOR_POSES = ['stand', 't-pose', 'walk', 'run', 'sit', 'crouch', 'kneel-one', 'kneel-two', 'hands-on-hips', 'lean', 'bow', 'think', 'fight', 'kick', 'throw', 'push', 'wave', 'reach', 'cross-arms', 'phone'];
+export const DIRECTOR_PRIMITIVES = ['box', 'sphere', 'cylinder', 'cone', 'torus', 'pyramid', 'empty'];
+export const directorUuid = z.string().regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+const uuid = directorUuid;
+const revision = z.number().int().nonnegative().safe();
+const coordinate = z.number().finite().min(-10000).max(10000);
+const position = z.tuple([coordinate, coordinate, coordinate]);
+const angle = z.number().finite().min(-180).lt(180);
+const scale = z.number().finite().min(0.05).max(100);
+const name = z.string().trim().min(1).max(120).refine(v => !/[\u0000-\u001f\u007f]/.test(v));
+const transform = z.object({ position, rotation: z.tuple([angle, angle, angle]), scale: z.tuple([scale, scale, scale]) }).strict();
+const poseKey = /^(?:(?:body|torso|head)\.(?:pitch|yaw|roll)|(?:left|right)(?:Shoulder|Hip)\.(?:pitch|twist|spread)|(?:left|right)(?:Elbow|Knee)\.bend|(?:left|right)(?:Hand|Foot)\.(?:pitch|roll|twist)|body\.offsetY)$/;
+const controls = z.record(z.number().finite().min(-180).max(180)).superRefine((value, ctx) => {
+    if (Object.keys(value).length > 64 || Object.keys(value).some(key => !poseKey.test(key)) || Math.abs(value['body.offsetY'] ?? 0) > 5)
+        ctx.addIssue({ code: 'custom', message: 'Invalid pose controls' });
+});
+const motionPathSchema = z.object({
+    closed: z.boolean(), smooth: z.boolean(), uniform: z.boolean(),
+    points: z.array(position).min(2).max(16),
+}).strict();
+const objectBase = { id: uuid, name, transform, color: z.string().regex(/^#[0-9a-fA-F]{6}$/), hidden: z.boolean(), locked: z.boolean(), path: motionPathSchema.optional() };
+const objectSchema = z.discriminatedUnion('kind', [
+    z.object({ ...objectBase, kind: z.literal('mannequin'), bodyType: z.enum(DIRECTOR_BODY_TYPES), pose: z.enum(DIRECTOR_POSES), controls }).strict(),
+    z.object({ ...objectBase, kind: z.literal('geometry'), primitive: z.enum(DIRECTOR_PRIMITIVES) }).strict(),
+]);
+const viewFields = { position, target: position, fov: z.number().finite().min(10).max(120) };
+function validView(value) {
+    const [dx, dy, dz] = value.target.map((n, i) => n - value.position[i]);
+    const length = Math.hypot(dx, dy, dz);
+    return length >= 0.0001 && Math.hypot(dx, dz) / length >= 0.0001;
+}
+const observerSchema = z.object(viewFields).strict().refine(validView);
+// Absent follow means the stored position is the shot. Absent aim means the stored target.
+// Geometry of a bound follow or rotation is checked when the shot is resolved, not here.
+const followSchema = z.object({ objectId: uuid, view: z.enum(['third', 'first']), offset: position }).strict();
+const aimSchema = z.discriminatedUnion('mode', [
+    z.object({ mode: z.literal('point') }).strict(),
+    z.object({ mode: z.literal('rotation'), rotation: z.tuple([angle, angle, angle]) }).strict(),
+    z.object({ mode: z.literal('object'), objectId: uuid }).strict(),
+]);
+export const DIRECTOR_CAMERA_MOVES = ['orbit', 'halfArc', 'pushIn', 'pullOut', 'pedestal', 'truck', 'helix', 'rollerCoaster'];
+export const DIRECTOR_TRANSITIONS = ['dissolve', 'flashWhite', 'flashBlack', 'flashBlack2', 'flashWhite2'];
+const sampleViewSchema = z.object({ position, target: position }).strict().refine(validView);
+const timelineFocusSchema = z.discriminatedUnion('mode', [
+    z.object({ mode: z.literal('scene') }).strict(),
+    z.object({ mode: z.literal('object'), objectId: uuid }).strict(),
+    z.object({ mode: z.literal('point'), point: position }).strict(),
+]);
+const timelineTrackSchema = z.object({ id: uuid, kind: z.enum(['camera', 'object']), targetId: uuid }).strict();
+const clipStart = z.number().finite().min(0).max(600);
+const clipDuration = z.number().finite().gt(0).max(60);
+const clipRate = z.number().finite().min(0.1).max(8).optional();
+const clipSchema = z.discriminatedUnion('kind', [
+    z.object({ id: uuid, trackId: uuid, start: clipStart, duration: clipDuration, rate: clipRate, kind: z.literal('cameraMove'), move: z.enum(DIRECTOR_CAMERA_MOVES), fov: z.number().finite().min(10).max(120), samples: z.array(sampleViewSchema).min(2).max(24) }).strict(),
+    z.object({ id: uuid, trackId: uuid, start: clipStart, duration: clipDuration, rate: clipRate, kind: z.literal('cameraHold'), position, target: position, fov: z.number().finite().min(10).max(120) }).strict(),
+    z.object({ id: uuid, trackId: uuid, start: clipStart, duration: clipDuration, rate: clipRate, kind: z.literal('objectHold'), position, rotation: z.tuple([angle, angle, angle]), scale: z.tuple([scale, scale, scale]), pose: z.enum(DIRECTOR_POSES).optional() }).strict(),
+    z.object({ id: uuid, trackId: uuid, start: clipStart, duration: z.number().finite().gt(0).max(8), rate: clipRate, kind: z.literal('transition'), transition: z.enum(DIRECTOR_TRANSITIONS) }).strict(),
+]);
+const timelineSchema = z.object({
+    fps: z.union([z.literal(30), z.literal(60)]), loop: z.boolean(),
+    duration: z.number().finite().min(0.1).max(600), viewLock: z.boolean(),
+    focus: timelineFocusSchema.optional(), tracks: z.array(timelineTrackSchema).max(32), clips: z.array(clipSchema).max(64),
+}).strict();
+const environmentSchema = z.object({
+    sky: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+    groundVisible: z.boolean(), groundOpacity: z.number().finite().min(0).max(1),
+    groundHeight: z.number().finite().min(-100).max(100),
+    gridSnap: z.boolean(), gaussianGroundSnap: z.boolean(), labels: z.boolean(),
+    panoramaYaw: angle.optional(), panoramaRadius: z.number().finite().min(1).max(500).optional(),
+    panoramaAssetId: uuid.optional(), gaussianAssetId: uuid.optional(),
+    gaussianQuality: z.enum(['fluent', 'standard', 'high']).optional(), gaussianGroundDetect: z.boolean().optional(),
+}).strict();
+const cameraSchema = z.object({
+    id: uuid, name, ...viewFields, aspect: z.enum(DIRECTOR_ASPECTS),
+    follow: followSchema.optional(), aim: aimSchema.optional(), path: motionPathSchema.optional(),
+}).strict().refine(validView);
+const sceneSchema = z.object({
+    version: z.literal(1), sceneId: uuid, sceneRevision: revision,
+    objects: z.array(objectSchema).max(80), cameras: z.array(cameraSchema).min(1).max(16),
+    activeCameraId: uuid, observerView: observerSchema, selectedObjectId: uuid.nullable(),
+    timeline: timelineSchema.optional(), environment: environmentSchema.optional(),
+}).strict().superRefine((scene, ctx) => {
+    const objects = new Set(scene.objects.map(o => o.id)), cameras = new Set(scene.cameras.map(c => c.id));
+    const identityOk = objects.size === scene.objects.length && cameras.size === scene.cameras.length && cameras.has(scene.activeCameraId) && (scene.selectedObjectId === null || objects.has(scene.selectedObjectId));
+    const aimOk = scene.cameras.every(camera => (!camera.follow || objects.has(camera.follow.objectId)) && (camera.aim?.mode !== 'object' || objects.has(camera.aim.objectId)));
+    const timeline = scene.timeline;
+    const tracks = timeline?.tracks ?? [], clips = timeline?.clips ?? [];
+    const trackIds = new Set(tracks.map(track => track.id));
+    const clipIds = new Set(clips.map(clip => clip.id));
+    const timelineOk = !timeline || (trackIds.size === tracks.length && clipIds.size === clips.length
+        && tracks.every(track => (track.kind === 'camera' ? cameras : objects).has(track.targetId))
+        && clips.every(clip => trackIds.has(clip.trackId) && clipFitsTrack(clip, tracks.find(track => track.id === clip.trackId)) && (clip.kind !== 'cameraHold' || validView(clip)))
+        && (timeline.focus?.mode !== 'object' || objects.has(timeline.focus.objectId)));
+    if (!identityOk || !aimOk || !timelineOk)
+        ctx.addIssue({ code: 'custom', message: 'Invalid scene identities' });
+});
+function clipFitsTrack(clip, track) {
+    if (clip.kind === 'transition' || clip.kind === 'cameraMove' || clip.kind === 'cameraHold')
+        return track.kind === 'camera';
+    return track.kind === 'object';
+}
+export function cameraDimensions(aspect) {
+    if (!DIRECTOR_ASPECTS.includes(aspect))
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    if (aspect === '自适应')
+        return { width: 1280, height: 720 };
+    const [w, h] = aspect.split(':').map(Number), ratio = w / h;
+    return ratio >= 1 ? { width: 1280, height: Math.round(1280 / ratio) } : { width: Math.round(1280 * ratio), height: 1280 };
+}
+// Check descriptors before serializing: accessors/prototype tricks must not run.
+// Bound traversal independently from zod so cyclic/deep/untrusted values are safe.
+export function isDirectorJson(value) {
+    const ancestors = new Set();
+    let count = 0;
+    function walk(v, depth) {
+        if (++count > 30000 || depth > 20)
+            return false;
+        if (v === null || typeof v === 'boolean' || typeof v === 'string')
+            return true;
+        if (typeof v === 'number')
+            return Number.isFinite(v);
+        if (typeof v !== 'object')
+            return false;
+        const proto = Object.getPrototypeOf(v);
+        if (Array.isArray(v) ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+            return false;
+        if (ancestors.has(v))
+            return false;
+        ancestors.add(v);
+        for (const key of Reflect.ownKeys(v)) {
+            if (Array.isArray(v) && key === 'length')
+                continue;
+            if (typeof key !== 'string' || ['__proto__', 'constructor', 'prototype'].includes(key))
+                return false;
+            const descriptor = Object.getOwnPropertyDescriptor(v, key);
+            if (!descriptor.enumerable || !('value' in descriptor) || !walk(descriptor.value, depth + 1))
+                return false;
+        }
+        ancestors.delete(v);
+        return true;
+    }
+    try {
+        return walk(value, 0);
+    }
+    catch {
+        return false;
+    }
+}
+function parse(schema, value, maxBytes) {
+    if (!isDirectorJson(value))
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    if (new TextEncoder().encode(JSON.stringify(value)).length > maxBytes)
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    const parsed = schema.safeParse(value);
+    if (!parsed.success)
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    return parsed.data;
+}
+function dropAbsent(value, key) {
+    if (value[key] === undefined)
+        delete value[key];
+}
+export function parseDirectorScene(value) {
+    const scene = parse(sceneSchema, value, DIRECTOR_MAX_SCENE_BYTES);
+    // Optional keys must stay absent so older scenes stringify the same way.
+    for (const camera of scene.cameras) {
+        dropAbsent(camera, 'follow');
+        dropAbsent(camera, 'aim');
+        dropAbsent(camera, 'path');
+    }
+    for (const object of scene.objects)
+        dropAbsent(object, 'path');
+    dropAbsent(scene, 'timeline');
+    dropAbsent(scene, 'environment');
+    if (scene.timeline) {
+        dropAbsent(scene.timeline, 'focus');
+        for (const clip of scene.timeline.clips) {
+            dropAbsent(clip, 'rate');
+            if (clip.kind === 'objectHold')
+                dropAbsent(clip, 'pose');
+        }
+    }
+    if (scene.environment)
+        for (const key of ['panoramaYaw', 'panoramaRadius', 'panoramaAssetId', 'gaussianAssetId', 'gaussianQuality', 'gaussianGroundDetect'])
+            dropAbsent(scene.environment, key);
+    return scene;
+}
+export function cloneDirectorScene(value, newId = () => globalThis.crypto.randomUUID()) {
+    const scene = parseDirectorScene(value), reserved = new Set([
+        scene.sceneId, ...scene.objects.map(o => o.id), ...scene.cameras.map(c => c.id),
+        ...(scene.timeline?.tracks.map(track => track.id) ?? []), ...(scene.timeline?.clips.map(clip => clip.id) ?? []),
+        ...[scene.environment?.panoramaAssetId, scene.environment?.gaussianAssetId].filter((id) => !!id),
+    ]);
+    const allocate = () => { const id = newId(); if (!uuid.safeParse(id).success || reserved.has(id))
+        throw new StudioError('STUDIO_DIRECTOR_INVALID'); reserved.add(id); return id; };
+    const nextScene = allocate(), objectMapping = new Map(), cameraMapping = new Map();
+    scene.objects.forEach(o => objectMapping.set(o.id, allocate()));
+    scene.cameras.forEach(c => cameraMapping.set(c.id, allocate()));
+    scene.sceneId = nextScene;
+    scene.sceneRevision = 0;
+    scene.objects.forEach(o => { o.id = objectMapping.get(o.id); });
+    scene.cameras.forEach(c => {
+        c.id = cameraMapping.get(c.id);
+        if (c.follow)
+            c.follow.objectId = objectMapping.get(c.follow.objectId);
+        if (c.aim?.mode === 'object')
+            c.aim.objectId = objectMapping.get(c.aim.objectId);
+    });
+    scene.activeCameraId = cameraMapping.get(scene.activeCameraId);
+    if (scene.selectedObjectId)
+        scene.selectedObjectId = objectMapping.get(scene.selectedObjectId);
+    if (scene.timeline) {
+        const trackMapping = new Map();
+        scene.timeline.tracks.forEach(track => trackMapping.set(track.id, allocate()));
+        scene.timeline.tracks.forEach(track => {
+            track.id = trackMapping.get(track.id);
+            const mapped = (track.kind === 'camera' ? cameraMapping : objectMapping).get(track.targetId);
+            if (!mapped)
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+            track.targetId = mapped;
+        });
+        scene.timeline.clips.forEach(clip => {
+            clip.id = allocate();
+            const mapped = trackMapping.get(clip.trackId);
+            if (!mapped)
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+            clip.trackId = mapped;
+        });
+        if (scene.timeline.focus?.mode === 'object') {
+            const mapped = objectMapping.get(scene.timeline.focus.objectId);
+            if (!mapped)
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+            scene.timeline.focus.objectId = mapped;
+        }
+    }
+    return parseDirectorScene(scene);
+}
+export function cloneDirectorMetadata(metadata, newId) {
+    if (!isDirectorJson(metadata))
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    const next = structuredClone(metadata);
+    if (next.studioDirector !== undefined)
+        next.studioDirector = cloneDirectorScene(next.studioDirector, newId);
+    delete next.studioDirectorCaptures;
+    delete next.studioDirectorCaptureOrigin;
+    return next;
+}
+export function directorSceneContent(value) { const { sceneRevision: _, ...content } = value; return JSON.stringify(content); }
+export function normalizeSceneEdit(previousValue, nextValue) {
+    const previous = parseDirectorScene(previousValue), next = parseDirectorScene(nextValue);
+    if (previous.sceneId !== next.sceneId) {
+        if (next.sceneRevision !== 0)
+            throw new StudioError('STUDIO_DIRECTOR_INVALID');
+        return next;
+    }
+    if (directorSceneContent(previous) === directorSceneContent(next)) {
+        next.sceneRevision = previous.sceneRevision;
+        return next;
+    }
+    if (previous.sceneRevision === Number.MAX_SAFE_INTEGER)
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    next.sceneRevision = previous.sceneRevision + 1;
+    return next;
+}
+export const directorCaptureSchema = z.object({ captureId: uuid, assetId: uuid, sceneId: uuid, sceneRevision: revision, cameraId: uuid,
+    createdAt: z.string().datetime(), width: z.number().int().positive().max(1280), height: z.number().int().positive().max(1280),
+}).strict().refine(v => DIRECTOR_ASPECTS.some(a => { const d = cameraDimensions(a); return d.width === v.width && d.height === v.height; }));
+export const directorProvenanceSchema = z.object({
+    captureId: uuid, requestHash: z.string().regex(/^[a-f0-9]{64}$/), canvasId: uuid,
+    expectedCanvasRevision: revision, nodeId: z.string().min(1).max(160).regex(/^[a-zA-Z0-9_-]+$/),
+    sceneId: uuid, sceneRevision: revision, cameraId: uuid,
+    width: z.number().int().positive().max(1280), height: z.number().int().positive().max(1280),
+}).strict().refine(v => DIRECTOR_ASPECTS.some(a => { const d = cameraDimensions(a); return d.width === v.width && d.height === v.height; }));
+const historySchema = z.array(directorCaptureSchema).max(64).refine(rows => new Set(rows.map(r => r.captureId)).size === rows.length && new Set(rows.map(r => r.assetId)).size === rows.length);
+export function parseDirectorCaptureHistory(value, scene) {
+    const rows = parse(historySchema, value, 64 * 1024);
+    if (scene && rows.some(row => row.sceneId === scene.sceneId && row.sceneRevision > scene.sceneRevision))
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    // A historical camera may have been deleted; its PNG remains independently valid.
+    return rows;
+}
+//# sourceMappingURL=director-contract.js.map

package/dist/studio/director-png.d.ts

@@ -0,0 +1,6 @@
+export declare const DIRECTOR_MAX_PNG_BYTES: number;
+export declare function validateDirectorPng(bytes: Uint8Array, expected: {
+    width: number;
+    height: number;
+}): void;
+//# sourceMappingURL=director-png.d.ts.map

package/dist/studio/director-png.js

@@ -0,0 +1,41 @@
+// Node-only finite PNG structure check, NOT a CRC validator or compressed-data decoder.
+import { StudioError } from './errors.js';
+export const DIRECTOR_MAX_PNG_BYTES = 8 * 1024 * 1024;
+const signature = Buffer.from('89504e470d0a1a0a', 'hex');
+export function validateDirectorPng(bytes, expected) {
+    const invalid = () => { throw new StudioError('STUDIO_CAPTURE_PNG_INVALID', 422); };
+    if (!(bytes instanceof Uint8Array) || bytes.length > DIRECTOR_MAX_PNG_BYTES || bytes.length < 57 || !Number.isInteger(expected.width) || !Number.isInteger(expected.height) || expected.width < 1 || expected.height < 1 || expected.width > 1280 || expected.height > 1280)
+        invalid();
+    const data = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (!data.subarray(0, 8).equals(signature))
+        invalid();
+    let offset = 8, header = false, image = false, ended = false;
+    while (offset < data.length) {
+        if (data.length - offset < 12)
+            invalid();
+        const length = data.readUInt32BE(offset), end = offset + length + 12;
+        if (end > data.length)
+            invalid();
+        const kind = data.toString('ascii', offset + 4, offset + 8);
+        if (!/^[A-Za-z]{4}$/.test(kind) || (!header && kind !== 'IHDR'))
+            invalid();
+        if (kind === 'IHDR') {
+            if (header || offset !== 8 || length !== 13)
+                invalid();
+            if (data.readUInt32BE(offset + 8) !== expected.width || data.readUInt32BE(offset + 12) !== expected.height || data[offset + 16] !== 8 || ![2, 6].includes(data[offset + 17]) || data[offset + 18] !== 0 || data[offset + 19] !== 0 || data[offset + 20] !== 0)
+                invalid();
+            header = true;
+        }
+        else if (kind === 'IDAT')
+            image = true;
+        else if (kind === 'IEND') {
+            if (length !== 0 || end !== data.length || !image)
+                invalid();
+            ended = true;
+        }
+        offset = end;
+    }
+    if (!header || !image || !ended)
+        invalid();
+}
+//# sourceMappingURL=director-png.js.map

package/dist/studio/director-relations.d.ts

@@ -0,0 +1,40 @@
+import { type DirectorCapture } from './director-contract.js';
+import type { StudioCanvas, StudioCanvasSnapshot } from './canvas-store.js';
+import type { StudioAsset } from './types.js';
+export declare function captureHistoryEntry(asset: StudioAsset): DirectorCapture;
+export declare function captureOrigin(asset: StudioAsset): {
+    canvasId: string;
+    nodeId: string;
+    createdAt: string;
+    sceneId: string;
+    sceneRevision: number;
+    captureId: string;
+    assetId: string;
+    cameraId: string;
+    width: number;
+    height: number;
+};
+export declare function referenceIds(metadata: Record<string, unknown>): string[];
+export declare function assertDirectorCanvas(next: StudioCanvas, previous: StudioCanvas, all: StudioCanvas[], assets: StudioAsset[]): void;
+export interface CaptureBinding {
+    reference: boolean;
+    assetNode: boolean;
+    connection: boolean;
+}
+export declare function captureBinding(canvas: StudioCanvas | undefined, asset: StudioAsset): {
+    binding: CaptureBinding;
+    history: boolean;
+};
+export declare function canBindOriginal(canvas: StudioCanvas | undefined, asset: StudioAsset): boolean;
+export interface CaptureDelta {
+    nodeId: string;
+    history: DirectorCapture;
+    assetId: string;
+    assetNode: StudioCanvasSnapshot['nodes'][number];
+    connection: StudioCanvasSnapshot['connections'][number];
+}
+export declare function withCaptureRelation(canvas: StudioCanvas, asset: StudioAsset): {
+    snapshot: StudioCanvasSnapshot;
+    delta: CaptureDelta;
+};
+//# sourceMappingURL=director-relations.d.ts.map

package/dist/studio/director-relations.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { directorSceneContent, directorUuid, parseDirectorScene, parseDirectorCaptureHistory } from './director-contract.js';
+import { StudioError } from './errors.js';
+import { CAPTURE_NODE_SIZE, capturePosition } from './capture-placement.js';
+const referencesSchema = z.array(directorUuid).max(200).refine(v => new Set(v).size === v.length);
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function exactRecord(a, b) {
+    return !!a && typeof a === 'object' && !Array.isArray(a) && Object.keys(a).length === Object.keys(b).length && Object.entries(b).every(([k, v]) => same(a[k], v));
+}
+export function captureHistoryEntry(asset) {
+    const p = asset.directorCapture;
+    return { captureId: p.captureId, assetId: asset.assetId, sceneId: p.sceneId, sceneRevision: p.sceneRevision, cameraId: p.cameraId, createdAt: asset.savedAt, width: p.width, height: p.height };
+}
+export function captureOrigin(asset) { const p = asset.directorCapture; return { ...captureHistoryEntry(asset), canvasId: p.canvasId, nodeId: p.nodeId }; }
+export function referenceIds(metadata) {
+    const parsed = referencesSchema.safeParse(metadata.studioReferenceAssetIds ?? []);
+    if (!parsed.success)
+        throw new StudioError('STUDIO_DIRECTOR_INVALID');
+    return parsed.data;
+}
+export function assertDirectorCanvas(next, previous, all, assets) {
+    const assetMap = new Map(assets.map(a => [a.assetId, a])), captureMap = new Map(assets.filter(a => a.directorCapture).map(a => [a.directorCapture.captureId, a]));
+    const usedScenes = new Set();
+    for (const doc of all)
+        if (doc.id !== next.id)
+            for (const n of doc.snapshot.nodes)
+                if (n.metadata.studioDirector !== undefined)
+                    usedScenes.add(parseDirectorScene(n.metadata.studioDirector).sceneId);
+    for (const n of next.snapshot.nodes) {
+        const m = n.metadata, old = previous.snapshot.nodes.find(o => o.id === n.id);
+        const scene = m.studioDirector === undefined ? undefined : parseDirectorScene(m.studioDirector);
+        if (scene) {
+            if (!['image', 'video'].includes(n.type) || usedScenes.has(scene.sceneId))
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+            usedScenes.add(scene.sceneId);
+            const before = old?.metadata.studioDirector === undefined ? undefined : parseDirectorScene(old.metadata.studioDirector);
+            if (before?.sceneId === scene.sceneId && (scene.sceneRevision < before.sceneRevision || (directorSceneContent(scene) !== directorSceneContent(before) && scene.sceneRevision <= before.sceneRevision)))
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+            // Reusing a removed scene identity on another node is not cloning.
+            if (previous.snapshot.nodes.some(p => p.id !== n.id && p.metadata.studioDirector !== undefined && parseDirectorScene(p.metadata.studioDirector).sceneId === scene.sceneId))
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+        }
+        for (const id of referenceIds(m))
+            if (!assetMap.has(id))
+                throw new StudioError('STUDIO_ASSET_NOT_FOUND', 404);
+        if (m.studioDirectorCaptures !== undefined) {
+            if (!['image', 'video'].includes(n.type))
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+            for (const record of parseDirectorCaptureHistory(m.studioDirectorCaptures, scene)) {
+                const asset = captureMap.get(record.captureId), p = asset?.directorCapture;
+                if (!asset || !p || p.canvasId !== next.id || p.nodeId !== n.id || !exactRecord(record, captureHistoryEntry(asset)))
+                    throw new StudioError('STUDIO_DIRECTOR_INVALID');
+            }
+        }
+        if (m.studioDirectorCaptureOrigin !== undefined) {
+            const asset = typeof m.studioAssetId === 'string' ? assetMap.get(m.studioAssetId) : undefined;
+            if (n.type !== 'asset' || !asset?.directorCapture || n.id !== `capture-${asset.directorCapture.captureId}` || asset.directorCapture.canvasId !== next.id || !exactRecord(m.studioDirectorCaptureOrigin, captureOrigin(asset)))
+                throw new StudioError('STUDIO_DIRECTOR_INVALID');
+        }
+    }
+}
+export function captureBinding(canvas, asset) {
+    const p = asset.directorCapture, snapshot = canvas?.snapshot;
+    const source = snapshot?.nodes.find(n => n.id === p.nodeId && ['image', 'video'].includes(n.type));
+    const target = snapshot?.nodes.find(n => n.id === `capture-${p.captureId}` && n.type === 'asset');
+    return { binding: {
+            reference: !!source && referenceIds(source.metadata).includes(asset.assetId),
+            assetNode: !!target && target.metadata.studioAssetId === asset.assetId && exactRecord(target.metadata.studioDirectorCaptureOrigin, captureOrigin(asset)),
+            connection: !!snapshot?.connections.some(e => e.id === `capture-edge-${p.captureId}` && e.fromNodeId === `capture-${p.captureId}` && e.toNodeId === p.nodeId),
+        }, history: !!source && parseDirectorCaptureHistory(source.metadata.studioDirectorCaptures ?? []).some(row => exactRecord(row, captureHistoryEntry(asset))) };
+}
+export function canBindOriginal(canvas, asset) {
+    const p = asset.directorCapture;
+    if (!canvas || canvas.revision !== p.expectedCanvasRevision)
+        return false;
+    const n = canvas.snapshot.nodes.find(n => n.id === p.nodeId && ['image', 'video'].includes(n.type));
+    if (!n || n.metadata.studioDirector === undefined)
+        return false;
+    const scene = parseDirectorScene(n.metadata.studioDirector);
+    return scene.sceneId === p.sceneId && scene.sceneRevision === p.sceneRevision && scene.cameras.some(c => c.id === p.cameraId);
+}
+export function withCaptureRelation(canvas, asset) {
+    const p = asset.directorCapture, snapshot = structuredClone(canvas.snapshot), source = snapshot.nodes.find(n => n.id === p.nodeId);
+    if (!source)
+        throw new StudioError('STUDIO_CAPTURE_BINDING_CONFLICT', 409);
+    const history = parseDirectorCaptureHistory(source.metadata.studioDirectorCaptures ?? []);
+    if (history.length >= 64 || snapshot.nodes.length >= 200 || snapshot.connections.length >= 400)
+        throw new StudioError('STUDIO_CAPTURE_CAPACITY_EXCEEDED', 409);
+    const id = `capture-${p.captureId}`, edgeId = `capture-edge-${p.captureId}`;
+    if (snapshot.nodes.some(n => n.id === id) || snapshot.connections.some(e => e.id === edgeId))
+        throw new StudioError('STUDIO_CAPTURE_BINDING_CONFLICT', 409);
+    const entry = captureHistoryEntry(asset);
+    const assetNode = { id, type: 'asset', title: '镜头截图', position: capturePosition(snapshot.nodes, source), ...CAPTURE_NODE_SIZE, status: 'idle', metadata: { studioAssetId: asset.assetId, mediaType: 'image', studioDirectorCaptureOrigin: captureOrigin(asset) } };
+    const connection = { id: edgeId, fromNodeId: id, toNodeId: source.id, fromHandle: 'right', toHandle: 'left', status: 'idle' };
+    source.metadata.studioDirectorCaptures = [...history, entry];
+    source.metadata.studioReferenceAssetIds = [...new Set([...referenceIds(source.metadata), asset.assetId])];
+    snapshot.nodes.push(assetNode);
+    snapshot.connections.push(connection);
+    if (new TextEncoder().encode(JSON.stringify(snapshot)).length > 512 * 1024)
+        throw new StudioError('STUDIO_CAPTURE_CAPACITY_EXCEEDED', 409);
+    return { snapshot, delta: { nodeId: source.id, history: entry, assetId: asset.assetId, assetNode, connection } };
+}
+//# sourceMappingURL=director-relations.js.map

package/dist/studio/document-authority.d.ts

@@ -0,0 +1,7 @@
+import { type StudioErrorCode } from './errors.js';
+import type { StudioRoot } from './types.js';
+/** A durable initialization witness distinguishes first use from a missing authority after restart.
+ * Written BEFORE initial document creation, so an interrupted initialization is detectable.
+ * Existing valid documents are adopted. Deleting both the witness and document is outside recovery. */
+export declare function prepareDocumentAuthority(root: StudioRoot, name: 'drafts' | 'runs' | 'canvases' | 'output-saves', hasDocument: boolean, code: StudioErrorCode): Promise<void>;
+//# sourceMappingURL=document-authority.d.ts.map

package/dist/studio/document-authority.js

@@ -0,0 +1,50 @@
+import { open } from 'node:fs/promises';
+import path from 'node:path';
+import { assertRegularFile, assertStudioRoot } from './paths.js';
+import { hasFsCode, StudioError } from './errors.js';
+/** A durable initialization witness distinguishes first use from a missing authority after restart.
+ * Written BEFORE initial document creation, so an interrupted initialization is detectable.
+ * Existing valid documents are adopted. Deleting both the witness and document is outside recovery. */
+export async function prepareDocumentAuthority(root, name, hasDocument, code) {
+    const marker = path.join(root.managedDir, `.${name}.initialized`), expected = `lumenkey-local-document-v1:${name}\n`;
+    await assertStudioRoot(root);
+    async function exists() {
+        try {
+            await assertRegularFile(marker);
+            const handle = await open(marker, 'r');
+            try {
+                if ((await handle.stat()).size > 100 || await handle.readFile('utf8') !== expected)
+                    throw new StudioError(code, 409);
+            }
+            finally {
+                await handle.close();
+            }
+            return true;
+        }
+        catch (error) {
+            if (hasFsCode(error, 'ENOENT'))
+                return false;
+            throw new StudioError(code, 409);
+        }
+    }
+    if (await exists()) {
+        if (!hasDocument)
+            throw new StudioError(code, 409);
+        return;
+    }
+    try {
+        const handle = await open(marker, 'wx', 0o600);
+        try {
+            await handle.writeFile(expected);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (!hasFsCode(error, 'EEXIST') || !hasDocument || !await exists())
+            throw new StudioError(code, 409);
+    }
+}
+//# sourceMappingURL=document-authority.js.map

package/dist/studio/draft-store.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import type { StudioRoot } from './types.js';
+declare const document: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    revision: z.ZodNumber;
+    drafts: z.ZodObject<{
+        image: z.ZodOptional<z.ZodObject<{
+            modelId: z.ZodString;
+            fields: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, unknown, unknown>, z.ZodRecord<z.ZodString, z.ZodString>>;
+            savedAt: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            modelId: string;
+            fields: Record<string, string>;
+            savedAt: string;
+        }, {
+            modelId: string;
+            savedAt: string;
+            fields?: unknown;
+        }>>;
+        video: z.ZodOptional<z.ZodObject<{
+            modelId: z.ZodString;
+            fields: z.ZodPipeline<z.ZodEffects<z.ZodUnknown, unknown, unknown>, z.ZodRecord<z.ZodString, z.ZodString>>;
+            savedAt: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            modelId: string;
+            fields: Record<string, string>;
+            savedAt: string;
+        }, {
+            modelId: string;
+            savedAt: string;
+            fields?: unknown;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        image?: {
+            modelId: string;
+            fields: Record<string, string>;
+            savedAt: string;
+        } | undefined;
+        video?: {
+            modelId: string;
+            fields: Record<string, string>;
+            savedAt: string;
+        } | undefined;
+    }, {
+        image?: {
+            modelId: string;
+            savedAt: string;
+            fields?: unknown;
+        } | undefined;
+        video?: {
+            modelId: string;
+            savedAt: string;
+            fields?: unknown;
+        } | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: 1;
+    revision: number;
+    drafts: {
+        image?: {
+            modelId: string;
+            fields: Record<string, string>;
+            savedAt: string;
+        } | undefined;
+        video?: {
+            modelId: string;
+            fields: Record<string, string>;
+            savedAt: string;
+        } | undefined;
+    };
+}, {
+    schemaVersion: 1;
+    revision: number;
+    drafts: {
+        image?: {
+            modelId: string;
+            savedAt: string;
+            fields?: unknown;
+        } | undefined;
+        video?: {
+            modelId: string;
+            savedAt: string;
+            fields?: unknown;
+        } | undefined;
+    };
+}>;
+export type StudioDrafts = z.infer<typeof document>;
+export interface StudioDraftStore {
+    read(): Promise<StudioDrafts>;
+    save(value: unknown): Promise<StudioDrafts>;
+}
+/** Uses the asset store's exclusive directory writer and lifecycle, not a second lock. */
+export declare function createDraftStore(root: StudioRoot, serial: <T>(fn: () => Promise<T>) => Promise<T>): StudioDraftStore;
+export {};
+//# sourceMappingURL=draft-store.d.ts.map