LumosLab-Innovation/3D-lab-skills / plugins/threejs-lab/skills/threejs-studio
threejs-studio
VerifiedCreate image options, get human approval on localhost, author geometry in Three.js or Blender MCP, then code Three.js motion, contraction and interaction for either model. Use for prompt-to-3D, image-to-model, animated interactive assets or resuming visual approval across coding agents. No paid image-to-3D service.
| File | Kind | Size |
|---|---|---|
| .npmignore | other | 51 B |
| SKILL.md | skill md | 5.9 KB |
| agents/openai.yaml | config | 269 B |
| assets/examples/blender-pulse.py | script | 2.2 KB |
| assets/examples/pulse-behavior.mjs | script | 1.6 KB |
| assets/examples/pulse-model.mjs | script | 1012 B |
| package-lock.json | manifest | 14.0 KB |
| package.json | manifest | 235 B |
| references/blender-setup.md | markdown | 1.1 KB |
| references/blender.md | markdown | 3.0 KB |
| references/hard-surface.md | markdown | 4.3 KB |
| references/image-options.md | markdown | 1.5 KB |
| references/licenses/img2threejs.txt | markdown | 11.1 KB |
| references/licenses/vibe3d.txt | markdown | 1.1 KB |
| references/motion-interaction.md | markdown | 3.9 KB |
| references/reconstruction.md | markdown | 2.3 KB |
| references/threejs.md | markdown | 2.8 KB |
| scripts/blender_export.py | script | 2.2 KB |
| scripts/cli.mjs | script | 6.2 KB |
| scripts/server.mjs | script | 7.7 KB |
| scripts/state.mjs | script | 9.8 KB |
| web/app.js | script | 7.8 KB |
| web/index.html | other | 3.7 KB |
| web/motion.js | script | 2.1 KB |
| web/style.css | other | 8.2 KB |
| web/viewer.html | other | 3.8 KB |
| web/viewer.js | script | 11.6 KB |
scripts/state.mjs
View on GitHubimport { createHash, randomUUID } from "node:crypto";
import { mkdir, readFile, writeFile, rename, realpath } from "node:fs/promises";
import { join, resolve, relative, isAbsolute, extname } from "node:path";
export function requireValue(value, message) {
if (!value) throw new Error(message);
}
export function text(value, name, limit = 4000) {
requireValue(typeof value === "string" && value.trim() && value.length <= limit, `Invalid ${name}`);
return value.trim();
}
export function engine(value) {
requireValue(["threejs", "blender"].includes(value), "Engine must be threejs or blender");
return value;
}
export const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
export const load = async (dir) => JSON.parse(await readFile(join(dir, "studio.json"), "utf8"));
export async function save(dir, state) {
const pending = join(dir, `.${randomUUID()}.json`);
await writeFile(pending, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
await rename(pending, join(dir, "studio.json"));
}
export async function init(dir, prompt, selectedEngine = "threejs") {
const state = {
schemaVersion: 1, id: randomUUID(), prompt: text(prompt, "prompt"), engine: engine(selectedEngine),
revision: 0, stage: "awaiting_images", imageRound: 1, modelRound: 1,
images: [], models: [], imageApproval: null, modelApproval: null, feedback: [],
};
await mkdir(dir, { recursive: true });
await writeFile(join(dir, "studio.json"), JSON.stringify(state, null, 2) + "\n", { flag: "wx", mode: 0o600 });
return state;
}
// Serve only registered snapshots, never an arbitrary project directory or a symlink escape.
export async function artifactPath(dir, file) {
requireValue(typeof file === "string" && !file.includes("\\") && !isAbsolute(file), "Invalid artifact path");
const root = await realpath(dir);
const result = await realpath(resolve(root, file));
const rel = relative(root, result);
requireValue(rel && !rel.startsWith("..") && !isAbsolute(rel), "Artifact escaped workspace");
return result;
}
async function snapshot(dir, id, name, bytes) {
requireValue(/^[\w./-]+$/.test(name) && !name.split("/").includes(".."), "Invalid snapshot name");
const file = `artifacts/${id}/${name}`;
await mkdir(join(dir, "artifacts", id), { recursive: true });
const destination = resolve(dir, file);
// No existing paths are overwritten, even when the agent reuses an input filename.
await writeFile(destination, bytes, { flag: "wx" });
return { file, sha256: hash(bytes), bytes: bytes.length };
}
function imageExtension(bytes) {
if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return ".png";
if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return ".jpg";
if (bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") return ".webp";
throw new Error("Image must be PNG, JPEG or WebP (SVG/HTML are not accepted)");
}
export async function addImage(dir, state, input) {
requireValue(!state.imageApproval, "Reference is already approved; request a new reference in the studio first");
const bytes = await readFile(text(input.file, "file"));
requireValue(bytes.length <= 25 * 1024 * 1024, "Image exceeds 25 MB");
const extension = imageExtension(bytes);
const id = randomUUID();
const item = { id, title: text(input.title, "title", 120), round: state.imageRound,
provenance: text(input.provenance, "image provenance", 1000),
...await snapshot(dir, id, `reference${extension}`, bytes) };
state.images.push(item);
state.stage = "image_review";
state.revision++;
await save(dir, state);
return item;
}
export async function approvedReference(dir, state) {
requireValue(state.imageApproval, "Approve a reference image in the browser before building 3D");
const item = state.images.find((image) => image.id === state.imageApproval.id);
requireValue(item && hash(await readFile(await artifactPath(dir, item.file))) === state.imageApproval.sha256,
"Approved reference changed on disk; restore it or request a new reference");
return item;
}
async function bundleSource(dir, id, source, output, requiredExport) {
requireValue([".mjs", ".js", ".ts"].includes(extname(source)), "Expected an ESM JS/TS source module");
const { build } = await import("esbuild");
const result = await build({ entryPoints: [resolve(source)], bundle: true, write: false,
format: "esm", platform: "browser", external: ["three", "three/*"], metafile: true,
loader: { ".png": "dataurl", ".jpg": "dataurl", ".webp": "dataurl" }, logLevel: "silent" });
requireValue(result.metafile.outputs[Object.keys(result.metafile.outputs)[0]].exports.includes(requiredExport), `Module must export ${requiredExport}`);
const sources = {};
for (const filename of Object.keys(result.metafile.inputs)) {
requireValue(!filename.includes("node_modules"), "Keep model dependencies to Three.js and local source files");
sources[filename] = (await readFile(resolve(filename))).toString("base64");
}
return [await snapshot(dir, id, output, result.outputFiles[0].contents),
await snapshot(dir, id, "sources.json", Buffer.from(JSON.stringify(sources, null, 2)))];
}
export async function addModel(dir, state, input) {
const reference = await approvedReference(dir, state);
requireValue(input.reference === reference.sha256, "Model reference hash does not match the approved image");
requireValue(["building", "model_review"].includes(state.stage), "Request changes before adding another model");
const title = text(input.title, "title", 120);
const source = text(input.file, "file");
const id = randomUUID();
const files = [];
let entry, behavior;
if (state.engine === "threejs") {
files.push(...await bundleSource(dir, id, source, "model.mjs", "createModel"));
entry = files[0];
} else {
const behaviorSource = text(input.behavior, "Three.js --behavior source for the Blender asset");
const bytes = await readFile(source);
requireValue(bytes.length <= 100 * 1024 * 1024 && bytes.length >= 20 &&
bytes.toString("ascii", 0, 4) === "glTF" && bytes.readUInt32LE(4) === 2 &&
bytes.readUInt32LE(8) === bytes.length, "Expected a valid GLB v2, at most 100 MB");
const jsonLength = bytes.readUInt32LE(12);
requireValue(bytes.readUInt32LE(16) === 0x4e4f534a && jsonLength <= bytes.length - 20, "Invalid GLB JSON chunk");
const gltf = JSON.parse(bytes.toString("utf8", 20, 20 + jsonLength));
requireValue([...(gltf.buffers || []), ...(gltf.images || [])].every((part) => !part.uri || part.uri.startsWith("data:")),
"GLB must embed buffers/textures; external URLs are not allowed");
entry = await snapshot(dir, id, "model.glb", bytes);
files.push(entry);
const scripted = await bundleSource(dir, id, behaviorSource, "behavior.mjs", "createBehavior");
files.push(...scripted); behavior = scripted[0].file;
if (input.blend) {
const blend = await readFile(input.blend);
requireValue(blend.toString("ascii", 0, 7) === "BLENDER", "Invalid uncompressed .blend file");
files.push(await snapshot(dir, id, "model.blend", blend));
}
}
const item = { id, title, engine: state.engine, round: state.modelRound,
reference: reference.sha256, entry: entry.file, ...(behavior ? { behavior } : {}), sha256: entry.sha256, files };
state.models.push(item);
state.stage = "model_review";
state.revision++;
await save(dir, state);
return item;
}
export async function decide(dir, state, input, viewed) {
requireValue(input.revision === state.revision, "Studio changed; refresh before deciding");
if (input.action === "approve-image") {
requireValue(state.stage === "image_review", "No image awaiting approval");
const item = state.images.find((x) => x.id === input.id && x.round === state.imageRound);
requireValue(item && input.sha256 === item.sha256, "Image is not in this review round");
requireValue(hash(await readFile(await artifactPath(dir, item.file))) === item.sha256, "Image changed on disk");
state.imageApproval = { id: item.id, sha256: item.sha256, at: new Date().toISOString(), source: "browser" };
state.engine = engine(input.engine);
state.stage = "building";
} else if (input.action === "approve-model") {
requireValue(state.stage === "model_review", "No model awaiting approval");
const item = state.models.find((x) => x.id === input.id && x.round === state.modelRound);
requireValue(item && input.sha256 === item.sha256 && viewed.has(item.id), "Open a working 3D preview before approving");
await approvedReference(dir, state);
for (const file of item.files) requireValue(hash(await readFile(await artifactPath(dir, file.file))) === file.sha256, "Model changed on disk");
state.modelApproval = { id: item.id, sha256: item.sha256, at: new Date().toISOString(), source: "browser" };
state.stage = "accepted";
} else if (input.action === "revise") {
requireValue(["image_review", "building", "model_review", "accepted"].includes(state.stage), "Nothing to revise yet");
requireValue(["image", "model"].includes(input.target), "Select image or model");
state.feedback.push({ target: input.target, note: text(input.note, "feedback", 2000), at: new Date().toISOString() });
if (input.target === "image") {
state.imageRound++;
state.imageApproval = null;
state.stage = "awaiting_images";
} else {
requireValue(state.imageApproval, "Approve an image first");
state.stage = "building";
}
state.modelRound++;
state.modelApproval = null;
} else throw new Error("Unknown decision");
state.revision++;
await save(dir, state);
}
export function next(state) {
const actions = { awaiting_images: "generate_images", image_review: "wait_for_user_image_approval",
building: "build_model", model_review: "wait_for_user_model_approval", accepted: "deliver" };
return { ...state, nextAction: actions[state.stage] };
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |