Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// three.ws 3D: the VS Code extension entry point.
//
// Registers the model viewer (a custom editor for .glb/.gltf), the workspace and
// gallery trees, the language features for <agent-3d> embeds, and the commands
// that generate, refine, animate, optimize, compare, rig, embed, and import
// models through the live three.ws studio. Every call hits the real public API;
// nothing here is stubbed.
import * as vscode from 'vscode';
import { GalleryProvider } from './gallery-tree.js';
import { ModelLinks } from './links.js';
import { ModelsProvider } from './models-tree.js';
import { ModelViewerProvider, VIEW_TYPE, openLocalModel, openRemoteModel, playClipIn, request } from './viewer.js';
import { TOOLS, callTool } from './studio.js';
import { downloadModel } from './download.js';
import { buildEmbedSnippet, resolveEmbedRelease, viewerUrl } from './embed.js';
import { slugFromUrl, uniqueName } from './naming.js';
import { activeViewer } from './active-panel.js';
import { clipSlug, fetchClip, generateMotion, listLibrary } from './animations.js';
import { refineModel } from './refine.js';
import { PRESETS, describeSavings, optimizeGlb } from './optimize.js';
import { committedBytes, compareModels } from './compare.js';
import { checkQuality, qualityMarkdown } from './quality.js';
import { createStatusBar } from './status-bar.js';
import { registerEmbedLanguage } from './embed-language-vscode.js';
let output;
let links;
let extensionContext;
export function activate(context) {
extensionContext = context;
output = vscode.window.createOutputChannel('three.ws 3D');
links = new ModelLinks(context.workspaceState);
const models = new ModelsProvider(links);
const gallery = new GalleryProvider();
const modelsView = vscode.window.createTreeView('threews3d.models', {
treeDataProvider: models,
});
const galleryView = vscode.window.createTreeView('threews3d.gallery', {
treeDataProvider: gallery,
});
context.subscriptions.push(
output,
models,
gallery,
modelsView,
galleryView,
ModelViewerProvider.register(context, links, output),
createStatusBar(),
registerEmbedLanguage(context, { origin, output }),
);
const reg = (id, fn) => context.subscriptions.push(vscode.commands.registerCommand(id, fn));
reg('threews3d.generateModel', () => generate('model'));
reg('threews3d.generateAvatar', () => generate('avatar'));
reg('threews3d.rigModel', (target) => rig(target));
reg('threews3d.refineModel', (target) => refine(target));
reg('threews3d.animate', (target) => animate(target));
reg('threews3d.animateFromText', (target) => animateFromText(target));
reg('threews3d.optimizeModel', (target) => optimize(target));
reg('threews3d.compareWithHead', (target) => compareWithHead(target));
reg('threews3d.checkQuality', (target) => quality(target));
reg('threews3d.insertEmbed', (target) => insertEmbed(target));
reg('threews3d.previewUrl', (url) => previewUrl(context, url));
reg('threews3d.previewCreation', (item) => {
if (item?.glbUrl) openRemoteModel(context, links, output, item.glbUrl, title(item));
});
reg('threews3d.importGalleryItem', (node) => importCreation(node?.creation || node));
reg('threews3d.openInBrowser', (target) => openInBrowser(target));
reg('threews3d.copyModelUrl', (target) => copyModelUrl(target));
reg('threews3d.saveSnapshot', () => withViewer((panel) => panel.threews.post({ type: 'snapshot' })));
reg('threews3d.exportTurntable', () => withViewer((panel) => panel.threews.post({ type: 'turntable' })));
reg('threews3d.toggleReport', () => withViewer((panel) => panel.threews.post({ type: 'toggle-report' })));
reg('threews3d.refreshModels', () => models.refresh());
reg('threews3d.refreshGallery', () => gallery.refresh());
models.refresh();
// The gallery view starts collapsed; load it the first time it is expanded so
// activation never blocks on the network.
const once = galleryView.onDidChangeVisibility((e) => {
if (e.visible) {
once.dispose();
gallery.refresh();
}
});
context.subscriptions.push(once);
}
export function deactivate() {}
function config() {
return vscode.workspace.getConfiguration('threews3d');
}
function origin() {
return config().get('origin', 'https://three.ws');
}
function title(creation) {
return creation.prompt ? creation.prompt.slice(0, 48) : `creation ${creation.id.slice(0, 8)}`;
}
function withViewer(fn) {
const panel = activeViewer();
if (!panel?.threews) {
vscode.window.showWarningMessage('three.ws 3D: open a model in the viewer first.');
return;
}
return fn(panel);
}
// ---------------------------------------------------------------- generation
async function generate(kind) {
const prompt = await vscode.window.showInputBox({
title: kind === 'avatar' ? 'Generate a 3D avatar' : 'Generate a 3D model',
prompt:
kind === 'avatar'
? 'Describe the character. Lead with the subject, then clothing and colours.'
: 'Describe one object. Lead with the subject, then its materials and colours.',
placeHolder:
kind === 'avatar'
? 'a cheerful astronaut in a white suit with an orange visor'
: 'a friendly round robot mascot, glossy white plastic, big blue eyes',
validateInput: validatePrompt,
});
if (!prompt) return;
const args =
kind === 'avatar'
? { prompt: prompt.trim() }
: { prompt: prompt.trim(), tier: config().get('tier', 'draft') };
const tool = kind === 'avatar' ? TOOLS.avatar : TOOLS.model;
await vscode.window.withProgress(
{
location: vscode.ProgressLocation.Notification,
title: kind === 'avatar' ? 'Generating your avatar' : 'Generating your 3D model',
cancellable: true,
},
async (progress, token) => {
const controller = new AbortController();
token.onCancellationRequested(() => controller.abort());
progress.report({ message: 'the free lane is working on it…' });
try {
const model = await callTool(origin(), tool, args, { signal: controller.signal });
output.appendLine(`${tool}: ${model.glbUrl}`);
progress.report({ message: 'saving into the workspace…' });
const saved = await downloadModel(model.glbUrl, {
prompt: prompt.trim(),
token,
progress,
});
await links.set(saved.uri, model.glbUrl, { prompt: prompt.trim() });
await openInViewer(saved.uri);
await offerFollowUp(saved.uri);
} catch (err) {
if (token.isCancellationRequested) return;
report(err, kind === 'avatar' ? 'avatar generation' : 'model generation');
}
},
);
}
function validatePrompt(v) {
const value = v.trim();
if (value.length < 3) return 'Describe the subject in at least 3 characters';
if (value.length > 1000) return 'Keep the description under 1000 characters';
return null;
}
async function offerFollowUp(uri) {
const choice = await vscode.window.showInformationMessage(
`Saved ${vscode.workspace.asRelativePath(uri, false)}`,
'Refine it',
'Rig for animation',
'Insert embed',
);
if (choice === 'Insert embed') await vscode.commands.executeCommand('threews3d.insertEmbed', uri);
if (choice === 'Rig for animation') await vscode.commands.executeCommand('threews3d.rigModel', uri);
if (choice === 'Refine it') await vscode.commands.executeCommand('threews3d.refineModel', uri);
}
async function openInViewer(uri) {
await vscode.commands.executeCommand('vscode.openWith', uri, VIEW_TYPE);
}
// --------------------------------------------------------------------- rigging
async function rig(target) {
const url = await resolveUrl(target, {
title: 'Rig a model for animation',
prompt: 'https URL of the static GLB to rig',
});
if (!url) return;
await vscode.window.withProgress(
{
location: vscode.ProgressLocation.Notification,
title: 'Rigging the model',
cancellable: true,
},
async (progress, token) => {
const controller = new AbortController();
token.onCancellationRequested(() => controller.abort());
progress.report({ message: 'fitting a humanoid skeleton…' });
try {
const rigged = await callTool(
origin(),
TOOLS.rig,
{ glb_url: url },
{ signal: controller.signal },
);
output.appendLine(`${TOOLS.rig}: ${rigged.glbUrl}`);
const saved = await downloadModel(rigged.glbUrl, {
prompt: `${slugFromUrl(url)}-rigged`,
token,
progress,
});
const meta = uriOf(target) ? links.meta(uriOf(target)) : null;
await links.set(saved.uri, rigged.glbUrl, { prompt: meta?.prompt || null });
await openInViewer(saved.uri);
const next = await vscode.window.showInformationMessage(
`Saved ${vscode.workspace.asRelativePath(saved.uri, false)}. It has a skeleton now.`,
'Try an animation',
);
if (next) await vscode.commands.executeCommand('threews3d.animate', saved.uri);
} catch (err) {
if (token.isCancellationRequested) return;
report(err, 'rigging');
}
},
);
}
// ------------------------------------------------------------------ refining
async function refine(target, presetInstruction = '') {
const uri = uriOf(target);
const url = await resolveUrl(target, {
title: 'Refine a model',
prompt: 'https URL of the model to refine',
});
if (!url) return;
const meta = uri ? links.meta(uri) : null;
const instruction = await vscode.window.showInputBox({
title: 'Refine this model',
prompt: meta?.prompt
? `Describe the change to "${meta.prompt.slice(0, 60)}". The new version keeps its form and materials.`
: 'Describe the change. The new version is generated anchored to this one.',
placeHolder: 'make it metallic · bigger helmet · add a cape · lower poly, chunkier shapes',
value: presetInstruction || undefined,
validateInput: (v) => {
const value = v.trim();
if (value.length < 1) return 'Describe the change';
if (value.length > 500) return 'Keep the change under 500 characters';
return null;
},
});
if (!instruction) return;
await vscode.window.withProgress(
{ location: vscode.ProgressLocation.Notification, title: `Refining: ${instruction.trim().slice(0, 40)}`, cancellable: true },
async (progress, token) => {
const controller = new AbortController();
token.onCancellationRequested(() => controller.abort());
progress.report({ message: 'generating a new version anchored to this one…' });
try {
const result = await refineModel(
origin(),
{ glbUrl: url, instruction: instruction.trim(), parentPrompt: meta?.prompt, lineage: meta?.lineage },
{ signal: controller.signal, onStatus: (message) => progress.report({ message }) },
);
output.appendLine(`${TOOLS.refine}: ${result.glbUrl} (version ${result.lineage.length} of the lineage)`);
progress.report({ message: 'saving into the workspace…' });
const stem = uri ? stemOf(uri) : slugFromUrl(url);
const saved = await downloadModel(result.glbUrl, {
prompt: `${stem}-v${result.lineage.length}`,
token,
progress,
});
await links.set(saved.uri, result.glbUrl, { prompt: result.prompt, lineage: result.lineage });
// The parent keeps the same lineage so a second refinement of it branches
// from the right version instead of forking a fresh history.
if (uri && meta) await links.set(uri, meta.url, { lineage: result.lineage });
await openInViewer(saved.uri);
const next = await vscode.window.showInformationMessage(
`Saved ${vscode.workspace.asRelativePath(saved.uri, false)} (version ${result.lineage.length}).`,
'Refine again',
'Compare with previous',
);
if (next === 'Refine again') await vscode.commands.executeCommand('threews3d.refineModel', saved.uri);
if (next === 'Compare with previous' && uri) await compareFiles(uri, saved.uri, 'previous version', `version ${result.lineage.length}`);
} catch (err) {
if (token.isCancellationRequested) return;
report(err, 'refining the model');
}
},
);
}
// ----------------------------------------------------------------- animating
/** The library is fetched once per session; 2,800 rows is under a megabyte. */
let libraryPromise = null;
function library() {
if (!libraryPromise) {
libraryPromise = listLibrary(origin()).catch((err) => {
libraryPromise = null;
throw err;
});
}
return libraryPromise;
}
async function animate(target) {
const panel = await viewerFor(target);
if (!panel) return;
if (panel.threews.stats && !panel.threews.stats.bones) {
const pick = await vscode.window.showWarningMessage(
'This model has no skeleton, so a library clip has nothing to drive. Rig it first.',
'Rig for animation',
);
if (pick) await vscode.commands.executeCommand('threews3d.rigModel', target);
return;
}
const quickPick = vscode.window.createQuickPick();
quickPick.title = 'Try a library animation';
quickPick.placeholder = 'Type to search 2,800 clips: idle, walk, wave, dance, sit, punch, or describe a new motion';
quickPick.matchOnDescription = true;
quickPick.busy = true;
const describe = { label: '$(sparkle) Describe a motion in words…', alwaysShow: true, kind: 'text' };
quickPick.items = [describe];
quickPick.show();
let clips;
try {
clips = await library();
} catch (err) {
quickPick.hide();
report(err, 'loading the animation library');
return;
}
quickPick.busy = false;
quickPick.items = [
describe,
{ label: '', kind: vscode.QuickPickItemKind.Separator },
...clips.map((clip) => ({
label: clip.label,
description: `${clip.duration.toFixed(1)}s${clip.loop ? ' · loops' : ''}`,
clip,
})),
];
const chosen = await new Promise((resolve) => {
quickPick.onDidAccept(() => resolve(quickPick.selectedItems[0]));
quickPick.onDidHide(() => resolve(undefined));
});
quickPick.dispose();
if (!chosen) return;
if (chosen.kind === 'text') return animateFromText(target);
await playOnViewer(panel, chosen.clip.url, { label: chosen.clip.label, loop: chosen.clip.loop });
}
async function animateFromText(target) {
const panel = await viewerFor(target);
if (!panel) return;
const prompt = await vscode.window.showInputBox({
title: 'Animate from a text prompt',
prompt: 'Describe the motion. A motion model samples it on the three.ws GPU fleet and the clip is retargeted onto this rig.',
placeHolder: 'waving confidently with the right hand · a slow tai-chi sweep · jumping for joy',
validateInput: validatePrompt,
});
if (!prompt) return;
await vscode.window.withProgress(
{ location: vscode.ProgressLocation.Notification, title: `Animating: ${prompt.trim().slice(0, 40)}`, cancellable: true },
async (progress, token) => {
const controller = new AbortController();
token.onCancellationRequested(() => controller.abort());
progress.report({ message: 'queued on the GPU fleet…' });
try {
const { clip } = await generateMotion(origin(), prompt.trim(), {
signal: controller.signal,
onStatus: (message) => progress.report({ message }),
});
await playClip(panel, clip, { label: prompt.trim().slice(0, 60), loop: false });
} catch (err) {
if (token.isCancellationRequested) return;
report(err, 'text to animation');
}
},
);
}
async function playOnViewer(panel, clipUrl, { label, loop }) {
await vscode.window.withProgress(
{ location: vscode.ProgressLocation.Window, title: `Retargeting "${label}"` },
async () => {
try {
const clip = await fetchClip(clipUrl);
await playClip(panel, clip, { label, loop });
} catch (err) {
report(err, 'loading the clip');
}
},
);
}
async function playClip(panel, clip, { label, loop }) {
const result = await playClipIn(panel, { clip, label, loop });
if (result.ok) {
const pct = Math.round(result.coverage * 100);
vscode.window.setStatusBarMessage(
`$(play) "${label}" is playing on ${result.matched} of ${result.total} bones (${pct}% coverage). Bake clip writes it into the file.`,
8000,
);
return;
}
const pick = await vscode.window.showWarningMessage(
result.message
? `three.ws 3D: ${result.message}`
: `This rig matched ${result.matched} of ${result.total} bones the clip drives (${Math.round(result.coverage * 100)}%), below the floor the retargeter accepts. Its bone names are not a humanoid convention the platform knows; rigging it through three.ws gives it one that is.`,
'Rig for animation',
);
if (pick) await vscode.commands.executeCommand('threews3d.rigModel', panel.threews.resource || panel.threews.remoteUrl);
}
/** The viewer showing `target`, opening it if needed; the active viewer when there is no target. */
async function viewerFor(target) {
const uri = uriOf(target);
const active = activeViewer();
if (!uri) {
if (active?.threews) return active;
vscode.window.showWarningMessage('three.ws 3D: open a model in the viewer first.');
return null;
}
if (active?.threews && sameTarget(active, uri)) return active;
if (uri.scheme === 'http' || uri.scheme === 'https') {
const panel = openRemoteModel(extensionContext, links, output, uri.toString(), slugFromUrl(uri.toString()));
await ready(panel);
return panel;
}
await openInViewer(uri);
const panel = activeViewer();
if (!panel?.threews) return null;
await ready(panel);
return panel;
}
function sameTarget(panel, uri) {
const t = panel.threews;
if (t.resource) return t.resource.toString() === uri.toString();
return t.remoteUrl === uri.toString();
}
/** Wait until the webview has loaded a model (its `loaded` message sets stats). */
function ready(panel, timeoutMs = 60_000) {
return new Promise((resolve) => {
const started = Date.now();
const tick = () => {
if (panel.threews?.stats || Date.now() - started > timeoutMs) return resolve();
setTimeout(tick, 150);
};
tick();
});
}
// ---------------------------------------------------------------- optimizing
async function optimize(target) {
const uri = await resolveLocal(target, 'optimize');
if (!uri) return;
const preset = await vscode.window.showQuickPick(
Object.entries(PRESETS).map(([id, p]) => ({ label: p.label, detail: p.detail, id })),
{ title: 'Optimize for the web', placeHolder: 'A copy is written next to the model; the original is untouched.' },
);
if (!preset) return;
await vscode.window.withProgress(
{ location: vscode.ProgressLocation.Notification, title: 'Optimizing the model' },
async (progress) => {
try {
progress.report({ message: 'dedup, prune, weld, resample, meshopt…' });
const bytes = await vscode.workspace.fs.readFile(uri);
const result = await optimizeGlb(bytes, { preset: preset.id });
const folder = vscode.Uri.joinPath(uri, '..');
const target = await freeName(folder, `${stemOf(uri)}.web`, '.glb');
await vscode.workspace.fs.writeFile(target, result.bytes);
const meta = links.meta(uri);
if (meta) await links.set(target, meta.url, { prompt: meta.prompt });
const savings = describeSavings(result.before, result.after);
output.appendLine(`optimized ${uri.fsPath} -> ${target.fsPath}: ${savings}`);
const pick = await vscode.window.showInformationMessage(
`Saved ${vscode.workspace.asRelativePath(target, false)}: ${savings}.`,
'Open',
'Compare',
);
if (pick === 'Open') await openInViewer(target);
if (pick === 'Compare') await compareFiles(uri, target, 'original', 'optimized');
} catch (err) {
report(err, 'optimizing the model');
}
},
);
}
// ------------------------------------------------------------------ comparing
async function compareWithHead(target) {
const uri = await resolveLocal(target, 'compare');
if (!uri) return;
await vscode.window.withProgress(
{ location: vscode.ProgressLocation.Notification, title: 'Comparing with the committed version' },
async () => {
try {
const [before, after] = await Promise.all([committedBytes(uri.fsPath), vscode.workspace.fs.readFile(uri)]);
if (sameBytes(before, after)) {
vscode.window.showInformationMessage(`${vscode.workspace.asRelativePath(uri, false)} is identical to the committed version.`);
return;
}
const { changeset, markdown } = await compareModels(before, after, { nameA: 'HEAD', nameB: 'working tree' });
const stash = vscode.Uri.joinPath(extensionContext.globalStorageUri, 'compare');
await vscode.workspace.fs.createDirectory(stash);
const headCopy = vscode.Uri.joinPath(stash, `${stemOf(uri)}@HEAD.glb`);
await vscode.workspace.fs.writeFile(headCopy, before);
await showMarkdown(markdown, `${stemOf(uri)}: HEAD vs working tree`);
openLocalModel(extensionContext, links, output, headCopy, `${path(uri)} @ HEAD`, vscode.ViewColumn.Beside);
const severity = changeset?.severity ? ` Severity: ${changeset.severity}.` : '';
vscode.window.setStatusBarMessage(`$(git-compare) ${path(uri)} compared with HEAD.${severity}`, 8000);
} catch (err) {
report(err, 'comparing with the committed version');
}
},
);
}
async function compareFiles(a, b, nameA, nameB) {
try {
const [before, after] = await Promise.all([vscode.workspace.fs.readFile(a), vscode.workspace.fs.readFile(b)]);
const { markdown } = await compareModels(before, after, { nameA, nameB });
await showMarkdown(markdown, `${path(a)} vs ${path(b)}`);
} catch (err) {
report(err, 'comparing the models');
}
}
function sameBytes(a, b) {
if (a.byteLength !== b.byteLength) return false;
for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
return true;
}
// -------------------------------------------------------------------- quality
async function quality(target) {
const panel = await viewerFor(target);
if (!panel) return;
const uri = panel.threews.resource;
const meta = uri ? links.meta(uri) : null;
await vscode.window.withProgress(
{ location: vscode.ProgressLocation.Notification, title: 'Checking quality', cancellable: true },
async (progress, token) => {
const controller = new AbortController();
token.onCancellationRequested(() => controller.abort());
try {
progress.report({ message: 'rendering the current view…' });
const render = await request(panel, { type: 'render' });
if (!render?.dataUrl) throw new Error(render?.message || 'the viewer produced no render');
progress.report({ message: 'a vision model is scoring it…' });
const { verdict } = await checkQuality(origin(), { image: render.dataUrl, prompt: meta?.prompt }, { signal: controller.signal });
const name = uri ? path(uri) : panel.title;
output.appendLine(`quality ${name}: ${verdict.qa_available ? `${verdict.pass ? 'pass' : 'fail'} ${verdict.score}` : 'unavailable'}`);
await showMarkdown(qualityMarkdown(verdict, { modelName: name, prompt: meta?.prompt }), `Quality: ${name}`);
if (verdict.qa_available && !verdict.pass && verdict.suggested_retry_hint && (uri || panel.threews.remoteUrl)) {
const pick = await vscode.window.showInformationMessage(
`Scored ${Math.round(verdict.score)}/100. ${verdict.suggested_retry_hint}`,
'Refine with this hint',
);
if (pick) await refine(uri || vscode.Uri.parse(panel.threews.remoteUrl), verdict.suggested_retry_hint);
}
} catch (err) {
if (token.isCancellationRequested) return;
report(err, 'the quality check');
}
},
);
}
// ---------------------------------------------------------------------- embed
async function insertEmbed(target) {
const src = await resolveUrl(target, {
title: 'Insert an <agent-3d> embed',
prompt: 'https URL of the hosted model the embed should show',
});
if (!src) return;
let snippet;
try {
const release = await resolveEmbedRelease(origin(), config().get('embedChannel', 'pinned'));
snippet = buildEmbedSnippet({ src, origin: origin(), ...release });
} catch (err) {
report(err, 'building the embed snippet');
return;
}
const editor = vscode.window.activeTextEditor;
if (editor) {
await editor.edit((edit) => {
for (const selection of editor.selections) edit.replace(selection, snippet);
});
return;
}
await vscode.env.clipboard.writeText(snippet);
vscode.window.showInformationMessage(
'three.ws 3D: no editor was open, so the embed snippet was copied to the clipboard.',
);
}
// -------------------------------------------------------------------- viewing
async function previewUrl(context, given) {
const url =
typeof given === 'string' && isHttpUrl(given)
? given
: await vscode.window.showInputBox({
title: 'Preview a model URL',
prompt: 'https URL of a .glb or .gltf file',
placeHolder: 'https://three.ws/avatars/default.glb',
validateInput: (v) => (isHttpUrl(v) ? null : 'Enter a valid http(s) URL'),
});
if (!url) return;
openRemoteModel(context, links, output, url.trim(), slugFromUrl(url));
}
async function importCreation(creation) {
if (!creation?.glbUrl) return;
await vscode.window.withProgress(
{ location: vscode.ProgressLocation.Notification, title: 'Importing the model', cancellable: true },
async (progress, token) => {
try {
const saved = await downloadModel(creation.glbUrl, {
prompt: creation.prompt || slugFromUrl(creation.glbUrl),
token,
progress,
});
await links.set(saved.uri, creation.glbUrl, { prompt: creation.prompt || null });
await openInViewer(saved.uri);
} catch (err) {
if (token.isCancellationRequested) return;
report(err, 'importing the model');
}
},
);
}
async function openInBrowser(target) {
const url = await resolveUrl(target, {
title: 'Open in the three.ws viewer',
prompt: 'https URL of the hosted model',
});
if (!url) return;
await vscode.env.openExternal(vscode.Uri.parse(viewerUrl(origin(), url)));
}
async function copyModelUrl(target) {
const url = await resolveUrl(target, {
title: 'Copy the model URL',
prompt: 'https URL of the hosted model',
});
if (!url) return;
await vscode.env.clipboard.writeText(url);
vscode.window.showInformationMessage('three.ws 3D: model URL copied.');
}
// -------------------------------------------------------------------- helpers
/** Show a Markdown document in the preview, beside the current editor. */
async function showMarkdown(markdown, name) {
const doc = await vscode.workspace.openTextDocument({ language: 'markdown', content: `<!-- ${name} -->\n\n${markdown}` });
await vscode.commands.executeCommand('markdown.showPreviewToSide', doc.uri);
}
function uriOf(target) {
const uri = target?.resourceUri || target;
if (uri instanceof vscode.Uri) return uri;
if (typeof uri === 'string' && isHttpUrl(uri)) return vscode.Uri.parse(uri);
return null;
}
/** A model on disk for commands that rewrite bytes; falls back to the active viewer's file. */
async function resolveLocal(target, verb) {
const uri = uriOf(target) || activeViewer()?.threews?.resource || null;
if (uri && uri.scheme !== 'http' && uri.scheme !== 'https') return uri;
vscode.window.showWarningMessage(`three.ws 3D: open a model file from the workspace to ${verb} it.`);
return null;
}
/**
* Work out which hosted model a command should act on.
*
* Tree items and explorer entries arrive as a Uri; models this extension
* generated or imported carry their CDN URL in the link store. A local file with
* no recorded URL cannot be embedded or rigged (the studio and the browser both
* need to fetch it), so the user is asked for one rather than being handed a
* broken snippet.
*/
async function resolveUrl(target, { title: boxTitle, prompt }) {
const uri = target?.resourceUri || target;
if (typeof uri === 'string' && isHttpUrl(uri)) return uri;
if (uri instanceof vscode.Uri) {
if (uri.scheme === 'http' || uri.scheme === 'https') return uri.toString();
const known = links.get(uri);
if (known) return known;
}
const name = uri instanceof vscode.Uri ? vscode.workspace.asRelativePath(uri, false) : '';
const entered = await vscode.window.showInputBox({
title: boxTitle,
prompt: name
? `${name} has no public URL yet. Paste the https URL where the model is hosted.`
: prompt,
placeHolder: 'https://…/model.glb',
validateInput: (v) => (isHttpUrl(v) ? null : 'Enter a valid http(s) URL'),
});
return entered?.trim() || null;
}
async function freeName(folder, stem, ext) {
const taken = await vscode.workspace.fs.readDirectory(folder).then(
(entries) => new Set(entries.map(([name]) => name.toLowerCase())),
() => new Set(),
);
return vscode.Uri.joinPath(folder, uniqueName(stem, ext, (name) => taken.has(name.toLowerCase())));
}
function path(uri) {
return uri.path.split('/').pop() || '';
}
function stemOf(uri) {
return path(uri).replace(/\.(glb|gltf)$/i, '');
}
function isHttpUrl(value) {
try {
const url = new URL(String(value).trim());
return url.protocol === 'http:' || url.protocol === 'https:';
} catch {
return false;
}
}
function report(err, what) {
const message = err?.message || String(err);
if (message === 'cancelled') return;
output.appendLine(`${what} failed: ${message}`);
vscode.window.showErrorMessage(`three.ws 3D: ${what} failed. ${message}`, 'Show log').then((pick) => {
if (pick === 'Show log') output.show(true);
});
}