The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.
TypeScript agent-skillsagentic-aiai-agentsai-videobyokclaude-codecodexdeepseek-harnessdsh-plugingenerative-ailocal-firstmcpmotionmotion-graphicsmultimodalopenmotionreverse-engineeringvideo-editingvideo-generationworkbuddy
import { renderFilenameStem } from './shared/render-name.ts';
import { createHash } from 'node:crypto';
import { isAssetFileWithinLimit } from './shared/asset-limits.ts';
import { createReadStream, existsSync, readFileSync } from 'node:fs';
import os from 'node:os';
import { copyFile, cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { delay, nativeProjectConfig, pluginRoot } from './hyperframes.ts';
import { validateProject, duration } from './shared/legacy.ts';
import type { Project as LegacyProject } from './shared/legacy.ts';
import { exportExpectation } from './shared/export-expectation.ts';
import type { ExportExpectation } from './shared/export-spec.ts';
import { validateInstruction, type ProjectConversation, type ProjectMessage } from './shared/conversation.ts';
import { creationMode, type CreativeSession, type SessionDetail } from './shared/session.ts';
import { templateConfig } from './shared/template-config.ts';
const legacyDataDir = fileURLToPath(new URL('.motion-data/', import.meta.url));
const productionDataDir = process.platform === 'darwin' && !existsSync(legacyDataDir)
? path.join(os.homedir(), 'Library', 'Application Support', 'OpenDesign') : legacyDataDir;
export const defaultDataDir = process.env.MOTION_DATA_DIR || (templateConfig().environment === 'dev' ? path.resolve(productionDataDir) + '-dev' : productionDataDir);
const ignored = new Set(['node_modules', 'renders', 'dist', 'output']);
const textExtensions = new Set(['.html', '.css', '.js', '.mjs', '.json', '.svg', '.txt', '.md', '.vtt', '.srt', '.glsl', '.vert', '.frag']);
// Hyperframes 0.9.7 includes these native Studio manifests in render inputs.
// Everything else in .hyperframes is a cache and must not change a revision.
const studioManifests = ['.hyperframes/studio-manual-edits.json', '.hyperframes/studio-motion.json'];
export type SourceFile = { path: string; size: number; hash: string };
export type FileEdit = { path: string; content: string };
export type SavedProject = { id: string; title: string; templateId?: string; createdAt?: number; openedAt?: number };
export type ProjectCatalog = { activeId: string; projects: SavedProject[]; sessions?: CreativeSession[]; activeSessionId?: string };
export type ExportJob = { id: string; projectId?: string; versionId?: string; requestId?: string; phase1?: boolean; stage?: string; verification?: unknown; revision: string; state: 'pending' | 'running' | 'cancelling' | 'cancelled' | 'completed' | 'failed';
createdAt: number; expiresAt: number; token?: string; workerPid?: number; file?: string; outputName?: string; error?: string; expected?: ExportExpectation };
export class Conflict extends Error { constructor() { super('工程已经被 Studio 或 Agent 更新,请重新读取 revision 后再修改。'); } }
export function projectPath(name: string): string {
if (studioManifests.includes(name)) return name;
if (typeof name !== 'string' || !name || name.length > 240 || name.includes('\\') || name.includes(':') || /[\x00-\x1f]/.test(name)
|| name.split('/').some(part => !part || part.startsWith('.') || ignored.has(part))) throw new Error('工程文件路径无效:' + name);
return name;
}
function alive(pid?: number) { try { if (!pid) return false; process.kill(pid, 0); return true; } catch { return false; } }
async function atomic(filename: string, content: string | Buffer) {
await mkdir(path.dirname(filename), { recursive: true });
const temporary = path.join(path.dirname(filename), '.motion-write-' + crypto.randomUUID());
try { await writeFile(temporary, content, { mode: 0o600 }); await rename(temporary, filename); }
finally { await rm(temporary, { force: true }); }
}
export class WorkspaceStore {
directory: string;
hashes = new Map<string, { signature: string; hash: string }>();
selectedProjectId?: string;
workspaceStore?: WorkspaceStore;
constructor(directory = defaultDataDir, projectId?: string) { this.directory = path.resolve(directory); this.selectedProjectId = projectId; }
get projectId() { return this.selectedProjectId ?? this.projectCatalog().activeId; }
forProject(id: string) {
if (!this.projectCatalog().projects.some(project => project.id === id)) throw new Error('PROJECT_NOT_FOUND: 工程不存在');
this.projectDirectoryFor(id);
const scoped = new WorkspaceStore(this.directory, id);
scoped.workspaceStore = this.workspaceStore ?? this;
return scoped;
}
projectDirectoryFor(id: string) {
if (id === 'project') return path.join(this.directory, 'project');
if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id)) throw new Error('工程编号无效');
return path.join(this.directory, 'projects', id);
}
projectCatalog(): ProjectCatalog {
let catalog: ProjectCatalog;
try { catalog = JSON.parse(readFileSync(path.join(this.directory, 'projects.json'), 'utf8')); }
catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') catalog = { activeId: 'project', projects: [{ id: 'project', title: '初始工程' }] };
else throw error;
}
if (!Array.isArray(catalog.projects) || !catalog.projects.some(item => item.id === catalog.activeId)) throw new Error('工程目录记录损坏');
for (const item of catalog.projects) { this.projectDirectoryFor(item.id); if (typeof item.title !== 'string') throw new Error('工程名称无效'); }
// Legacy conversations keep their IDs and files; all new sessions own artifact IDs.
catalog.sessions ??= catalog.projects.map(project => ({ ...project, mode: 'motion', artifacts: [{ id: project.id, kind: 'motion-project', projectId: project.id, title: project.title, templateId: project.templateId }] }));
catalog.activeSessionId ??= catalog.sessions.find(session => session.artifacts.some(artifact => artifact.projectId === catalog.activeId))?.id;
const owners = new Set<string>(), sessionIds = new Set<string>(), artifactIds = new Set<string>();
for (const session of catalog.sessions) {
this.projectDirectoryFor(session.id); creationMode(session.mode);
if (sessionIds.has(session.id) || typeof session.title !== 'string') throw new Error('会话记录损坏');
sessionIds.add(session.id);
if (!Array.isArray(session.artifacts) || session.artifacts.some(artifact => !catalog.projects.some(project => project.id === artifact.projectId))) throw new Error('会话产物记录损坏');
for (const artifact of session.artifacts) {
if (artifact.kind !== 'motion-project' || typeof artifact.id !== 'string' || artifactIds.has(artifact.id) || owners.has(artifact.projectId)) throw new Error('会话产物归属记录损坏');
artifactIds.add(artifact.id); owners.add(artifact.projectId);
artifact.title = catalog.projects.find(project => project.id === artifact.projectId)!.title;
}
session.activeArtifactId = session.artifacts.find(item => item.id === session.activeArtifactId)?.id ?? session.artifacts[0]?.id;
}
if (owners.size !== catalog.projects.length || !catalog.sessions.some(item => item.id === catalog.activeSessionId)) throw new Error('会话产物归属记录损坏');
return catalog;
}
get projectDirectory() { return this.projectDirectoryFor(this.projectId); }
async createSession(input: { id?: string; mode: string; title: string; templateId?: string; instruction?: string }) {
const mode = creationMode(input.mode), title = validateProjectTitle(input.title);
const instruction = input.instruction === undefined ? undefined : validateInstruction(input.instruction);
const id = input.id ?? crypto.randomUUID(); this.projectDirectoryFor(id);
return this.lock(async () => {
const catalog = this.projectCatalog(), existing = catalog.sessions!.find(item => item.id === id);
if (existing) {
const session = await this.session(id);
if (session.title !== title || session.mode !== mode.id || session.templateId !== input.templateId || session.messages[0]?.content !== instruction) throw new Error('会话编号已使用');
return session;
}
const session: CreativeSession = { id, title, mode: mode.id, templateId: input.templateId, artifacts: [], createdAt: Date.now(), openedAt: Date.now() };
const messages: ProjectMessage[] = instruction ? [{ id: crypto.randomUUID(), role: 'user', content: instruction, createdAt: Date.now() }] : [];
catalog.sessions!.unshift(session); catalog.activeSessionId = id;
const file = path.join(this.directory, 'sessions', id + '.json');
await atomic(file, JSON.stringify({ sessionId: id, messages }));
try { await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); }
catch (error) { await rm(file, { force: true }); throw error; }
return { ...session, messages };
});
}
async selectSession(id: string) {
return this.lock(async () => {
const catalog = this.projectCatalog(), session = catalog.sessions!.find(item => item.id === id);
if (!session) throw new Error('会话不存在');
catalog.activeSessionId = id; session.openedAt = Date.now();
await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog));
return { sessionId: id, session };
});
}
// Called while holding the workspace lock, after the candidate Studio is ready.
async selectProject(id: string, entry?: SavedProject, instruction?: string, sessionTarget?: { sessionId?: string; title?: string; templateId?: string }) {
this.projectDirectoryFor(id);
const catalog = this.projectCatalog();
if (entry) {
if (entry.id !== id || catalog.projects.some(item => item.id === id)) throw new Error('工程编号已存在');
catalog.projects.unshift(entry);
}
if (!catalog.projects.some(item => item.id === id)) throw new Error('工程不存在');
catalog.activeId = id;
catalog.projects.find(item => item.id === id)!.openedAt = Date.now();
let session = catalog.sessions!.find(item => sessionTarget?.sessionId ? item.id === sessionTarget.sessionId : item.artifacts.some(artifact => artifact.projectId === id));
if (sessionTarget?.sessionId && !session) throw new Error('会话不存在');
const creatingSession = !session;
if (!session) {
session = { id: crypto.randomUUID(), title: sessionTarget?.title || entry!.title, mode: 'motion', createdAt: Date.now(), artifacts: [], templateId: sessionTarget?.templateId || entry?.templateId };
catalog.sessions!.unshift(session);
}
if (entry) session.artifacts.push({ id: crypto.randomUUID(), kind: 'motion-project', projectId: id, title: entry.title, templateId: entry.templateId ?? sessionTarget?.templateId });
const artifact = session.artifacts.find(item => item.projectId === id);
if (!artifact) throw new Error('该产物不属于此会话');
session.activeArtifactId = artifact.id;
session.openedAt = Date.now(); catalog.activeSessionId = session.id;
const conversationFile = path.join(this.directory, 'sessions', session.id + '.json');
if (instruction && creatingSession) await atomic(conversationFile, JSON.stringify({ sessionId: session.id, messages: [{ id: crypto.randomUUID(), role: 'user', content: validateInstruction(instruction), createdAt: Date.now() }] }));
try { await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog)); }
catch (error) { if (instruction && creatingSession) await rm(conversationFile, { force: true }); throw error; }
if (this.selectedProjectId !== undefined) this.selectedProjectId = id;
}
async session(id: string): Promise<SessionDetail> {
this.projectDirectoryFor(id);
const session = this.projectCatalog().sessions!.find(item => item.id === id);
if (!session) throw new Error('会话不存在');
try { return { ...session, messages: JSON.parse(await readFile(path.join(this.directory, 'sessions', id + '.json'), 'utf8')).messages }; }
catch (error) {
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { ...session, messages: [] };
throw error;
}
}
async conversation(projectId: string): Promise<ProjectConversation> {
const session = this.projectCatalog().sessions!.find(item => item.artifacts.some(artifact => artifact.projectId === projectId));
if (!session) throw new Error('工程不存在');
return { projectId, messages: (await this.session(session.id)).messages };
}
async addProjectMessage(projectId: string, id: string, content: string) {
const session = this.projectCatalog().sessions!.find(item => item.artifacts.some(artifact => artifact.projectId === projectId));
if (!session) throw new Error('工程不存在');
return { projectId, messages: (await this.addSessionMessage(session.id, id, content)).messages };
}
async addSessionMessage(sessionId: string, id: string, content: string, role: 'user' | 'assistant' = 'user') {
content = validateInstruction(content);
if (!['user', 'assistant'].includes(role)) throw new Error('消息角色无效');
if (typeof id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id)) throw new Error('消息编号无效');
return this.lock(async () => {
const conversation = await this.session(sessionId);
const existing = conversation.messages.find(message => message.id === id);
if (existing) {
if (existing.content !== content || existing.role !== role) throw new Error('消息编号已使用');
return conversation;
}
if (conversation.messages.length >= 200) throw new Error('此会话已保存 200 条创作需求');
const message: ProjectMessage = { id, role, content, createdAt: Date.now() };
conversation.messages.push(message);
await atomic(path.join(this.directory, 'sessions', sessionId + '.json'), JSON.stringify({ sessionId, messages: conversation.messages }));
return conversation;
});
}
async renameSession(id: string, title: string) {
title = validateProjectTitle(title);
return this.lock(async () => {
const catalog = this.projectCatalog(), session = catalog.sessions!.find(item => item.id === id);
if (!session) throw new Error('会话不存在');
session.title = title;
await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog));
return catalog;
});
}
async renameProject(id: string, title: string) {
title = validateProjectTitle(title);
return this.lock(async () => {
const catalog = this.projectCatalog();
const project = catalog.projects.find(item => item.id === id);
if (!project) throw new Error('工程不存在');
project.title = title;
await atomic(path.join(this.directory, 'projects.json'), JSON.stringify(catalog));
return catalog;
});
}
get jobFilename() { return path.join(this.directory, 'export.json'); }
async lock<T>(change: () => Promise<T>): Promise<T> {
await mkdir(this.directory, { recursive: true });
const lockPath = path.join(this.directory, 'workspace.lock');
let lock; const end = Date.now() + 30_000;
while (!lock) {
try { lock = await open(lockPath, 'wx', 0o600); }
catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
if (Date.now() > end) throw new Error('工程正在被另一进程使用,请检查 workspace.lock');
await delay(25);
}
}
try { return await change(); }
finally { await lock.close(); await rm(lockPath, { force: true }); }
}
async safePath(name: string, directory = this.projectDirectory) {
projectPath(name);
let target = directory;
for (const part of ['', ...name.split('/')]) {
if (part) target = path.join(target, part);
try { if ((await lstat(target)).isSymbolicLink()) throw new Error('工程不支持符号链接:' + name); }
catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
}
return target;
}
async files(directory = this.projectDirectory): Promise<SourceFile[]> {
const files: SourceFile[] = [];
const collect = async (name: string) => {
const filename = await this.safePath(name, directory), info = await stat(filename);
if (!info.isFile()) throw new Error('工程源文件类型无效:' + name);
const signature = `${info.ino}:${info.mtimeMs}:${info.ctimeMs}:${info.size}`;
let cached = this.hashes.get(filename);
if (!cached || cached.signature !== signature) {
const hash = createHash('sha256');
for await (const chunk of createReadStream(filename)) hash.update(chunk);
cached = { signature, hash: hash.digest('hex') }; this.hashes.set(filename, cached);
}
files.push({ path: name, size: info.size, hash: cached.hash });
if (files.length > 5000) throw new Error('工程文件数超过 5000');
};
const walk = async (folder: string) => {
for (const entry of await readdir(path.join(directory, folder), { withFileTypes: true })) {
if (entry.name.startsWith('.') || ignored.has(entry.name)) continue;
const name = folder ? folder + '/' + entry.name : entry.name;
projectPath(name);
if (entry.isSymbolicLink()) throw new Error('工程不支持符号链接:' + name);
if (entry.isDirectory()) await walk(name);
else if (entry.isFile()) await collect(name);
}
};
await this.safePath('index.html', directory);
try { await lstat(directory); }
catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error; }
await walk('');
for (const name of studioManifests) {
try { await collect(name); }
catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
}
return files.sort((a, b) => a.path.localeCompare(b.path));
}
revision(files: SourceFile[]) { return createHash('sha256').update(JSON.stringify(files)).digest('hex'); }
async get() {
const directory = this.projectDirectory;
const files = await this.files(directory);
const index = files.find(file => file.path === 'index.html');
return { revision: this.revision(files), project: index ? {
format: 'hyperframes' as const, entry: 'index.html', directory, files,
html: index.size <= 2 * 1024 * 1024 ? await readFile(path.join(directory, 'index.html'), 'utf8') : undefined,
} : null };
}
async readFile(name: string) {
if (!textExtensions.has(path.extname(projectPath(name)))) throw new Error('此工具只读取文本源文件;媒体请使用文件路径');
const filename = await this.safePath(name);
if ((await stat(filename)).size > 2 * 1024 * 1024) throw new Error('源文件超过 2 MB,请使用本地文件工具读取');
return { path: name, content: await readFile(filename, 'utf8') };
}
async writeFiles(expectedRevision: string, edits: FileEdit[]) {
if (!Array.isArray(edits) || !edits.length || edits.length > 100) throw new Error('一次需要提交 1–100 个源文件');
const names = new Set<string>(); let size = 0;
for (const file of edits) {
if (!file || typeof file.content !== 'string') throw new Error('源文件需要 path 和 content');
projectPath(file.path);
if (!textExtensions.has(path.extname(file.path))) throw new Error('请用 motion_import_asset 导入媒体文件');
if (names.has(file.path)) throw new Error('提交包含重复文件');
names.add(file.path); size += Buffer.byteLength(file.content);
}
if (size > 8 * 1024 * 1024) throw new Error('一次提交不能超过 8 MB');
return this.lock(async () => {
const current = await this.get();
if (current.revision !== expectedRevision) throw new Conflict();
if (!current.project && !names.has('index.html')) throw new Error('新工程必须包含 index.html');
const paths = await Promise.all(edits.map(file => this.safePath(file.path)));
if ((await this.get()).revision !== expectedRevision) throw new Conflict();
for (let i = 0; i < edits.length; i++) await atomic(paths[i], edits[i].content);
return this.get();
});
}
async importAsset(expectedRevision: string, sourcePath: string, targetPath: string) {
if (!path.isAbsolute(sourcePath)) throw new Error('素材来源必须是本地绝对路径');
projectPath(targetPath);
if (!targetPath.startsWith('assets/')) throw new Error('素材目标必须位于 assets/');
const source = await stat(sourcePath);
if (!isAssetFileWithinLimit(source)) throw new Error('素材必须是不超过 500 MB(500000000 字节)的文件');
return this.lock(async () => {
if ((await this.get()).revision !== expectedRevision) throw new Conflict();
const target = await this.safePath(targetPath);
await mkdir(path.dirname(target), { recursive: true });
const temporary = path.join(path.dirname(target), '.motion-import-' + crypto.randomUUID());
try {
await copyFile(sourcePath, temporary);
if (!isAssetFileWithinLimit(await stat(temporary))) throw new Error('素材必须是不超过 500 MB(500000000 字节)的文件');
if ((await this.get()).revision !== expectedRevision) throw new Conflict();
await rename(temporary, target);
} finally { await rm(temporary, { force: true }); }
return this.get();
});
}
async initialize(runtimeRoot: string) {
return this.lock(() => this.initializeLocked(runtimeRoot));
}
// The caller must hold the workspace lock, as project switching already does.
async initializeLocked(runtimeRoot: string) {
if ((await this.get()).project) return;
if ((await this.files()).length) throw new Error('工程目录已有文件但缺少 index.html,请先修复入口');
const staging = path.join(this.directory, 'initialize-' + crypto.randomUUID());
await mkdir(path.join(staging, 'assets'), { recursive: true });
try {
let legacy: LegacyProject | null = null;
try {
const old = JSON.parse(await readFile(path.join(this.directory, 'workspace.json'), 'utf8'));
if (old.project) legacy = validateProject(old.project);
} catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
if (legacy) await migrateLegacy(legacy, staging);
else await cp(path.join(pluginRoot, 'templates'), staging, { recursive: true });
await copyFile(path.join(runtimeRoot, 'node_modules/gsap/dist/gsap.min.js'), path.join(staging, 'assets/gsap.min.js'));
await writeFile(path.join(staging, 'hyperframes.json'), JSON.stringify(nativeProjectConfig, null, 2));
// The legacy workspace.json remains untouched. Never replace an existing native entry.
try { await rename(staging, this.projectDirectory); }
catch (error) { throw new Error('无法创建 Hyperframes 工程,已有目录保持不变', { cause: error }); }
} finally { await rm(staging, { recursive: true, force: true }); }
}
exportPath(job: ExportJob) {
return job.outputName ? path.join(this.directory, 'exports', job.id, job.outputName) : path.join(this.directory, 'exports', job.id + '.mp4');
}
async job(id?: string): Promise<ExportJob | null> {
if (id && !/^[a-f0-9-]{36}$/.test(id)) throw new Error('无效的导出任务编号');
try {
const value = JSON.parse(await readFile(id ? path.join(this.directory, 'jobs', id, 'job.json') : this.jobFilename, 'utf8'));
if (id) return value;
return await this.job(value.id) ?? value;
}
catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; }
}
async saveJob(job: ExportJob) {
await atomic(path.join(this.directory, 'jobs', job.id, 'job.json'), JSON.stringify(job));
const current = await this.job();
if (!current || current.id === job.id) await atomic(this.jobFilename, JSON.stringify(job));
}
async status(jobId?: string) {
const current = await this.get();
let job = await this.job(jobId);
if (this.selectedProjectId !== undefined && job?.projectId && job.projectId !== this.projectId) job = null;
if (job && ['pending', 'running', 'cancelling'].includes(job.state) && (job.expiresAt < Date.now() || (job.state !== 'pending' && !alive(job.workerPid)))) {
job.state = 'failed'; job.error = '后台渲染已中断或超时,请重新导出';
await this.saveJob(job);
}
if (job?.state === 'completed') {
try { if (!(await stat(this.exportPath(job))).size) throw new Error('empty'); }
catch { job.state = 'failed'; job.error = '导出文件已不存在,请重新导出'; delete job.file; await this.saveJob(job); }
}
if (job) { delete job.token; delete job.workerPid; }
const catalog = this.projectCatalog();
// A newly opened empty conversation must not be reported as owner of the last native project.
const sessionId = catalog.sessions!.find(item => item.artifacts.some(artifact => artifact.projectId === this.projectId))!.id;
return { revision: current.revision, hasProject: Boolean(current.project), projectId: this.projectId, projectTitle: catalog.projects.find(item => item.id === this.projectId)!.title, sessionId, activeSessionId: catalog.activeSessionId, exportJob: job };
}
snapshotDirectory(id: string) { return path.join(this.directory, 'jobs', id, 'project'); }
async requestExport(expectedRevision: string, options: Partial<Pick<ExportJob, 'phase1' | 'versionId' | 'requestId'>> & { audio?: ExportExpectation['audio'] } = {}) {
return this.lock(async () => {
const current = await this.get();
if (current.revision !== expectedRevision) throw new Conflict();
if (!current.project) throw new Error('还没有 Hyperframes 工程');
const previous = await this.job();
if (previous && ['pending', 'running', 'cancelling'].includes(previous.state) && previous.expiresAt > Date.now() && (previous.state === 'pending' || alive(previous.workerPid))) throw new Error('EXPORT_BUSY: 已有导出任务正在等待或运行');
const { audio, ...identity } = options;
const job: ExportJob = { ...identity, id: crypto.randomUUID(), projectId: this.projectId, revision: expectedRevision, state: 'pending', stage: 'queued', createdAt: Date.now(), expiresAt: Date.now() + 30 * 60_000 };
job.outputName = renderFilenameStem(this.projectCatalog().projects.find(project => project.id === this.projectId)?.title) + '.mp4';
const snapshot = this.snapshotDirectory(job.id);
try {
for (const file of current.project.files) {
const source = await this.safePath(file.path);
const destination = path.join(snapshot, file.path);
await mkdir(path.dirname(destination), { recursive: true }); await copyFile(source, destination);
}
if (this.revision(await this.files(snapshot)) !== expectedRevision || (await this.get()).revision !== expectedRevision) throw new Conflict();
job.expected = await exportExpectation(this.directory, snapshot);
if (audio) job.expected.audio = audio;
await atomic(path.join(this.directory, 'jobs', job.id, 'job.json'), JSON.stringify(job));
await atomic(this.jobFilename, JSON.stringify(job));
return job;
} catch (error) { await rm(path.dirname(snapshot), { recursive: true, force: true }); throw error; }
});
}
async claimExport() {
return this.lock(async () => {
const job = await this.job();
if (!job || job.state !== 'pending' || job.expiresAt < Date.now()) return null;
job.state = 'running'; job.token = crypto.randomUUID(); job.workerPid = process.pid;
await this.saveJob(job); return job;
});
}
async finishExport(id: string, token: string, error?: string) {
return this.lock(async () => {
const job = await this.job(id) ?? await this.job();
if (!job || job.id !== id || job.token !== token || !['running', 'cancelling'].includes(job.state)) throw new Error('无效的导出任务凭据');
if (job.state === 'cancelling') {
job.state = 'cancelled'; job.stage = 'cancelled'; delete job.token; delete job.workerPid;
await this.saveJob(job); return job;
}
if (!error && !(await stat(this.exportPath(job))).size) throw new Error('Hyperframes 未生成视频');
job.state = error ? 'failed' : 'completed'; job.stage = job.state;
if (error) job.error = error.slice(-2000); else job.file = path.relative(this.directory, this.exportPath(job)).split(path.sep).join('/');
delete job.token; delete job.workerPid;
await this.saveJob(job); return job;
});
}
}
const escape = (value: string) => value.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>').replaceAll('"', '"');
export function validateProjectTitle(value: unknown): string {
if (typeof value !== 'string' || !value.trim() || value.trim().length > 100 || /[\x00-\x1f]/.test(value)) throw new Error('项目名称需要 1–100 个字符');
return value.trim();
}
/** An empty native composition, ready for Studio uploads and timeline edits. */
export async function createBlankProject(directory: string, runtimeRoot: string, title: string) {
await mkdir(path.join(directory, 'assets'), { recursive: true });
await copyFile(path.join(runtimeRoot, 'node_modules/gsap/dist/gsap.min.js'), path.join(directory, 'assets/gsap.min.js'));
await writeFile(path.join(directory, 'hyperframes.json'), JSON.stringify(nativeProjectConfig, null, 2));
await writeFile(path.join(directory, 'index.html'), `<!doctype html>
<html lang="zh-CN"><head><meta charset="utf-8"><title>${escape(title)}</title>
<script src="assets/gsap.min.js"></script>
<style>body{margin:0}#main{position:relative;width:1920px;height:1080px;overflow:hidden;background:#000}</style></head>
<body><div id="main" data-composition-id="main" data-start="0" data-duration="10" data-width="1920" data-height="1080" data-fps="30"></div>
<script>window.__timelines = {main: gsap.timeline({paused:true})};</script></body></html>`);
}
async function migrateLegacy(project: LegacyProject, directory: string) {
const assets = new Map<string, string>();
for (const [i, asset] of project.assets.entries()) {
const match = asset.data.match(/^data:[^/]+\/([^;]+);base64,([\s\S]+)$/)!;
const name = `assets/media-${i}.${match[1] === 'quicktime' ? 'mov' : match[1]}`;
await writeFile(path.join(directory, name), Buffer.from(match[2], 'base64')); assets.set(asset.id, name);
}
let start = 0;
const clips: string[] = [];
await mkdir(path.join(directory, 'compositions'), { recursive: true });
for (const [i, shot] of project.shots.entries()) {
const id = `shot-${i}`;
const asset = project.assets.find(item => item.id === shot.assetId);
const media = asset ? `<${asset.type === 'video' ? 'video muted playsinline' : 'img'} id="media-${i}" class="clip" src="${assets.get(asset.id)}" data-start="0" data-duration="${shot.duration}" data-track-index="0" ${asset.type === 'video' ? `data-media-start="${shot.start}"` : ''} style="position:absolute;width:540px;height:960px;object-fit:${shot.fit}" ${asset.type === 'video' ? '></video>' : '>'}` : '';
const position = { top: 'top:80px', center: 'top:380px', bottom: 'bottom:100px' }[shot.position];
await writeFile(path.join(directory, 'compositions', id + '.html'), `<template>
<style>#${id}-root{position:absolute;inset:0;font-family:Inter,sans-serif;overflow:hidden}#${id}-bg{position:absolute;inset:0;background:#203021}#${id}-caption{position:absolute;left:40px;right:40px;${position};text-align:center;color:white;text-shadow:0 2px 8px #000}#${id}-caption h1{font-size:38px;white-space:pre-wrap}#${id}-caption p{font-size:22px;white-space:pre-wrap}</style>
<div id="${id}-root" data-composition-id="${id}" data-width="540" data-height="960" data-duration="${shot.duration}"><div id="${id}-bg"></div>${media}<div id="${id}-caption"><h1>${escape(shot.caption)}</h1><p style="color:${shot.accent}">${escape(shot.subtitle)}</p></div></div>
<script>window.__timelines = window.__timelines || {}; window.__timelines['${id}'] = gsap.timeline({paused:true});</script></template>`);
clips.push(`<div id="${id}" class="clip" data-composition-id="${id}" data-composition-src="compositions/${id}.html" data-start="${start}" data-duration="${shot.duration}" data-track-index="0" data-width="540" data-height="960"></div>`);
start += shot.duration;
}
await writeFile(path.join(directory, 'index.html'), `<!doctype html>
<html lang="zh-CN"><head><meta charset="utf-8"><title>${escape(project.title)}</title><script src="assets/gsap.min.js"></script>
<style>body{margin:0}#main{position:relative;width:540px;height:960px;overflow:hidden}</style></head>
<body><div id="main" data-composition-id="main" data-start="0" data-duration="${duration(project)}" data-width="540" data-height="960" data-fps="24">${clips.join('\n')}</div>
<script>window.__timelines = {main: gsap.timeline({paused:true})};</script></body></html>`);
}