Skip to content

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.

feat(forge): add an opt-in "Use your GPU" lane that generates through a local Modly app

nirholas5175ddc41210
diff --git a/pages/forge.html b/pages/forge.html
index 943e62b61..44cceacee 100644
--- a/pages/forge.html
+++ b/pages/forge.html
@@ -3423,6 +3423,326 @@
padding-right: max(var(--space-md), env(safe-area-inset-right, 0px));
}
+ /* ── Your GPU (Modly) ───────────────────────────────────────────────
+ Opt-in local lane. An inset panel in the photos tab, styled like the
+ BYOK row so "runs somewhere other than our cloud" reads consistently.
+ data-state drives the status dot: idle, probing, connected,
+ not-running, blocked. */
+ .modly-panel {
+ position: relative;
+ margin-top: var(--space-sm);
+ padding: 0.75rem 0.85rem 0.75rem 1rem;
+ background: var(--surface-2);
+ border: 1px solid var(--stroke);
+ border-radius: var(--radius-md);
+ transition: border-color var(--duration-fast);
+ }
+ .modly-panel::before {
+ content: '';
+ position: absolute;
+ left: 0;
+ top: 0.6rem;
+ bottom: 0.6rem;
+ width: 2px;
+ border-radius: 0 2px 2px 0;
+ background: var(--stroke-strong);
+ transition: background var(--duration-fast);
+ }
+ .modly-panel[data-state='connected']::before {
+ background: var(--success);
+ }
+ .modly-panel[data-state='not-running']::before,
+ .modly-panel[data-state='blocked']::before {
+ background: var(--warning, #e0a93e);
+ }
+ .modly-panel[data-state='connected'] {
+ border-color: color-mix(in srgb, var(--success) 35%, var(--stroke));
+ }
+ .modly-head {
+ display: flex;
+ align-items: center;
+ gap: var(--space-sm);
+ flex-wrap: wrap;
+ }
+ .modly-ico {
+ flex: none;
+ display: inline-grid;
+ place-items: center;
+ width: 32px;
+ height: 32px;
+ border-radius: var(--radius-sm);
+ background: var(--surface-3);
+ color: var(--ink);
+ }
+ .modly-ico svg {
+ width: 18px;
+ height: 18px;
+ }
+ .modly-copy {
+ flex: 1 1 10rem;
+ min-width: 0;
+ }
+ .modly-title {
+ margin: 0;
+ font-size: var(--text-sm);
+ font-weight: 650;
+ color: var(--ink);
+ display: flex;
+ align-items: center;
+ gap: 0.4em;
+ }
+ .modly-pill {
+ display: inline-block;
+ padding: 0.05em 0.45em;
+ border-radius: 999px;
+ font-size: 0.72em;
+ font-weight: 700;
+ letter-spacing: 0.03em;
+ line-height: 1.5;
+ white-space: nowrap;
+ color: var(--success);
+ background: rgba(34, 197, 94, 0.14);
+ border: 1px solid rgba(74, 222, 128, 0.38);
+ }
+ html[data-theme='light'] .modly-pill {
+ color: #0a7d33;
+ background: rgba(34, 197, 94, 0.16);
+ border-color: rgba(34, 197, 94, 0.32);
+ }
+ .modly-sub {
+ margin: 0.1rem 0 0;
+ font-size: var(--text-xs);
+ color: var(--ink-dim);
+ }
+ .modly-sub a,
+ .modly-status a {
+ color: var(--ink);
+ text-decoration: underline;
+ text-underline-offset: 2px;
+ }
+ .modly-sub a:hover,
+ .modly-status a:hover {
+ color: var(--accent);
+ }
+ .modly-actions {
+ display: flex;
+ gap: var(--space-xs);
+ margin-left: auto;
+ }
+ .modly-btn {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.4rem;
+ font: inherit;
+ font-size: var(--text-xs);
+ font-weight: 600;
+ color: var(--ink);
+ background: var(--surface-1);
+ border: 1px solid var(--stroke-strong);
+ border-radius: var(--radius-pill);
+ padding: 5px 12px;
+ cursor: pointer;
+ transition: border-color var(--duration-fast), transform var(--duration-fast), background var(--duration-fast);
+ }
+ .modly-btn:hover:not(:disabled) {
+ border-color: var(--accent);
+ transform: translateY(-1px);
+ }
+ .modly-btn:active:not(:disabled) {
+ transform: translateY(0);
+ background: var(--surface-3);
+ }
+ .modly-btn:focus-visible {
+ outline: 2px solid var(--accent);
+ outline-offset: 2px;
+ }
+ .modly-btn:disabled {
+ cursor: progress;
+ opacity: 0.7;
+ }
+ .modly-btn-quiet {
+ background: transparent;
+ border-color: var(--stroke);
+ color: var(--ink-dim);
+ }
+ .modly-dot {
+ width: 7px;
+ height: 7px;
+ border-radius: 50%;
+ background: var(--ink-dim);
+ opacity: 0.6;
+ }
+ .modly-panel[data-state='connected'] .modly-dot {
+ background: var(--success);
+ opacity: 1;
+ box-shadow: 0 0 6px var(--success);
+ }
+ .modly-panel[data-state='not-running'] .modly-dot,
+ .modly-panel[data-state='blocked'] .modly-dot {
+ background: var(--warning, #e0a93e);
+ opacity: 1;
+ }
+ .modly-panel[data-state='probing'] .modly-dot {
+ background: var(--accent);
+ opacity: 1;
+ animation: modly-pulse 1s ease-in-out infinite;
+ }
+ @keyframes modly-pulse {
+ 50% {
+ opacity: 0.25;
+ }
+ }
+ .modly-status {
+ margin: 0.55rem 0 0;
+ font-size: var(--text-xs);
+ line-height: 1.5;
+ color: var(--ink-dim);
+ }
+ .modly-status:empty {
+ display: none;
+ }
+ .modly-status strong {
+ color: var(--ink);
+ }
+ .modly-status code,
+ .modly-origin-msg code {
+ font-family: var(--font-mono);
+ font-size: 0.95em;
+ overflow-wrap: anywhere;
+ }
+ .modly-status:not(:empty) {
+ animation: byok-reveal 0.22s ease both;
+ }
+ .modly-spinner {
+ display: inline-block;
+ width: 0.85em;
+ height: 0.85em;
+ margin-right: 0.45em;
+ vertical-align: -0.1em;
+ border: 2px solid var(--stroke-strong);
+ border-top-color: var(--accent);
+ border-radius: 50%;
+ animation: modly-spin 0.8s linear infinite;
+ }
+ @keyframes modly-spin {
+ to {
+ transform: rotate(360deg);
+ }
+ }
+ .modly-advanced {
+ margin-top: 0.5rem;
+ font-size: var(--text-xs);
+ }
+ .modly-advanced summary {
+ cursor: pointer;
+ color: var(--ink-dim);
+ width: fit-content;
+ border-radius: var(--radius-sm);
+ }
+ .modly-advanced summary:hover {
+ color: var(--ink);
+ }
+ .modly-advanced summary:focus-visible {
+ outline: 2px solid var(--accent);
+ outline-offset: 2px;
+ }
+ .modly-origin-row {
+ display: flex;
+ align-items: center;
+ gap: var(--space-xs);
+ flex-wrap: wrap;
+ margin-top: 0.45rem;
+ }
+ .modly-origin-label {
+ color: var(--ink-dim);
+ }
+ .modly-origin-input {
+ flex: 1 1 12rem;
+ min-width: 0;
+ font-family: var(--font-mono);
+ font-size: var(--text-xs);
+ color: var(--ink);
+ background: var(--surface-1);
+ border: 1px solid var(--stroke-strong);
+ border-radius: var(--radius-sm);
+ padding: 5px 8px;
+ transition: border-color var(--duration-fast);
+ }
+ .modly-origin-input:hover {
+ border-color: var(--ink-dim);
+ }
+ .modly-origin-input:focus-visible {
+ outline: 2px solid var(--accent);
+ outline-offset: 1px;
+ }
+ .modly-origin-input[aria-invalid='true'] {
+ border-color: var(--danger);
+ }
+ .modly-origin-msg {
+ margin: 0.35rem 0 0;
+ color: var(--ink-dim);
+ }
+ .modly-origin-msg[data-tone='error'] {
+ color: var(--danger);
+ }
+ .modly-origin-msg[data-tone='ok'] {
+ color: var(--success);
+ }
+ /* Modly engines in the picker carry the same mint pill, worded for the lane. */
+ .aspect button .eng-local {
+ white-space: nowrap;
+ }
+ /* Save row under the result bar, for a model made on the user's GPU. */
+ .modly-save {
+ display: flex;
+ align-items: center;
+ gap: var(--space-sm);
+ flex-wrap: wrap;
+ margin-top: var(--space-sm);
+ padding: 0.6rem 0.8rem;
+ background: var(--surface-2);
+ border: 1px solid var(--stroke);
+ border-radius: var(--radius-md);
+ }
+ .modly-save[hidden] {
+ display: none;
+ }
+ .modly-save-text {
+ flex: 1 1 14rem;
+ margin: 0;
+ font-size: var(--text-xs);
+ line-height: 1.5;
+ color: var(--ink-dim);
+ }
+ .modly-save-text a {
+ color: var(--ink);
+ text-decoration: underline;
+ text-underline-offset: 2px;
+ }
+ .modly-save-text a:hover {
+ color: var(--accent);
+ }
+ .modly-save-text[data-tone='ok'] strong {
+ color: var(--success);
+ }
+ .modly-save-text[data-tone='error'] strong {
+ color: var(--danger);
+ }
+ @media (prefers-reduced-motion: reduce) {
+ .modly-btn,
+ .modly-panel,
+ .modly-panel::before,
+ .modly-origin-input {
+ transition: none;
+ }
+ .modly-status:not(:empty) {
+ animation: none;
+ }
+ .modly-panel[data-state='probing'] .modly-dot,
+ .modly-spinner {
+ animation: none;
+ }
+ }
</style>
<link rel="canonical" href="https://three.ws/forge">
@@ -3546,6 +3866,46 @@
(<kbd class="gen-kbd">⌘V</kbd> / <kbd class="gen-kbd">Ctrl+V</kbd>), drag a thumbnail to reorder.
PNG/JPG/WebP, up to 8&nbsp;MB each.
</p>
+ <!-- Your GPU: opt-in local generation through Modly (src/forge-modly.js).
+ Nothing contacts localhost until Connect is pressed. -->
+ <section class="modly-panel" id="modly-panel" data-state="idle" aria-labelledby="modly-title">
+ <div class="modly-head">
+ <span class="modly-ico" aria-hidden="true">
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">
+ <rect x="4" y="4" width="16" height="16" rx="2" />
+ <rect x="9" y="9" width="6" height="6" rx="1" />
+ <path d="M9 1v3M15 1v3M9 20v3M15 20v3M20 9h3M20 14h3M1 9h3M1 14h3" />
+ </svg>
+ </span>
+ <div class="modly-copy">
+ <h3 class="modly-title" id="modly-title">Use your GPU <span class="modly-pill">Free</span></h3>
+ <p class="modly-sub">Generate on this computer with <a href="https://modly3d.app/" target="_blank" rel="noopener">Modly</a>.</p>
+ </div>
+ <div class="modly-actions">
+ <button type="button" class="modly-btn" id="modly-connect" aria-describedby="modly-status"><span class="modly-dot" aria-hidden="true"></span><span id="modly-connect-label">Connect</span></button>
+ <button type="button" class="modly-btn modly-btn-quiet" id="modly-disconnect" hidden>Disconnect</button>
+ </div>
+ </div>
+ <p class="modly-status" id="modly-status" role="status" aria-live="polite"></p>
+ <details class="modly-advanced">
+ <summary>Custom address</summary>
+ <div class="modly-origin-row">
+ <label class="modly-origin-label" for="modly-origin">Modly address</label>
+ <input
+ class="modly-origin-input"
+ id="modly-origin"
+ type="text"
+ inputmode="url"
+ spellcheck="false"
+ autocomplete="off"
+ placeholder="http://localhost:8765"
+ aria-describedby="modly-origin-msg"
+ />
+ <button type="button" class="modly-btn" id="modly-origin-save">Save</button>
+ </div>
+ <p class="modly-origin-msg" id="modly-origin-msg" aria-live="polite">Only needed if you changed Modly's port. Leave empty for the default.</p>
+ </details>
+ </section>
</div>
<!-- Sketch → 3D (TripoSG-scribble) -->
@@ -4072,6 +4432,12 @@
<button class="btn" type="button" id="again" data-i18n="forge.make_another">Make another</button>
</div>
</div>
+ <!-- Shown only for a result generated on the user's GPU (Modly): it is
+ not a server-side creation, so saving it is an explicit step. -->
+ <div class="modly-save" id="modly-save" hidden>
+ <p class="modly-save-text" id="modly-save-text" role="status" aria-live="polite"></p>
+ <button type="button" class="modly-btn" id="modly-save-btn">Save to my avatars</button>
+ </div>
<!-- What the model was actually asked for: the art-directed rewrite
that painted the reference view, straight from the API's
diff --git a/src/forge-modly.js b/src/forge-modly.js
new file mode 100644
index 000000000..fad18f344
--- /dev/null
+++ b/src/forge-modly.js
@@ -0,0 +1,270 @@
+// /forge "Your GPU" lane: the opt-in Modly connect panel, plus the two
+// persistence steps a model generated on the user's own machine needs before
+// the rest of Forge (rig, optimize, AR, embed, the avatar library) can use it.
+//
+// Modly (https://modly3d.app/) is a free desktop app that runs open image-to-3D
+// models on the user's graphics card and serves an HTTP API on localhost. The
+// transport lives in src/modly-local.js; this module owns the panel's states.
+//
+// Nothing here touches localhost until the person presses Connect. Probing a
+// loopback address raises Chrome's Local Network Access prompt, and a prompt
+// nobody asked for on page load is exactly what a visitor should never see.
+
+import {
+ MODLY_INSTALL_URL,
+ MODLY_ORIGINS,
+ probeModly,
+ getModlyOriginOverride,
+ setModlyOriginOverride,
+} from './modly-local.js';
+
+const PROBE_TIMEOUT_MS = 2500;
+
+function esc(value) {
+ return String(value ?? '').replace(
+ /[&<>"']/g,
+ (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c],
+ );
+}
+
+function plural(n, one, many) {
+ return n === 1 ? one : many;
+}
+
+/** Models that can serve an image-to-3D run right now. */
+export function readyModlyModels(models) {
+ return (Array.isArray(models) ? models : []).filter(
+ (m) => m && m.downloaded && m.input === 'image' && m.output === 'mesh',
+ );
+}
+
+/**
+ * Wire the connect panel. `root` is #modly-panel; `onChange(state)` fires after
+ * every state transition so the engine picker can add or drop Modly engines.
+ *
+ * state: { status: 'idle'|'probing'|'connected'|'not-running'|'blocked',
+ * origin, models, reason, error }
+ */
+export function createModlyPanel({ root, onChange = () => {} }) {
+ if (!root) return null;
+ const $ = (id) => root.querySelector(`#${id}`);
+ const connectBtn = $('modly-connect');
+ const connectLabel = $('modly-connect-label');
+ const disconnectBtn = $('modly-disconnect');
+ const statusEl = $('modly-status');
+ const originInput = $('modly-origin');
+ const originSave = $('modly-origin-save');
+ const originMsg = $('modly-origin-msg');
+
+ let state = { status: 'idle', origin: null, models: [], reason: '', error: null };
+ // One-off outcome line ("Cancelled…") shown above the status until the
+ // next connect or disconnect.
+ let note = '';
+ let probe = null;
+
+ if (originInput) originInput.value = getModlyOriginOverride();
+
+ function setState(next) {
+ state = { ...state, ...next };
+ render();
+ onChange(state);
+ }
+
+ function render() {
+ root.dataset.state = state.status;
+ const probing = state.status === 'probing';
+ connectBtn.disabled = probing;
+ connectBtn.setAttribute('aria-busy', String(probing));
+ connectLabel.textContent = probing
+ ? 'Connecting…'
+ : state.status === 'connected'
+ ? 'Refresh'
+ : state.status === 'idle'
+ ? 'Connect'
+ : 'Retry';
+ disconnectBtn.hidden = state.status !== 'connected';
+ const lead = note ? `<strong class="modly-note">${esc(note)}</strong> ` : '';
+ statusEl.innerHTML = lead + statusHTML();
+ }
+
+ function statusHTML() {
+ const install = `<a href="${MODLY_INSTALL_URL}" target="_blank" rel="noopener">modly3d.app</a>`;
+ switch (state.status) {
+ case 'idle':
+ return 'Run open image-to-3D models on your own graphics card with Modly, a free desktop app. Nothing on this computer is contacted until you press Connect.';
+ case 'probing':
+ return '<span class="modly-spinner" aria-hidden="true"></span>Looking for Modly on this computer…';
+ case 'not-running': {
+ const tried = MODLY_ORIGINS.map((o) => `<code>${esc(o)}</code>`).join(', ');
+ return `<strong>Modly isn't running.</strong> Install it from ${install}, start it, then press Retry. Checked ${tried}.`;
+ }
+ case 'blocked':
+ if (state.reason === 'mixed-content') {
+ return '<strong>Safari blocks this.</strong> A secure page cannot reach an app on <code>http://localhost</code> in Safari. Open three.ws/forge in Chrome, Edge or Firefox to use Modly.';
+ }
+ return '<strong>Your browser blocked the connection.</strong> Open site settings (the icon left of the address bar), set <em>Local network access</em> to Allow, then press Retry.';
+ case 'connected':
+ return connectedHTML();
+ default:
+ return '';
+ }
+ }
+
+ function connectedHTML() {
+ const where = `Connected to Modly at <code>${esc(state.origin)}</code>.`;
+ if (state.error) {
+ return `${where} It could not list its models: ${esc(state.error.message)}. Press Refresh to try again.`;
+ }
+ const ready = readyModlyModels(state.models);
+ if (ready.length) {
+ return `${where} <strong>${ready.length} ${plural(ready.length, 'model', 'models')} ready.</strong> Pick one under Engine, marked <span class="modly-pill">Your GPU, free</span>.`;
+ }
+ const pending = state.models.filter((m) => !m.downloaded).map((m) => esc(m.name));
+ const pendingNote = pending.length ? ` Installed but not downloaded yet: ${pending.join(', ')}.` : '';
+ return `${where} <strong>No models downloaded yet.</strong> Open Modly, go to its Models page, download a model, then press Refresh.${pendingNote}`;
+ }
+
+ async function connect() {
+ probe?.abort();
+ const controller = new AbortController();
+ probe = controller;
+ note = '';
+ setState({ status: 'probing', error: null });
+ const result = await probeModly({ signal: controller.signal, timeoutMs: PROBE_TIMEOUT_MS });
+ if (probe !== controller) return state;
+ probe = null;
+ setState({
+ status: result.status,
+ origin: result.origin,
+ models: result.models || [],
+ reason: result.reason || '',
+ error: result.status === 'connected' ? result.error || null : null,
+ });
+ return state;
+ }
+
+ function disconnect() {
+ probe?.abort();
+ probe = null;
+ note = '';
+ setState({ status: 'idle', origin: null, models: [], reason: '', error: null });
+ connectBtn.focus();
+ }
+
+ function saveOrigin() {
+ originInput.removeAttribute('aria-invalid');
+ let saved;
+ try {
+ saved = setModlyOriginOverride(originInput.value.trim());
+ } catch (err) {
+ originInput.setAttribute('aria-invalid', 'true');
+ originMsg.textContent = err.message;
+ originMsg.dataset.tone = 'error';
+ originInput.focus();
+ return;
+ }
+ originInput.value = saved;
+ originMsg.textContent = saved
+ ? `Saved. Forge tries ${saved} first, then the default port.`
+ : 'Cleared. Forge uses the default port 8765.';
+ originMsg.dataset.tone = 'ok';
+ connect();
+ }
+
+ connectBtn.addEventListener('click', () => connect());
+ disconnectBtn.addEventListener('click', disconnect);
+ originSave?.addEventListener('click', saveOrigin);
+ // The panel sits inside the composer <form>: Enter here saves the address
+ // instead of submitting a generation.
+ originInput?.addEventListener('keydown', (e) => {
+ if (e.key !== 'Enter') return;
+ e.preventDefault();
+ saveOrigin();
+ });
+ originInput?.addEventListener('input', () => {
+ originInput.removeAttribute('aria-invalid');
+ originMsg.textContent = '';
+ });
+
+ render();
+ return {
+ connect,
+ disconnect,
+ get state() {
+ return state;
+ },
+ /** Show a one-off outcome line in the panel's live region. */
+ notify(text) {
+ note = String(text || '');
+ render();
+ },
+ readyModels: () => (state.status === 'connected' ? readyModlyModels(state.models) : []),
+ modelById: (id) => state.models.find((m) => m.id === id) || null,
+ };
+}
+
+async function readError(res, fallback) {
+ const body = await res.json().catch(() => null);
+ return body?.message || body?.error_description || fallback;
+}
+
+/**
+ * Copy a locally generated GLB into three.ws object storage and return its
+ * public https URL. Rig, optimize, game-ready, AR and the avatar library all
+ * take a public URL, so this is what lets a local result use the same tools
+ * as a cloud one. Uses the presigned GLB upload route (/api/scene-glb-upload)
+ * and PUTs the bytes straight to storage.
+ */
+export async function promoteModlyGlb(blob, { signal } = {}) {
+ const presign = await fetch('/api/scene-glb-upload', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ content_type: 'model/gltf-binary', size_bytes: blob.size }),
+ signal,
+ });
+ if (!presign.ok) {
+ throw new Error(await readError(presign, `Storage refused the upload (HTTP ${presign.status}).`));
+ }
+ const slot = await presign.json();
+ if (!slot?.upload_url || !slot?.public_url) throw new Error('Storage did not return an upload address.');
+ const put = await fetch(slot.upload_url, {
+ method: slot.method || 'PUT',
+ headers: slot.headers || { 'content-type': 'model/gltf-binary' },
+ body: blob,
+ signal,
+ });
+ if (!put.ok) throw new Error(`Storage rejected the file (HTTP ${put.status}).`);
+ return slot.public_url;
+}
+
+/**
+ * Save a promoted GLB into the signed-in user's avatar library through
+ * /api/avatars/from-forge. Resolves { ok, status, viewUrl, message }.
+ */
+export async function saveModlyResultToLibrary({ glbUrl, name, sourcePrompt, modelName }) {
+ const tags = ['forge', 'modly'];
+ let res;
+ try {
+ res = await fetch('/api/avatars/from-forge', {
+ method: 'POST',
+ credentials: 'include',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ glb_url: glbUrl,
+ name: String(name || 'Modly model').slice(0, 80),
+ source_prompt: [sourcePrompt, modelName ? `Generated locally with ${modelName} in Modly` : '']
+ .filter(Boolean)
+ .join(' · ')
+ .slice(0, 1000),
+ tags,
+ }),
+ });
+ } catch {
+ return { ok: false, status: 0, message: 'Could not reach three.ws. Check your connection and try again.' };
+ }
+ if (res.status === 201) {
+ const body = await res.json().catch(() => ({}));
+ return { ok: true, status: 201, viewUrl: body?.view_url || '', avatar: body?.avatar || null };
+ }
+ return { ok: false, status: res.status, message: await readError(res, `Save failed (HTTP ${res.status}).`) };
+}
diff --git a/src/forge-timeline.js b/src/forge-timeline.js
index 1659d79ff..f71a20e42 100644
--- a/src/forge-timeline.js
+++ b/src/forge-timeline.js
@@ -89,6 +89,10 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)
queuedSeconds: 0,
failoverFrom: null,
elapsedS: 0,
+ // A lane running on the user's own machine (Modly). It reports its own
+ // step text, and its result is not one of the server's saved creations.
+ local: false,
+ stepText: '',
};
}
@@ -160,8 +164,13 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)
out.push({
id: 'finish',
label: f.status === 'done' ? 'Model ready' : 'Finalizing the GLB',
- detail:
- f.status === 'done'
+ detail: f.local
+ ? f.status === 'done'
+ ? 'Loaded in the viewer'
+ : f.status === 'finalizing'
+ ? 'Fetching the GLB from your computer and loading it into the viewer'
+ : 'Fetched from your computer, then straight into the viewer'
+ : f.status === 'done'
? 'Saved to your creations and loaded in the viewer'
: f.status === 'finalizing'
? 'Compressing, scoring quality and loading it into the viewer'
@@ -191,6 +200,7 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)
function meshLabel() {
const engine = engineLabel(f.backend || f.plannedBackend);
if (f.mode === 'sketch') return `Sculpting geometry from your drawing on ${engine}`;
+ if (f.local) return `Building the mesh on ${engine}`;
return `Sculpting the textured mesh on ${engine}`;
}
@@ -204,6 +214,8 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)
if (f.failoverFrom) {
return `${engineLabel(f.failoverFrom)} hit a snag, so ${engineLabel(f.backend)} picked the job up`;
}
+ // A local engine names the step it is on; that beats any generic copy.
+ if (f.stepText && (f.status === 'queued' || f.status === 'running')) return f.stepText;
if (f.status === 'queued') {
if (f.coldStart) return 'Waiting on a GPU worker that is still booting';
return f.queuedSeconds >= 8
@@ -370,9 +382,10 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)
* Start a fresh timeline for a submission. Everything passed here is known
* client-side before the request goes out; the server's answer refines it.
*/
- begin({ mode, backend, viewCount = 0, localPreviewUrl = null, usesReference = true }) {
+ begin({ mode, backend, viewCount = 0, localPreviewUrl = null, usesReference = true, local = false }) {
f = blankFacts();
f.mode = mode;
+ f.local = Boolean(local);
f.plannedBackend = backend;
f.backend = backend;
f.viewCount = viewCount;
@@ -543,6 +556,17 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)
paint();
},
+ /**
+ * The step a local engine says it is on (Modly's own `step` text). Empty
+ * text falls back to the generic stage copy. No state changes.
+ */
+ setStepText(text) {
+ const next = String(text || '').trim().slice(0, 140);
+ if (next === f.stepText) return;
+ f.stepText = next;
+ paint();
+ },
+
/** The GLB landed; the client is loading it into the viewer. */
finalizing() {
f.status = 'finalizing';
diff --git a/src/forge.js b/src/forge.js
index f0af6741e..6b35612e6 100644
--- a/src/forge.js
+++ b/src/forge.js
@@ -26,6 +26,8 @@ import { generateForgePrompt } from './forge-prompt-gen.js';
import { createForgeTimeline } from './forge-timeline.js';
import { createCompare } from './forge-compare.js';
import { initForgeDestinationPicker, storedForgeDestination } from './shared/forge-destination-picker.js';
+import { generateWithModly, defaultModlyParams } from './modly-local.js';
+import { createModlyPanel, promoteModlyGlb, saveModlyResultToLibrary } from './forge-modly.js';
ensureStateKitStyles();
//
// Drives /api/forge. Three paths share one polling loop:
@@ -76,6 +78,14 @@ const els = {
modeSwitch: document.getElementById('mode-switch'),
textPane: document.getElementById('text-pane'),
imagePane: document.getElementById('image-pane'),
+ // Your GPU (Modly) lane: the connect panel in the photos tab, the
+ // "Feel free to leave" line it must hide (a local run stops with the tab),
+ // and the explicit save row under a local result.
+ modlyPanel: document.getElementById('modly-panel'),
+ genLeaveHint: document.querySelector('#state-generating .gen-leave-hint'),
+ modlySave: document.getElementById('modly-save'),
+ modlySaveText: document.getElementById('modly-save-text'),
+ modlySaveBtn: document.getElementById('modly-save-btn'),
viewsGrid: document.getElementById('views-grid'),
fileInput: document.getElementById('view-file-input'),
imagePrompt: document.getElementById('image-prompt'),
@@ -199,6 +209,12 @@ let currentResultTier = null;
// The GLB currently shown in the viewer (set on every result). Lets the
// rate-limit state know a model exists to refine locally as a fallback.
let lastShownGlb = '';
+// Your GPU lane. `modly` is the connect panel (src/forge-modly.js); `modlyRun`
+// is the generation in flight on the user's machine, whose real percent and
+// step text drive the meter; `modlyResult` is the local model on screen.
+let modly = null;
+let modlyRun = null;
+let modlyResult = null;
// Quality tiers, lowest → highest. Refine walks one step up this ladder.
const TIER_ORDER = ['draft', 'standard', 'high'];
@@ -217,13 +233,17 @@ let catalog = null;
// optimistically from the catalog and tighten when health lands.
let health = null;
let selectedTier = 'standard';
-let selectedEngine = {
+// What the composer submits before the catalog has rendered an engine button.
+const DEFAULT_ENGINE = Object.freeze({
id: 'trellis',
path: 'image',
backend: 'trellis',
byok: null,
polyControl: false,
-};
+ modly: false,
+ modelId: null,
+});
+let selectedEngine = { ...DEFAULT_ENGINE };
// Once the user deliberately picks an engine we stop auto-selecting the
// catalog's per-tier default (e.g. the free NVIDIA lane on draft) under them.
let userPickedEngine = false;
@@ -431,6 +451,7 @@ function revealStage() {
// Human label for a backend id, from the short-label map or the live catalog.
function engineLabel(id) {
if (!id) return 'the engine';
+ if (isModlyEngine(id)) return modlyEngineLabel(id);
return ENGINE_LABELS[id] || catalog?.backends?.find((b) => b.id === id)?.label || id;
}
@@ -520,6 +541,13 @@ function startElapsed(offsetMs = 0) {
const s = Math.floor((performance.now() - elapsedStart) / 1000);
// Re-read every tick: the accepted job replaces the catalog guess with the
// server's real ETA for the lane that actually ran (cold start included).
+ // A run on the user's own GPU reports a real percent and step, so the
+ // meter shows exactly that instead of a time-based estimate.
+ if (modlyRun) {
+ timeline.tick(s);
+ paintModlyProgress(s);
+ return;
+ }
const typical = currentEtaSeconds();
if (els.genProgress) els.genProgress.dataset.indeterminate = typical ? 'false' : 'true';
// The timeline's warming card counts real seconds against that same ETA.
@@ -686,7 +714,7 @@ function setMode(next) {
}
// Sketch serves through its own engine set (TripoSG) — rebuild the selector
// so each mode only offers engines that can actually take its input.
- if (catalog) buildEngineButtons();
+ refreshEnginePicker();
updateAspectVisibility();
// The estimate caption is tab-aware (text → "renders a preview"; photos →
// "builds from your reference photos"), so refresh it when the tab changes
@@ -764,7 +792,7 @@ function buildEngineButtons() {
if (!els.engine) return;
// Each mode offers only the engines that take its input: sketch mode shows
// the sketch-path engines (TripoSG); text/photo modes hide sketch-only ones.
- const usable = catalog.backends.filter((b) => {
+ const usable = (catalog?.backends || []).filter((b) => {
if (!(b.configured || b.byok)) return false;
const sketchOnly = Array.isArray(b.paths) && b.paths.every((p) => p === 'sketch');
return mode === 'sketch' ? b.paths.includes('sketch') : !sketchOnly;
@@ -797,6 +825,7 @@ function buildEngineButtons() {
btn.setAttribute('aria-pressed', String(b.id === selectedEngine.backend));
els.engine.appendChild(btn);
}
+ const modlyIds = appendModlyEngineButtons();
// Catalog loaded but no lane can serve this mode (every backend unconfigured,
// non-BYOK, or sketch-only in a text/photo tab) — say so rather than leave a
// blank pill. The catalog-missing case is handled separately in loadCatalog().
@@ -808,7 +837,7 @@ function buildEngineButtons() {
els.engine.appendChild(note);
}
// If the previously-selected engine isn't usable, fall back to the first.
- if (!usable.some((b) => b.id === selectedEngine.backend)) {
+ if (!usable.some((b) => b.id === selectedEngine.backend) && !modlyIds.includes(selectedEngine.backend)) {
const first = els.engine.querySelector('button');
if (first) selectEngine(first, true);
}
@@ -895,7 +924,12 @@ function selectEngine(btn, silent) {
backend: btn.dataset.backend,
byok: btn.dataset.byok || null,
polyControl: btn.dataset.poly === 'true',
+ modly: btn.dataset.modly === '1',
+ modelId: btn.dataset.modelId || null,
};
+ // A Modly model runs with its own settings, so the cloud quality tiers do
+ // not apply to it: hide that row rather than offer a control that does nothing.
+ els.tier?.classList.toggle('is-hidden', selectedEngine.modly);
for (const b of els.engine.querySelectorAll('button')) {
b.setAttribute('aria-pressed', String(b === btn));
}
@@ -952,7 +986,7 @@ let _highAccess = null; // last resolved forge.high access payload (for the gate
// own Meshy/Tripo/Rodin key would be wrongly blocked from High. Draft/Standard are never
// gated. Every client gate check keys on this, so the lock can never engage outside it.
function highTierNeedsPass() {
- return selectedTier === 'high' && !selectedEngine.byok;
+ return selectedTier === 'high' && !selectedEngine.byok && !selectedEngine.modly;
}
function accessHost() {
@@ -1146,7 +1180,12 @@ function costSegment(backend, tierMeta) {
// Render the honest time/cost/poly estimate for the current engine + tier from
// the catalog. No fabricated numbers — everything comes from /api/forge?catalog.
function updateEstimate() {
- if (!els.estimate || !catalog) return;
+ if (!els.estimate) return;
+ if (selectedEngine.modly) {
+ renderModlyEstimate();
+ return;
+ }
+ if (!catalog) return;
const backend = catalog.backends.find((b) => b.id === selectedEngine.backend);
const tierMeta = catalog.tiers.find((t) => t.id === selectedTier);
if (!backend || !tierMeta) {
@@ -2084,7 +2123,7 @@ function setViewsBadge(meta) {
parts.push(`${used} ${used === 1 ? 'view' : 'views'}`);
if (meta.multiview) parts.push('multi-view');
}
- if (meta?.backend) parts.push(ENGINE_LABELS[meta.backend] || meta.backend);
+ if (meta?.backend) parts.push(engineLabel(meta.backend));
if (meta?.tier) parts.push(meta.tier);
if (meta?.path === 'geometry') parts.push('geometry-first');
if (meta?.path === 'sketch') parts.push('sketch→3D');
@@ -2195,6 +2234,28 @@ function updateRefineButton() {
}
}
+// Point the cross-page result actions at this model. Also called when a local
+// (Modly) result gains its public copy after it was first shown.
+function linkResultTools(glbUrl) {
+ // Deep-link the physical lane at THIS generation. A creation id is the
+ // better handle (it carries the prompt and the creator through to the
+ // print), but a model that has not been persisted yet still materializes
+ // from its own URL, so the action is never dead.
+ if (els.materialize) {
+ const handle = currentCreationId
+ ? `?creation=${encodeURIComponent(currentCreationId)}`
+ : glbUrl && !glbUrl.startsWith('blob:')
+ ? `?glb=${encodeURIComponent(glbUrl)}`
+ : '';
+ els.materialize.href = `/materialize${handle}`;
+ els.materialize.hidden = false;
+ }
+ // Cross-link into Parts Studio with this exact model pre-loaded.
+ if (els.segmentBtn) els.segmentBtn.href = `/segment?mesh=${encodeURIComponent(glbUrl)}`;
+ if (els.openInComposer) els.openInComposer.href = `/compose?glb=${encodeURIComponent(glbUrl)}`;
+ if (els.irlBtn) els.irlBtn.href = `/irl?avatar=${encodeURIComponent(glbUrl)}`;
+}
+
// `glbUrl` is what the VIEWER loads and `downloadUrl` is what the Download
// button hands over. They differ for a re-opened creation that has a delivery
// variant (api/_lib/forge-store.js): the viewer takes the phone-sized meshopt +
@@ -2253,19 +2314,7 @@ function showResult(glbUrl, label, meta, { autoSaved = false, downloadUrl = null
// Hide after animation completes (3s).
setTimeout(() => els.savedChip?.classList.add('is-hidden'), 3100);
}
- // Deep-link the physical lane at THIS generation. A creation id is the
- // better handle (it carries the prompt and the creator through to the
- // print), but a model that has not been persisted yet still materializes
- // from its own URL, so the action is never dead.
- if (els.materialize) {
- const handle = currentCreationId
- ? `?creation=${encodeURIComponent(currentCreationId)}`
- : glbUrl && !glbUrl.startsWith('blob:')
- ? `?glb=${encodeURIComponent(glbUrl)}`
- : '';
- els.materialize.href = `/materialize${handle}`;
- els.materialize.hidden = false;
- }
+ linkResultTools(glbUrl);
els.download.href = downloadUrl || glbUrl;
els.download.setAttribute(
'download',
@@ -2276,10 +2325,6 @@ function showResult(glbUrl, label, meta, { autoSaved = false, downloadUrl = null
.replace(/^-|-$/g, '') || 'forge'
}.glb`,
);
- // Cross-link into Parts Studio with this exact model pre-loaded.
- if (els.segmentBtn) els.segmentBtn.href = `/segment?mesh=${encodeURIComponent(glbUrl)}`;
- if (els.openInComposer) els.openInComposer.href = `/compose?glb=${encodeURIComponent(glbUrl)}`;
- if (els.irlBtn) els.irlBtn.href = `/irl?avatar=${encodeURIComponent(glbUrl)}`;
// Offer "Refine" when a higher tier exists and this job can be re-run. Use the
// tier the result was actually produced at (meta), falling back to the current
// selection for re-opened gallery models that don't carry tier metadata.
@@ -2306,6 +2351,7 @@ function showResult(glbUrl, label, meta, { autoSaved = false, downloadUrl = null
if (els.forgeShareBtn) {
els.forgeShareBtn.dataset.sharePrompt = label;
}
+ if (!meta?.modly) hideModlySave();
}
// Deterministic gradient from prompt text — same prompt → same colours.
@@ -3028,6 +3074,411 @@ async function run(cfg) {
}
}
+// Your GPU (Modly) -----------------------------------------------------------
+// An opt-in lane that runs image-to-3D on the visitor's own graphics card
+// through Modly (src/modly-local.js, src/forge-modly.js). Its models join the
+// engine picker as `modly:<id>` engines, the run reports Modly's real percent
+// and step text, and the finished GLB enters the same result path as a cloud
+// generation once it has a public copy (rig, optimize and AR need a URL).
+
+function isModlyEngine(id) {
+ return typeof id === 'string' && id.startsWith('modly:');
+}
+
+function modlyEngineLabel(id) {
+ const modelId = id.slice('modly:'.length);
+ return `Your GPU (${modly?.modelById(modelId)?.name || modelId})`;
+}
+
+// Models that can serve the current tab: Modly takes a photo, so only the
+// photos tab offers them.
+function modlyReadyModels() {
+ return mode === 'image' && modly ? modly.readyModels() : [];
+}
+
+function appendModlyEngineButtons() {
+ const ids = [];
+ for (const m of modlyReadyModels()) {
+ const id = `modly:${m.id}`;
+ const btn = document.createElement('button');
+ btn.type = 'button';
+ Object.assign(btn.dataset, {
+ engine: id,
+ path: 'modly',
+ backend: id,
+ byok: '',
+ poly: 'false',
+ userimages: 'true',
+ modly: '1',
+ modelId: m.id,
+ });
+ const name = document.createElement('span');
+ name.className = 'eng-label';
+ name.textContent = m.name;
+ const pill = document.createElement('span');
+ pill.className = 'eng-free eng-local';
+ pill.setAttribute('aria-hidden', 'true');
+ pill.textContent = 'Your GPU, free';
+ btn.append(name, ' ', pill);
+ const vram = m.vramGb ? ` · needs about ${m.vramGb} GB of graphics memory` : '';
+ btn.title = `${m.name}: runs in Modly on your own graphics card, free${vram}`;
+ btn.setAttribute('aria-label', `${m.name}, runs on your GPU, free`);
+ btn.setAttribute('aria-pressed', String(id === selectedEngine.backend));
+ els.engine.appendChild(btn);
+ ids.push(id);
+ }
+ return ids;
+}
+
+// Rebuild the engine picker from whatever can serve right now: the cloud
+// catalog, the connected Modly models, or both. With no catalog (an older
+// deployment) the picker still appears for Modly alone.
+function refreshEnginePicker() {
+ if (!els.engine) return;
+ if (!catalog) {
+ const local = modlyReadyModels().length > 0;
+ els.engine.closest('#forge-quality')?.classList.toggle('is-hidden', !local);
+ if (!local) {
+ els.engine.innerHTML = '';
+ if (selectedEngine.modly) {
+ selectedEngine = { ...DEFAULT_ENGINE };
+ els.tier?.classList.remove('is-hidden');
+ }
+ return;
+ }
+ }
+ buildEngineButtons();
+}
+
+function onModlyChange(state) {
+ if (state.status === 'probing') return;
+ if (state.status !== 'connected' && selectedEngine.modly) userPickedEngine = false;
+ refreshEnginePicker();
+ // Connecting is an explicit opt-in, so a first connect puts a local model in
+ // the selection. A Refresh keeps whichever Modly model was already picked.
+ if (state.status === 'connected' && mode === 'image' && !selectedEngine.modly) {
+ const btn = els.engine?.querySelector('button[data-modly="1"]:not(:disabled)');
+ if (btn) {
+ userPickedEngine = true;
+ selectEngine(btn);
+ }
+ }
+ updateEstimate();
+}
+
+function renderModlyEstimate() {
+ const model = modly?.modelById(selectedEngine.modelId);
+ const parts = [
+ '<strong>Your GPU</strong>',
+ '<span class="est-free">Free</span>',
+ 'runs in Modly on this computer',
+ 'builds from your first photo',
+ ];
+ if (model?.vramGb) parts.push(`needs about ${Number(model.vramGb)} GB of graphics memory`);
+ els.estimate.innerHTML = parts.join(' · ');
+}
+
+function paintModlyProgress(elapsedS) {
+ const pending = modlyRun.state === 'pending';
+ if (els.genProgress) {
+ els.genProgress.dataset.indeterminate = String(pending);
+ els.genProgress.dataset.over = 'false';
+ }
+ if (!pending) setProgress(modlyRun.pct);
+ const strong = document.createElement('strong');
+ strong.textContent = `${elapsedS}s`;
+ els.genMeta.replaceChildren('Elapsed ', strong, pending ? '' : ` · ${modlyRun.pct}%`);
+ if (modlyRun.step) els.genMeta.append(` · ${modlyRun.step}`);
+}
+
+// The photo Modly builds from: the first view the user added. Modly takes a
+// single image, so extra views are named as unused rather than silently dropped.
+function modlySourceSlot() {
+ const index = slots.findIndex(
+ (s) => (s.state === 'uploaded' || s.state === 'uploading') && s.objectUrl,
+ );
+ return index < 0 ? null : { index, slot: slots[index] };
+}
+
+function modlyErrorCopy(err, modelName) {
+ switch (err?.code) {
+ case 'GENERATION_FAILED':
+ return {
+ title: `${modelName} couldn't finish`,
+ message: `Modly reported: ${err.message} The full trace is in Modly's log.`,
+ };
+ case 'CANCELLED':
+ return {
+ title: 'Cancelled in Modly',
+ message: 'The generation was stopped from inside the Modly app. Press Try again to run it again.',
+ };
+ case 'NOT_RUNNING':
+ case 'BLOCKED':
+ case 'TIMEOUT':
+ return {
+ title: 'Modly stopped answering',
+ message: `${err.message} Make sure Modly is still open, then press Try again.`,
+ };
+ case 'UNKNOWN_MODEL':
+ return {
+ title: 'Model not available in Modly',
+ message: `${err.message} Press Refresh under "Use your GPU" to reload the model list.`,
+ };
+ default:
+ return {
+ title: 'Modly couldn’t finish',
+ message: err?.message || 'Modly could not finish this generation.',
+ };
+ }
+}
+
+async function runModly(modelId) {
+ if (modlyRun) return;
+ stopRateLimitCountdown();
+ lastJob = { modly: true, modelId };
+ // A Retry after Modly restarted: look for it again before giving up.
+ if (modly && modly.state.status !== 'connected') await modly.connect();
+ const origin = modly?.state.status === 'connected' ? modly.state.origin : null;
+ const model = origin ? modly.readyModels().find((m) => m.id === modelId) : null;
+ if (!origin) {
+ showError(
+ 'Forge could not reach Modly on this computer. Start Modly, then press Try again. The "Use your GPU" panel in the photos tab shows what the browser saw.',
+ { title: 'Modly is not reachable' },
+ );
+ return;
+ }
+ if (!model) {
+ showError(
+ `${modelId} is no longer downloaded in Modly. Pick another engine, or download it again in Modly's Models page.`,
+ { title: 'Model not available in Modly' },
+ );
+ return;
+ }
+ const source = modlySourceSlot();
+ if (!source) {
+ const first = slotEl(0);
+ first?.focus();
+ first?.classList.add('drop-target');
+ setTimeout(() => first?.classList.remove('drop-target'), 600);
+ return;
+ }
+ let image;
+ try {
+ image = await (await fetch(source.slot.objectUrl)).blob();
+ } catch {
+ showError('Forge could not read your photo. Add it again, then press Try again.', {
+ title: 'Photo unavailable',
+ });
+ return;
+ }
+
+ const backend = `modly:${modelId}`;
+ const controller = new AbortController();
+ modlyRun = { controller, pct: 0, step: 'Sending your photo to Modly', state: 'pending' };
+ currentCreationId = null;
+ pollAbort = false;
+ setBusy(true);
+ timeline.begin({
+ mode: 'image',
+ backend,
+ viewCount: 1,
+ localPreviewUrl: source.slot.objectUrl,
+ usesReference: false,
+ local: true,
+ });
+ const views = slots.filter((s) => s.state === 'uploaded' || s.state === 'uploading').length;
+ setLaneNote(
+ views > 1
+ ? `Modly builds from a single photo, so only your ${VIEW_LABELS[source.index]} view is used.`
+ : '',
+ );
+ // A local run lives in this tab: leaving the page would stop following it.
+ if (els.genLeaveHint) els.genLeaveHint.hidden = true;
+ startElapsed();
+ showState('generating');
+ revealStage();
+
+ const prompt = els.imagePrompt?.value.trim() || '';
+ const label = prompt || `${model.name} model`;
+ try {
+ const result = await generateWithModly(origin, {
+ image,
+ modelId,
+ params: defaultModlyParams(model.paramsSchema),
+ signal: controller.signal,
+ onStarted: () => timeline.applySubmit({ backend, status: 'queued' }),
+ onProgress: (pct, step, state) => {
+ if (modlyRun?.controller !== controller) return;
+ Object.assign(modlyRun, { pct, step, state: state || modlyRun.state });
+ if (state === 'done') {
+ timeline.finalizing();
+ } else {
+ timeline.applyPoll({ status: state === 'running' ? 'running' : 'queued' });
+ timeline.setStepText(step);
+ }
+ elapsedRetick?.();
+ },
+ });
+
+ // The mesh is on this machine. Give it a public copy so every downstream
+ // tool (rig, optimize, AR, embed, save) can fetch it like a cloud result.
+ Object.assign(modlyRun, { pct: 100, step: 'Copying the model to three.ws storage' });
+ elapsedRetick?.();
+ markProgressDone();
+ const objectUrl = URL.createObjectURL(result.blob);
+ let publicUrl = '';
+ let storageError = '';
+ try {
+ publicUrl = await promoteModlyGlb(result.blob, { signal: controller.signal });
+ } catch (err) {
+ if (controller.signal.aborted) {
+ URL.revokeObjectURL(objectUrl);
+ throw err;
+ }
+ storageError = err?.message || 'Storage is unavailable.';
+ }
+
+ releaseModlyResult();
+ modlyResult = {
+ objectUrl,
+ publicUrl,
+ storageError,
+ blob: result.blob,
+ label,
+ prompt,
+ modelName: model.name,
+ };
+ showResult(
+ publicUrl || objectUrl,
+ label,
+ { backend, views_used: 1, modly: true },
+ { downloadUrl: objectUrl },
+ );
+ timeline.complete();
+ // Not a server-side creation: the creation-scoped feedback controls
+ // (verdict, category, destination) would have nothing to write to.
+ if (els.verdict) els.verdict.hidden = true;
+ if (els.categoryPicker) els.categoryPicker.hidden = true;
+ destinationPicker.hide();
+ renderModlySave();
+ } catch (err) {
+ const ours = controller.signal.aborted;
+ if (ours) {
+ // The person pressed Cancel; generateWithModly already told Modly to stop.
+ stopElapsed();
+ timeline.fail();
+ showState('empty');
+ modly?.notify('Cancelled. Modly stopped the generation.');
+ els.imagePrompt?.focus();
+ return;
+ }
+ const copy = modlyErrorCopy(err, model.name);
+ showError(copy.message, { title: copy.title });
+ } finally {
+ if (modlyRun?.controller === controller) modlyRun = null;
+ if (els.genLeaveHint) els.genLeaveHint.hidden = false;
+ setBusy(false);
+ }
+}
+
+function releaseModlyResult() {
+ if (modlyResult?.objectUrl) URL.revokeObjectURL(modlyResult.objectUrl);
+ modlyResult = null;
+}
+
+// Any non-local result replaces the local one: drop its save row and blob.
+function hideModlySave() {
+ if (els.modlySave) els.modlySave.hidden = true;
+ if (els.verdict) els.verdict.hidden = false;
+ releaseModlyResult();
+}
+
+// The save row under a local result. `phase` is one of: ready, saving,
+// signin, saved, error.
+function renderModlySave(phase = 'ready', detail = {}) {
+ if (!els.modlySave || !modlyResult) return;
+ const r = modlyResult;
+ const text = els.modlySaveText;
+ const btn = els.modlySaveBtn;
+ els.modlySave.hidden = false;
+ text.dataset.tone = phase === 'saved' ? 'ok' : phase === 'error' || phase === 'signin' ? 'error' : '';
+ btn.hidden = phase === 'saved';
+ btn.disabled = phase === 'saving';
+ btn.setAttribute('aria-busy', String(phase === 'saving'));
+ btn.textContent = r.publicUrl ? 'Save to my avatars' : 'Upload and save';
+ const strong = (s) => {
+ const el = document.createElement('strong');
+ el.textContent = s;
+ return el;
+ };
+ const link = (href, s) => {
+ const a = document.createElement('a');
+ a.href = href;
+ a.textContent = s;
+ return a;
+ };
+ if (phase === 'saving') {
+ text.replaceChildren(r.publicUrl ? 'Saving to your avatars…' : 'Uploading, then saving to your avatars…');
+ } else if (phase === 'saved') {
+ text.replaceChildren(strong('Saved to your avatars.'), ' ');
+ if (detail.viewUrl) text.append(link(detail.viewUrl, 'Open it'));
+ } else if (phase === 'signin') {
+ text.replaceChildren(
+ strong('Sign in to save it.'),
+ ' ',
+ link(`/login?next=${encodeURIComponent('/forge')}`, 'Sign in'),
+ ' in a new tab if you want to keep this model on screen, then press Save again. Download works without an account.',
+ );
+ } else if (phase === 'error') {
+ text.replaceChildren(strong('Not saved.'), ` ${detail.message || 'Try again.'}`);
+ } else if (r.publicUrl) {
+ text.replaceChildren(
+ `Made on your GPU with ${r.modelName}. It is not in Your creations: save it to your avatars to keep it in your library.`,
+ );
+ } else {
+ text.replaceChildren(
+ strong('Only on this computer.'),
+ ` Copying it to three.ws failed (${r.storageError}), so rigging, optimizing and saving need an upload first. Download keeps the GLB either way.`,
+ );
+ }
+}
+
+async function saveModlyResult() {
+ const r = modlyResult;
+ if (!r) return;
+ renderModlySave('saving');
+ if (!r.publicUrl) {
+ try {
+ r.publicUrl = await promoteModlyGlb(r.blob);
+ r.storageError = '';
+ } catch (err) {
+ r.storageError = err?.message || 'Storage is unavailable.';
+ renderModlySave('error', { message: `Upload failed: ${r.storageError}` });
+ return;
+ }
+ if (modlyResult !== r) return;
+ // The model now has a public URL: hand it to the result tools that need one.
+ linkResultTools(r.publicUrl);
+ lastShownGlb = r.publicUrl;
+ document.dispatchEvent(
+ new CustomEvent('forge:model-ready', { detail: { glbUrl: r.publicUrl, label: r.label } }),
+ );
+ }
+ const out = await saveModlyResultToLibrary({
+ glbUrl: r.publicUrl,
+ name: r.label,
+ sourcePrompt: r.prompt,
+ modelName: r.modelName,
+ });
+ if (modlyResult !== r) return;
+ if (out.ok) renderModlySave('saved', { viewUrl: out.viewUrl });
+ else if (out.status === 401) renderModlySave('signin');
+ else renderModlySave('error', { message: out.message });
+}
+
+els.modlySaveBtn?.addEventListener('click', saveModlyResult);
+modly = createModlyPanel({ root: els.modlyPanel, onChange: onModlyChange });
+
// Resume an in-flight generation persisted before a reload/navigation. The
// server holds all job state, so picking it back up is just polling the same
// job id; the panel restores in its mesh phase with an honest elapsed count.
@@ -3156,6 +3607,11 @@ function collectComposerCfg() {
}
function submit() {
+ // Your GPU lane: the run happens in Modly on this computer, not /api/forge.
+ if (selectedEngine.modly && mode === 'image') {
+ runModly(selectedEngine.modelId);
+ return;
+ }
// Platform-keyed High is a $THREE holder perk. The Generate button is disabled
// when locked, but a keyboard submit (⌘↵) can still reach here — open the upsell
// (with the working Pay-per-use path) instead of firing a request the server will
@@ -3373,6 +3829,12 @@ els.providerKey?.addEventListener('input', () => {
});
els.cancel.addEventListener('click', () => {
+ // Aborting a local run makes generateWithModly call Modly's own cancel
+ // endpoint, so the GPU stops working too; runModly shows the outcome.
+ if (modlyRun) {
+ modlyRun.controller.abort();
+ return;
+ }
pollAbort = true;
clearInflight();
stopElapsed();
@@ -3408,7 +3870,9 @@ els.retry.addEventListener('click', () => {
stopRateLimitCountdown();
if (els.categoryPicker) els.categoryPicker.hidden = true;
destinationPicker.hide();
- if (lastJob && (lastJob.prompt || (lastJob.imageUrls && lastJob.imageUrls.length))) {
+ if (lastJob?.modly) {
+ runModly(lastJob.modelId);
+ } else if (lastJob && (lastJob.prompt || (lastJob.imageUrls && lastJob.imageUrls.length))) {
run(lastJob);
} else {
showState('empty');
diff --git a/src/modly-local.js b/src/modly-local.js
new file mode 100644
index 000000000..0e7ce25b6
--- /dev/null
+++ b/src/modly-local.js
@@ -0,0 +1,730 @@
+// Browser client for Modly, the local image-to-3D desktop app.
+//
+// Adapted from Modly (https://github.com/lightningpixel/modly), MIT License, Copyright (c) 2026 Lightning Pixel
+//
+// The HTTP contract below is taken from Modly's FastAPI backend (api/main.py and
+// api/routers/{model,workflow_runs,generation,export,optimize}.py), and the
+// workspace-path rules and the run-then-export flow follow its own agent CLI
+// (tools/modly-cli/agent.py). Modly listens on http://localhost:8765 with
+// CORS `allow_origins=["*"]`, so a page on https://three.ws can talk to it
+// directly: every request here is a CORS "simple" request (GET, or a POST with
+// a multipart or JSON body that FastAPI accepts), credentials are never sent,
+// and nothing leaves the user's machine except the page's own fetches.
+//
+// Nothing in this module runs on import. Probing loopback triggers Chrome's
+// Local Network Access prompt, so callers must only probe after a user gesture.
+
+/** Where Modly's installer lives. Shown in the "not detected" state. */
+export const MODLY_INSTALL_URL = 'https://modly3d.app/';
+
+/** Modly's documented default port, on both loopback spellings. */
+export const MODLY_DEFAULT_ORIGINS = Object.freeze(['http://127.0.0.1:8765', 'http://localhost:8765']);
+
+const OVERRIDE_KEY = 'tws:modly-origin';
+const DEFAULT_PROBE_TIMEOUT_MS = 2500;
+const DEFAULT_POLL_INTERVAL_MS = 2000;
+// Modly's own CLI waits 30 minutes for a run; big models on small GPUs need it.
+const DEFAULT_RUN_TIMEOUT_MS = 30 * 60 * 1000;
+const GLB_MAGIC = 0x46546c67; // "glTF", little-endian
+
+/**
+ * Typed failure from the Modly client. `code` is stable and safe to branch on:
+ * NOT_RUNNING no Modly answered at the origin
+ * BLOCKED the browser refused the loopback request (see `reason`)
+ * BAD_ORIGIN a user-supplied origin is not an http(s) URL
+ * BAD_INPUT the caller passed an unusable argument
+ * BAD_REQUEST Modly rejected the request (HTTP 400), `message` is Modly's text
+ * UNKNOWN_MODEL the model id is not installed in Modly
+ * NOT_FOUND Modly answered 404 (unknown run, op, or file)
+ * UNAVAILABLE Modly answered 503 (mesh op dependency missing or failed)
+ * HTTP any other non-2xx answer
+ * RUN_LOST Modly forgot the run (it was restarted mid-generation)
+ * GENERATION_FAILED the model raised; `message` is the exception line, `detail` the traceback
+ * CANCELLED the run was cancelled (by our signal or inside Modly)
+ * TIMEOUT the run outlived `timeoutMs`
+ * BAD_PATH Modly reported a workspace path that escapes the workspace
+ * NOT_GLB the exported file is not a binary glTF
+ * UPLOAD_UNSUPPORTED Modly has no endpoint that accepts mesh bytes
+ */
+export class ModlyError extends Error {
+ constructor(code, message, { status = 0, detail = '', reason = '', cause } = {}) {
+ super(message, cause ? { cause } : undefined);
+ this.name = 'ModlyError';
+ this.code = code;
+ this.status = status;
+ this.detail = detail;
+ this.reason = reason;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Origins
+// ---------------------------------------------------------------------------
+
+function readOverride() {
+ try {
+ return globalThis.localStorage?.getItem(OVERRIDE_KEY) || '';
+ } catch {
+ return '';
+ }
+}
+
+/**
+ * Normalize something a person typed ("localhost:9000", "http://10.0.0.5:8765/")
+ * into a bare origin. Throws BAD_ORIGIN for anything that is not http(s).
+ */
+export function normalizeModlyOrigin(input) {
+ const raw = String(input ?? '').trim();
+ if (!raw) throw new ModlyError('BAD_ORIGIN', 'Enter the address Modly is listening on, for example http://localhost:8765.');
+ const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`;
+ let url;
+ try {
+ url = new URL(withScheme);
+ } catch {
+ throw new ModlyError('BAD_ORIGIN', `"${raw}" is not a valid address.`);
+ }
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+ throw new ModlyError('BAD_ORIGIN', 'Modly is reached over http or https.');
+ }
+ return url.origin;
+}
+
+function buildOrigins(override) {
+ const list = [];
+ if (override) {
+ try {
+ list.push(normalizeModlyOrigin(override));
+ } catch {
+ // A corrupt stored value is ignored; the defaults still apply.
+ }
+ }
+ for (const o of MODLY_DEFAULT_ORIGINS) if (!list.includes(o)) list.push(o);
+ return list;
+}
+
+/**
+ * Origins probed in order: the user's saved override first (if any), then the
+ * two loopback defaults. This array is live: setModlyOriginOverride updates it
+ * in place, so importers holding a reference always see the current list.
+ */
+export const MODLY_ORIGINS = buildOrigins(readOverride());
+
+/** The saved custom origin, or '' when none is set. */
+export function getModlyOriginOverride() {
+ const stored = readOverride();
+ if (!stored) return '';
+ try {
+ return normalizeModlyOrigin(stored);
+ } catch {
+ return '';
+ }
+}
+
+/**
+ * Save (or with a falsy value, clear) a custom Modly origin and refresh
+ * MODLY_ORIGINS. Returns the normalized origin, or '' when cleared.
+ */
+export function setModlyOriginOverride(origin) {
+ const normalized = origin ? normalizeModlyOrigin(origin) : '';
+ try {
+ if (normalized) globalThis.localStorage?.setItem(OVERRIDE_KEY, normalized);
+ else globalThis.localStorage?.removeItem(OVERRIDE_KEY);
+ } catch {
+ // Storage can be blocked (private mode); the in-memory list still updates.
+ }
+ MODLY_ORIGINS.splice(0, MODLY_ORIGINS.length, ...buildOrigins(normalized));
+ return normalized;
+}
+
+// ---------------------------------------------------------------------------
+// Transport
+// ---------------------------------------------------------------------------
+
+// One controller that aborts when the caller's signal does or when the timeout
+// fires, whichever comes first. `dispose` must run when the request settles.
+function linkSignal(signal, timeoutMs) {
+ const ctrl = new AbortController();
+ let timer = null;
+ const onAbort = () => ctrl.abort(signal.reason);
+ if (signal) {
+ if (signal.aborted) ctrl.abort(signal.reason);
+ else signal.addEventListener('abort', onAbort, { once: true });
+ }
+ if (timeoutMs > 0) timer = setTimeout(() => ctrl.abort(new ModlyError('TIMEOUT', 'Modly did not answer in time.')), timeoutMs);
+ return {
+ signal: ctrl.signal,
+ dispose() {
+ if (timer) clearTimeout(timer);
+ signal?.removeEventListener('abort', onAbort);
+ },
+ };
+}
+
+function cancelledError(cause) {
+ return new ModlyError('CANCELLED', 'The Modly generation was cancelled.', { cause });
+}
+
+// FastAPI errors are `{"detail": "..."}` for HTTPException and
+// `{"detail": [{loc, msg, type}]}` for request validation (422).
+function detailText(body) {
+ const d = body?.detail;
+ if (typeof d === 'string') return d;
+ if (Array.isArray(d)) {
+ return d
+ .map((e) => [Array.isArray(e?.loc) ? e.loc.filter((p) => p !== 'body').join('.') : '', e?.msg].filter(Boolean).join(': '))
+ .filter(Boolean)
+ .join('; ');
+ }
+ return '';
+}
+
+async function errorFromResponse(res) {
+ let text = '';
+ try {
+ const raw = await res.text();
+ try {
+ text = detailText(JSON.parse(raw)) || raw;
+ } catch {
+ text = raw;
+ }
+ } catch {
+ text = '';
+ }
+ text = String(text || '').trim().slice(0, 2000);
+ const status = res.status;
+ if (status === 404) return new ModlyError('NOT_FOUND', text || 'Modly could not find that resource.', { status });
+ if (status === 400 && /unknown model/i.test(text)) return new ModlyError('UNKNOWN_MODEL', text, { status });
+ if (status === 400 || status === 422) return new ModlyError('BAD_REQUEST', text || 'Modly rejected the request.', { status });
+ if (status === 503) return new ModlyError('UNAVAILABLE', text || 'Modly could not run that operation.', { status });
+ return new ModlyError('HTTP', text || `Modly answered HTTP ${status}.`, { status });
+}
+
+// fetch against Modly. A network-level failure (connection refused, blocked by
+// the browser) becomes NOT_RUNNING; aborts surface as CANCELLED or TIMEOUT.
+async function modlyFetch(origin, path, { signal, timeoutMs = 0, ...init } = {}) {
+ const link = linkSignal(signal, timeoutMs);
+ try {
+ const res = await fetch(`${origin}${path}`, {
+ ...init,
+ mode: 'cors',
+ credentials: 'omit',
+ cache: 'no-store',
+ signal: link.signal,
+ });
+ if (!res.ok) throw await errorFromResponse(res);
+ return res;
+ } catch (err) {
+ if (err instanceof ModlyError) throw err;
+ if (link.signal.aborted) {
+ const reason = link.signal.reason;
+ if (reason instanceof ModlyError) throw reason;
+ throw cancelledError(err);
+ }
+ throw new ModlyError('NOT_RUNNING', `Could not reach Modly at ${origin}.`, { cause: err });
+ } finally {
+ link.dispose();
+ }
+}
+
+async function modlyJson(origin, path, opts) {
+ const res = await modlyFetch(origin, path, opts);
+ try {
+ return await res.json();
+ } catch (err) {
+ throw new ModlyError('HTTP', `Modly sent an unreadable answer for ${path}.`, { status: res.status, cause: err });
+ }
+}
+
+function postJson(body) {
+ return {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify(body),
+ };
+}
+
+function sleep(ms, signal) {
+ return new Promise((resolve, reject) => {
+ if (signal?.aborted) return reject(cancelledError(signal.reason));
+ const timer = setTimeout(() => {
+ signal?.removeEventListener('abort', onAbort);
+ resolve();
+ }, ms);
+ function onAbort() {
+ clearTimeout(timer);
+ reject(cancelledError(signal.reason));
+ }
+ signal?.addEventListener('abort', onAbort, { once: true });
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+function isSafari() {
+ const ua = globalThis.navigator?.userAgent || '';
+ return /Safari\//.test(ua) && !/(Chrome|Chromium|CriOS|FxiOS|Edg|OPR|Android)\//.test(ua);
+}
+
+// Chrome's Local Network Access permission. Older builds name it
+// 'loopback-network'; browsers without it throw on query, which means "no gate".
+async function localNetworkPermission() {
+ const perms = globalThis.navigator?.permissions;
+ if (!perms?.query) return 'unsupported';
+ for (const name of ['local-network-access', 'loopback-network']) {
+ try {
+ const status = await perms.query({ name });
+ if (status?.state) return status.state;
+ } catch {
+ // Unknown permission name in this browser; try the next spelling.
+ }
+ }
+ return 'unsupported';
+}
+
+/**
+ * Why a failed probe failed, as far as the page can tell. A refused connection
+ * and a browser block look identical to fetch, so this reads the signals the
+ * browser does expose: Safari blocks http loopback from an https page as mixed
+ * content, and Chrome reports a denied Local Network Access permission.
+ */
+async function blockReason() {
+ const permission = await localNetworkPermission();
+ if (permission === 'denied') return 'lna-denied';
+ const pageIsHttps = globalThis.location?.protocol === 'https:';
+ if (pageIsHttps && isSafari()) return 'mixed-content';
+ return '';
+}
+
+async function pingHealth(origin, { signal, timeoutMs }) {
+ const body = await modlyJson(origin, '/health', { signal, timeoutMs });
+ if (body?.status !== 'ok') throw new ModlyError('NOT_RUNNING', `${origin} answered, but it is not Modly.`);
+ return true;
+}
+
+/**
+ * Probe every origin in MODLY_ORIGINS (or `origins`) for a running Modly and
+ * explain the outcome. Never throws.
+ *
+ * @returns {Promise<{status:'connected'|'not-running'|'blocked', origin:string|null,
+ * models:Array, reason:string, error?:ModlyError}>}
+ * `reason` is 'lna-denied' or 'mixed-content' when blocked.
+ */
+export async function probeModly({ signal, timeoutMs = DEFAULT_PROBE_TIMEOUT_MS, origins = MODLY_ORIGINS } = {}) {
+ let lastError = null;
+ for (const origin of origins) {
+ if (signal?.aborted) break;
+ try {
+ await pingHealth(origin, { signal, timeoutMs });
+ } catch (err) {
+ lastError = err;
+ continue;
+ }
+ try {
+ const models = await listModlyModels(origin, { signal });
+ return { status: 'connected', origin, models, reason: '' };
+ } catch (err) {
+ // Modly is up but the model list failed: still report it, the caller
+ // can show Modly's own error text.
+ return { status: 'connected', origin, models: [], reason: '', error: err };
+ }
+ }
+ const reason = await blockReason();
+ if (reason) return { status: 'blocked', origin: null, models: [], reason, error: lastError || undefined };
+ return { status: 'not-running', origin: null, models: [], reason: '', error: lastError || undefined };
+}
+
+/**
+ * Find a running Modly. Resolves `{ origin, models }`, or `null` when none is
+ * reachable (including when the browser blocks loopback). Never throws.
+ */
+export async function detectModly({ signal, timeoutMs } = {}) {
+ try {
+ const probe = await probeModly({ signal, timeoutMs });
+ return probe.status === 'connected' ? { origin: probe.origin, models: probe.models } : null;
+ } catch {
+ return null;
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Models
+// ---------------------------------------------------------------------------
+
+// Modly's ParamSchema (src/shared/types/electron.d.ts), kept in Modly's own
+// field names so a consumer can render it exactly as Modly does.
+function normalizeParam(p) {
+ if (!p || typeof p !== 'object' || !p.id) return null;
+ const out = {
+ id: String(p.id),
+ label: String(p.label || p.id),
+ type: String(p.type || 'string'),
+ default: p.default,
+ };
+ if (Array.isArray(p.options)) {
+ out.options = p.options.map((o) => (o && typeof o === 'object' ? { value: o.value, label: String(o.label ?? o.value) } : { value: o, label: String(o) }));
+ }
+ for (const k of ['min', 'max', 'step']) if (typeof p[k] === 'number') out[k] = p[k];
+ if (p.tooltip) out.tooltip = String(p.tooltip);
+ if (p.show_if && typeof p.show_if === 'object') out.show_if = p.show_if;
+ return out;
+}
+
+/** Normalize one `/model/all` entry. Exported for tests and other consumers. */
+export function normalizeModlyModel(m, paramsSchema = []) {
+ return {
+ id: String(m.id),
+ name: String(m.name || m.id),
+ description: String(m.description || ''),
+ version: String(m.version || ''),
+ vramGb: typeof m.vram_gb === 'number' ? m.vram_gb : null,
+ tags: Array.isArray(m.tags) ? m.tags.map(String) : [],
+ downloaded: !!m.downloaded,
+ loaded: !!m.loaded,
+ active: !!m.active,
+ // /model/all does not carry these; Modly's registry defaults a manifest
+ // without them to an image-in, mesh-out generator.
+ input: String(m.input || 'image'),
+ output: String(m.output || 'mesh'),
+ paramsSchema: (Array.isArray(paramsSchema) ? paramsSchema : []).map(normalizeParam).filter(Boolean),
+ };
+}
+
+/** GET /model/params?model_id=... normalized. Resolves [] for a model with no params. */
+export async function getModlyModelParams(origin, modelId, { signal } = {}) {
+ const list = await modlyJson(origin, `/model/params?model_id=${encodeURIComponent(modelId)}`, { signal });
+ return (Array.isArray(list) ? list : []).map(normalizeParam).filter(Boolean);
+}
+
+/**
+ * Every generator installed in Modly, with its parameter schema.
+ * @returns {Promise<Array<{id,name,downloaded,input,output,paramsSchema,description,version,vramGb,tags,loaded,active}>>}
+ */
+export async function listModlyModels(origin, { signal } = {}) {
+ const raw = await modlyJson(origin, '/model/all', { signal });
+ const models = (Array.isArray(raw) ? raw : []).filter((m) => m && m.id);
+ return Promise.all(
+ models.map(async (m) => {
+ let params = [];
+ try {
+ params = await getModlyModelParams(origin, m.id, { signal });
+ } catch (err) {
+ if (err?.code === 'CANCELLED') throw err;
+ // A generator that cannot describe its params still generates with defaults.
+ }
+ return normalizeModlyModel(m, params);
+ }),
+ );
+}
+
+/** Default param values from a model's schema, as Modly's own UI seeds them. */
+export function defaultModlyParams(paramsSchema = []) {
+ const out = {};
+ for (const p of paramsSchema) if (p && p.id && p.default !== undefined) out[p.id] = p.default;
+ return out;
+}
+
+// ---------------------------------------------------------------------------
+// Generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a workspace-relative path Modly reported: relative, no `..`, no
+ * drive letter, no URL scheme. Same rules as Modly's CLI.
+ */
+export function validateModlyWorkspacePath(value) {
+ const s = String(value ?? '');
+ const parts = s.replace(/\\/g, '/').split('/');
+ const bad =
+ !s ||
+ s.startsWith('/') ||
+ s.startsWith('\\') ||
+ /^[a-z][a-z0-9+.-]*:/i.test(s) ||
+ parts.some((p) => p === '..') ||
+ parts.some((p) => p.length >= 2 && /[a-z]/i.test(p[0]) && p[1] === ':');
+ if (bad) throw new ModlyError('BAD_PATH', `Modly reported an invalid workspace path: ${s}`);
+ return s;
+}
+
+/** The workspace path of a finished run (scene_candidate first, then output_url). */
+export function modlyRunWorkspacePath(status) {
+ const candidate = status?.scene_candidate?.workspace_path;
+ if (candidate) return validateModlyWorkspacePath(candidate);
+ const url = String(status?.output_url || '');
+ if (!url) throw new ModlyError('BAD_PATH', 'Modly finished without reporting an output file.');
+ let path = url;
+ try {
+ if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) path = new URL(url).pathname;
+ } catch {
+ path = url;
+ }
+ const prefix = '/workspace/';
+ if (path.startsWith(prefix)) path = path.slice(prefix.length);
+ try {
+ path = decodeURIComponent(path);
+ } catch {
+ throw new ModlyError('BAD_PATH', `Modly reported an invalid workspace path: ${url}`);
+ }
+ return validateModlyWorkspacePath(path);
+}
+
+/**
+ * Modly stores the full Python traceback as a run's error. Lift the final
+ * exception line ("RuntimeError: CUDA out of memory") for display; the whole
+ * text stays on `detail`.
+ */
+export function summarizeModlyError(text) {
+ const lines = String(text || '')
+ .split(/\r?\n/)
+ .map((l) => l.trim())
+ .filter(Boolean);
+ if (!lines.length) return 'Modly reported a failure without details.';
+ const last = lines[lines.length - 1];
+ const m = /^(?:[\w.]+(?:Error|Exception|Exit|Interrupt|Cancelled)|\w+Error):\s*(.+)$/.exec(last);
+ return (m ? m[1] : last).slice(0, 400);
+}
+
+const IMAGE_SIGNATURES = [
+ { type: 'image/png', bytes: [0x89, 0x50, 0x4e, 0x47] },
+ { type: 'image/jpeg', bytes: [0xff, 0xd8, 0xff] },
+ { type: 'image/gif', bytes: [0x47, 0x49, 0x46, 0x38] },
+ { type: 'image/webp', bytes: [0x52, 0x49, 0x46, 0x46], extra: { offset: 8, bytes: [0x57, 0x45, 0x42, 0x50] } },
+];
+
+function matchAt(view, offset, bytes) {
+ if (view.length < offset + bytes.length) return false;
+ return bytes.every((b, i) => view[offset + i] === b);
+}
+
+// Modly rejects any upload whose content type is not image/*. A Blob with no
+// type (a canvas export, a fetched object URL) is sniffed rather than guessed.
+async function asTypedImage(image) {
+ if (!(image instanceof Blob)) throw new ModlyError('BAD_INPUT', 'Pass the image as a Blob or File.');
+ if (image.size === 0) throw new ModlyError('BAD_INPUT', 'The image is empty.');
+ if (image.type && image.type.startsWith('image/')) return image;
+ const head = new Uint8Array(await image.slice(0, 16).arrayBuffer());
+ const sig = IMAGE_SIGNATURES.find((s) => matchAt(head, 0, s.bytes) && (!s.extra || matchAt(head, s.extra.offset, s.extra.bytes)));
+ if (!sig) throw new ModlyError('BAD_INPUT', 'Modly needs a PNG, JPEG, WebP, or GIF image.');
+ return new Blob([image], { type: sig.type });
+}
+
+function imageFilename(image, typed) {
+ if (typeof image.name === 'string' && image.name) return image.name;
+ const ext = (typed.type.split('/')[1] || 'png').replace('jpeg', 'jpg');
+ return `image.${ext}`;
+}
+
+async function startRun(origin, { image, modelId, params, collection, signal }) {
+ const typed = await asTypedImage(image);
+ const filename = imageFilename(image, typed);
+ const form = () => {
+ const fd = new FormData();
+ fd.append('image', typed, filename);
+ fd.append('model_id', modelId);
+ fd.append('params', JSON.stringify(params || {}));
+ if (collection) fd.append('collection', collection);
+ return fd;
+ };
+ try {
+ const body = await modlyJson(origin, '/workflow-runs/from-image', { method: 'POST', body: form(), signal });
+ if (!body?.run_id) throw new ModlyError('HTTP', 'Modly did not return a run id.');
+ return { id: String(body.run_id), api: 'workflow-runs' };
+ } catch (err) {
+ // Builds that predate /workflow-runs only expose the legacy route.
+ if (!(err instanceof ModlyError) || (err.status !== 404 && err.status !== 405)) throw err;
+ }
+ const body = await modlyJson(origin, '/generate/from-image', { method: 'POST', body: form(), signal });
+ if (!body?.job_id) throw new ModlyError('HTTP', 'Modly did not return a job id.');
+ return { id: String(body.job_id), api: 'legacy' };
+}
+
+function statusPath(run) {
+ const id = encodeURIComponent(run.id);
+ return run.api === 'legacy' ? `/generate/status/${id}` : `/workflow-runs/${id}`;
+}
+
+function cancelPath(run) {
+ const id = encodeURIComponent(run.id);
+ return run.api === 'legacy' ? `/generate/cancel/${id}` : `/workflow-runs/${id}/cancel`;
+}
+
+/**
+ * Ask Modly to cancel a run. Resolves true when Modly confirmed, false when it
+ * could not be reached or no longer knows the run. Never throws.
+ */
+export async function cancelModlyRun(origin, runId, { api = 'workflow-runs' } = {}) {
+ try {
+ const body = await modlyJson(origin, cancelPath({ id: runId, api }), { method: 'POST', timeoutMs: 5000 });
+ return body?.cancelled === true;
+ } catch {
+ return false;
+ }
+}
+
+/** GET /export/glb for a workspace path, verified to be a binary glTF. */
+export async function downloadModlyGlb(origin, workspacePath, { signal } = {}) {
+ const path = validateModlyWorkspacePath(workspacePath);
+ const res = await modlyFetch(origin, `/export/glb?path=${encodeURIComponent(path)}`, { signal });
+ const buf = await res.arrayBuffer();
+ if (buf.byteLength < 12 || new DataView(buf).getUint32(0, true) !== GLB_MAGIC) {
+ throw new ModlyError('NOT_GLB', `Modly's output "${path.split('/').pop()}" is not a GLB mesh, so it cannot open in this viewer.`);
+ }
+ const filename = path.split('/').pop() || 'modly.glb';
+ return { blob: new Blob([buf], { type: 'model/gltf-binary' }), filename: /\.glb$/i.test(filename) ? filename : `${filename}.glb` };
+}
+
+/**
+ * Run an image-to-3D generation on the user's own GPU through Modly.
+ *
+ * Posts to /workflow-runs/from-image (falling back to the legacy
+ * /generate/from-image on Modly builds without it), polls the run every
+ * `pollIntervalMs`, reports `onProgress(percent, stepLabel, state)` from Modly's
+ * own progress, step text and run status ('pending' | 'running' | 'done'),
+ * then downloads the result via /export/glb.
+ * Aborting `signal` calls Modly's cancel endpoint before rejecting with
+ * ModlyError CANCELLED.
+ *
+ * @param {string} origin a connected Modly origin (from detectModly)
+ * @param {object} opts
+ * @param {Blob|File} opts.image
+ * @param {string} opts.modelId
+ * @param {object} [opts.params] model params (see defaultModlyParams)
+ * @param {string} [opts.collection] Modly workspace folder to file the output in
+ * @param {(pct:number, step:string, state:string)=>void} [opts.onProgress]
+ * @param {(info:{runId:string, api:string})=>void} [opts.onStarted]
+ * @param {AbortSignal} [opts.signal]
+ * @returns {Promise<{blob:Blob, filename:string, jobId:string, modelId:string, workspacePath:string, api:string}>}
+ */
+export async function generateWithModly(
+ origin,
+ { image, modelId, params = {}, collection, onProgress, onStarted, signal, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, timeoutMs = DEFAULT_RUN_TIMEOUT_MS } = {},
+) {
+ if (!origin) throw new ModlyError('BAD_INPUT', 'Connect to Modly first.');
+ if (!modelId) throw new ModlyError('BAD_INPUT', 'Pick a Modly model.');
+ if (signal?.aborted) throw cancelledError(signal.reason);
+ const report = (pct, step, state) => {
+ try {
+ onProgress?.(Math.max(0, Math.min(100, Math.round(Number(pct) || 0))), step || '', state);
+ } catch {
+ // A throwing progress callback must not break the run.
+ }
+ };
+
+ report(0, 'Sending image to Modly', 'pending');
+ const run = await startRun(origin, { image, modelId, params, collection, signal });
+ try {
+ onStarted?.({ runId: run.id, api: run.api });
+ } catch {
+ // Observer only.
+ }
+
+ let cancelSent = false;
+ const sendCancel = () => {
+ if (cancelSent) return;
+ cancelSent = true;
+ cancelModlyRun(origin, run.id, { api: run.api });
+ };
+ signal?.addEventListener('abort', sendCancel, { once: true });
+
+ try {
+ const deadline = Date.now() + timeoutMs;
+ let status;
+ for (;;) {
+ try {
+ status = await modlyJson(origin, statusPath(run), { signal, timeoutMs: 15000 });
+ } catch (err) {
+ if (err.code === 'NOT_FOUND') {
+ throw new ModlyError('RUN_LOST', 'Modly no longer knows this generation. It may have restarted. Try again.', { status: 404 });
+ }
+ // One slow status answer is not a failure; keep polling until the deadline.
+ if (err.code !== 'TIMEOUT') throw err;
+ }
+ if (status) {
+ const s = status.status;
+ if (s === 'done') break;
+ if (s === 'error') {
+ throw new ModlyError('GENERATION_FAILED', summarizeModlyError(status.error), { detail: String(status.error || '') });
+ }
+ if (s === 'cancelled') throw cancelledError();
+ report(status.progress, status.step, s);
+ }
+ if (Date.now() >= deadline) {
+ sendCancel();
+ throw new ModlyError('TIMEOUT', `Modly did not finish within ${Math.round(timeoutMs / 60000)} minutes.`);
+ }
+ await sleep(pollIntervalMs, signal);
+ }
+
+ const workspacePath = modlyRunWorkspacePath(status);
+ report(100, 'Fetching the mesh from Modly', 'done');
+ const { blob, filename } = await downloadModlyGlb(origin, workspacePath, { signal });
+ return { blob, filename, jobId: run.id, modelId, workspacePath, api: run.api };
+ } catch (err) {
+ if (signal?.aborted) {
+ sendCancel();
+ throw err instanceof ModlyError && err.code === 'CANCELLED' ? err : cancelledError(err);
+ }
+ throw err;
+ } finally {
+ signal?.removeEventListener('abort', sendCancel);
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Mesh operations
+// ---------------------------------------------------------------------------
+
+/** GET /optimize/ops: Modly's mesh operations with their param schemas. */
+export async function listModlyMeshOps(origin, { signal } = {}) {
+ const ops = await modlyJson(origin, '/optimize/ops', { signal });
+ return (Array.isArray(ops) ? ops : [])
+ .filter((o) => o && o.id)
+ .map((o) => ({
+ id: String(o.id),
+ label: String(o.label || o.id),
+ category: String(o.category || ''),
+ destructive: !!o.destructive,
+ undoable: !!o.undoable,
+ paramsSchema: (Array.isArray(o.params_schema) ? o.params_schema : []).map(normalizeParam).filter(Boolean),
+ }));
+}
+
+/**
+ * Run one of Modly's mesh operations (POST /optimize/op/{op}) and fetch the result.
+ *
+ * Limit: Modly's mesh ops read and write files inside Modly's own workspace,
+ * and Modly exposes no endpoint that accepts mesh bytes over HTTP (its import
+ * route takes an absolute path on the user's disk). So `glb` must name a mesh
+ * already in that workspace: a workspace-relative path string, or a result
+ * object from generateWithModly / modlyMeshOp (anything with `workspacePath`).
+ * Passing a Blob rejects with ModlyError UPLOAD_UNSUPPORTED; run browser-side
+ * mesh processing on a Blob instead.
+ *
+ * @param {string} origin
+ * @param {object} opts
+ * @param {string|{workspacePath:string}|Blob} opts.glb
+ * @param {string} opts.op an id from listModlyMeshOps, e.g. 'decimate'
+ * @param {object} [opts.params]
+ * @param {AbortSignal} [opts.signal]
+ * @returns {Promise<{blob:Blob, filename:string, workspacePath:string, details:object}>}
+ */
+export async function modlyMeshOp(origin, { glb, op, params = {}, signal } = {}) {
+ if (!origin) throw new ModlyError('BAD_INPUT', 'Connect to Modly first.');
+ if (!op) throw new ModlyError('BAD_INPUT', 'Name the mesh operation to run.');
+ if (glb instanceof Blob) {
+ throw new ModlyError(
+ 'UPLOAD_UNSUPPORTED',
+ 'Modly can only process meshes in its own workspace, and it has no upload endpoint. Use a mesh Modly generated.',
+ );
+ }
+ const inputPath = validateModlyWorkspacePath(typeof glb === 'string' ? glb : glb?.workspacePath);
+ const body = await modlyJson(origin, `/optimize/op/${encodeURIComponent(op)}`, { ...postJson({ path: inputPath, params }), signal });
+ // An output Modly wrote outside its workspace comes back as an absolute
+ // path with no url; it cannot be exported over HTTP.
+ if (!body?.url) throw new ModlyError('BAD_PATH', 'Modly wrote this result outside its workspace, so it cannot be downloaded.');
+ const workspacePath = validateModlyWorkspacePath(body.path);
+ const { path: _p, url: _u, ...details } = body;
+ const { blob, filename } = await downloadModlyGlb(origin, workspacePath, { signal });
+ return { blob, filename, workspacePath, details };
+}
diff --git a/tests/modly-local.test.js b/tests/modly-local.test.js
new file mode 100644
index 000000000..ef5fa509a
--- /dev/null
+++ b/tests/modly-local.test.js
@@ -0,0 +1,446 @@
+// Contract tests for src/modly-local.js against an in-process stub of Modly's
+// HTTP API. Every route, status code, and body shape the stub serves is taken
+// from Modly's FastAPI routers (api/routers/{model,workflow_runs,generation,
+// export,optimize}.py, https://github.com/lightningpixel/modly, MIT).
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+ MODLY_ORIGINS,
+ MODLY_DEFAULT_ORIGINS,
+ ModlyError,
+ detectModly,
+ probeModly,
+ listModlyModels,
+ generateWithModly,
+ modlyMeshOp,
+ listModlyMeshOps,
+ normalizeModlyModel,
+ defaultModlyParams,
+ validateModlyWorkspacePath,
+ modlyRunWorkspacePath,
+ summarizeModlyError,
+ setModlyOriginOverride,
+ getModlyOriginOverride,
+ normalizeModlyOrigin,
+ cancelModlyRun,
+} from '../src/modly-local.js';
+
+const ORIGIN = 'http://127.0.0.1:8765';
+
+// A minimal valid GLB header: magic "glTF", version 2, total length 12.
+function glbBytes() {
+ const buf = new ArrayBuffer(12);
+ const v = new DataView(buf);
+ v.setUint32(0, 0x46546c67, true);
+ v.setUint32(4, 2, true);
+ v.setUint32(8, 12, true);
+ return new Uint8Array(buf);
+}
+
+const PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0]);
+
+function json(body, status = 200) {
+ return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+
+// In-memory Modly. `script` is the sequence of statuses a run walks through,
+// one per status poll, mirroring JobStatus transitions in _run_generation.
+function makeModly({
+ models = [
+ { id: 'sf3d', name: 'Stable Fast 3D', description: 'fast', version: '1.0', vram_gb: 6, hf_repo: 'x/y', tags: ['fast'], downloaded: true, loaded: false, active: true },
+ { id: 'hunyuan3d', name: 'Hunyuan3D 2', downloaded: false, loaded: false, active: false },
+ ],
+ params = {
+ sf3d: [
+ { id: 'remesh', label: 'Remesh', type: 'select', default: 'quad', options: [{ value: 'quad', label: 'Quad' }, { value: 'triangle', label: 'Triangle' }] },
+ { id: 'texture_resolution', label: 'Texture size', type: 'int', default: 1024, min: 512, max: 2048, step: 512 },
+ ],
+ },
+ script = [
+ { status: 'pending', progress: 0, step: 'Waiting for the previous generation…' },
+ { status: 'running', progress: 40, step: 'Generating mesh' },
+ { status: 'done', progress: 100 },
+ ],
+ outputPath = 'Default/sf3d_0001.glb',
+ workflowRuns = true,
+ exportBytes = glbBytes(),
+} = {}) {
+ const calls = [];
+ const runs = new Map();
+ let seq = 0;
+
+ function statusFor(id) {
+ const run = runs.get(id);
+ if (!run) return null;
+ if (run.cancelled) return { status: 'cancelled', progress: run.last?.progress ?? 0, step: null, output_url: null, error: null };
+ const step = script[Math.min(run.polls, script.length - 1)];
+ run.polls += 1;
+ run.last = step;
+ const done = step.status === 'done';
+ return {
+ status: step.status,
+ progress: step.progress ?? 0,
+ step: step.step ?? null,
+ output_url: done ? `/workspace/${outputPath}` : null,
+ error: step.error ?? null,
+ };
+ }
+
+ async function handle(url, init = {}) {
+ const u = new URL(url);
+ const method = (init.method || 'GET').toUpperCase();
+ calls.push({ method, path: u.pathname, search: u.search, init });
+ const p = u.pathname;
+
+ if (method === 'GET' && p === '/health') return json({ status: 'ok' });
+ if (method === 'GET' && p === '/model/all') return json(models);
+ if (method === 'GET' && p === '/model/params') {
+ const id = u.searchParams.get('model_id');
+ if (!models.some((m) => m.id === id)) return json({ detail: `Unknown model ID: ${id}` }, 404);
+ return json(params[id] || []);
+ }
+
+ const isRunCreate = (workflowRuns && p === '/workflow-runs/from-image') || p === '/generate/from-image';
+ if (method === 'POST' && isRunCreate) {
+ const fd = init.body;
+ const image = fd.get('image');
+ if (!image || !String(image.type).startsWith('image/')) return json({ detail: 'File must be an image' }, 400);
+ const modelId = fd.get('model_id') || 'sf3d';
+ if (!models.some((m) => m.id === modelId)) return json({ detail: `Unknown model ID: ${modelId}` }, 400);
+ const id = `run-${++seq}`;
+ runs.set(id, { polls: 0, cancelled: false, modelId, params: JSON.parse(fd.get('params') || '{}'), image });
+ return json(p.startsWith('/workflow-runs') ? { run_id: id, status: 'pending' } : { job_id: id });
+ }
+
+ let m = workflowRuns && /^\/workflow-runs\/([^/]+)$/.exec(p);
+ if (method === 'GET' && m) {
+ const s = statusFor(m[1]);
+ if (!s) return json({ detail: `Run ${m[1]} not found` }, 404);
+ const sc = s.status === 'done' && s.output_url ? { workspace_path: s.output_url.replace('/workspace/', '') } : null;
+ return json({ run_id: m[1], ...s, scene_candidate: sc });
+ }
+ m = /^\/generate\/status\/([^/]+)$/.exec(p);
+ if (method === 'GET' && m) {
+ const s = statusFor(m[1]);
+ if (!s) return json({ detail: `Job ${m[1]} not found` }, 404);
+ return json({ job_id: m[1], ...s });
+ }
+ m = (workflowRuns && /^\/workflow-runs\/([^/]+)\/cancel$/.exec(p)) || /^\/generate\/cancel\/([^/]+)$/.exec(p);
+ if (method === 'POST' && m) {
+ const run = runs.get(m[1]);
+ if (!run) return json({ detail: `Job ${m[1]} not found` }, 404);
+ run.cancelled = true;
+ return json({ cancelled: true });
+ }
+
+ if (method === 'GET' && p === '/export/glb') {
+ const path = u.searchParams.get('path');
+ if (!path) return json({ detail: [{ loc: ['query', 'path'], msg: 'Field required', type: 'missing' }] }, 422);
+ return new Response(exportBytes, { status: 200, headers: { 'content-type': 'model/gltf-binary' } });
+ }
+
+ if (method === 'GET' && p === '/optimize/ops') {
+ return json([
+ { id: 'decimate', label: 'Decimate', params_schema: [{ id: 'target_faces', label: 'Target faces', type: 'int', default: 10000, min: 100 }], destructive: true, undoable: true, category: 'topology' },
+ ]);
+ }
+ m = /^\/optimize\/op\/([^/]+)$/.exec(p);
+ if (method === 'POST' && m) {
+ const body = JSON.parse(init.body);
+ if (m[1] !== 'decimate') return json({ detail: `Unknown mesh operation: ${m[1]}` }, 404);
+ const out = body.path.replace(/\.glb$/, '_dec.glb');
+ return json({ path: out, url: `/workspace/${out}`, face_count: body.params.target_faces ?? 10000 });
+ }
+
+ return json({ detail: 'Not Found' }, 404);
+ }
+
+ return { calls, runs, handle };
+}
+
+let modly;
+
+function installFetch(stub, { refuse = [] } = {}) {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async (url, init) => {
+ if (init?.signal?.aborted) throw new DOMException('Aborted', 'AbortError');
+ if (refuse.some((o) => String(url).startsWith(o))) throw new TypeError('Failed to fetch');
+ return stub.handle(String(url), init);
+ }),
+ );
+}
+
+beforeEach(() => {
+ modly = makeModly();
+ installFetch(modly);
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ setModlyOriginOverride('');
+});
+
+describe('model normalization', () => {
+ it('defaults input/output the way Modly\'s registry does and keeps ParamSchema field names', () => {
+ const m = normalizeModlyModel(
+ { id: 'x', downloaded: 1, vram_gb: 8, tags: ['a'] },
+ [{ id: 'steps', label: 'Steps', type: 'int', default: 30, min: 1, max: 100, show_if: { param: 'mode', equals: 'hq' } }, { label: 'no id' }],
+ );
+ expect(m).toMatchObject({ id: 'x', name: 'x', downloaded: true, input: 'image', output: 'mesh', vramGb: 8, tags: ['a'] });
+ expect(m.paramsSchema).toEqual([{ id: 'steps', label: 'Steps', type: 'int', default: 30, min: 1, max: 100, show_if: { param: 'mode', equals: 'hq' } }]);
+ });
+
+ it('listModlyModels reads /model/all and attaches each model\'s /model/params', async () => {
+ const models = await listModlyModels(ORIGIN);
+ expect(models.map((m) => [m.id, m.downloaded])).toEqual([
+ ['sf3d', true],
+ ['hunyuan3d', false],
+ ]);
+ expect(models[0].paramsSchema.map((p) => p.id)).toEqual(['remesh', 'texture_resolution']);
+ expect(models[0].paramsSchema[0].options).toEqual([
+ { value: 'quad', label: 'Quad' },
+ { value: 'triangle', label: 'Triangle' },
+ ]);
+ expect(models[1].paramsSchema).toEqual([]);
+ expect(defaultModlyParams(models[0].paramsSchema)).toEqual({ remesh: 'quad', texture_resolution: 1024 });
+ });
+
+ it('treats an empty Modly (no extensions installed) as zero models, not an error', async () => {
+ modly = makeModly({ models: [] });
+ installFetch(modly);
+ expect(await listModlyModels(ORIGIN)).toEqual([]);
+ });
+});
+
+describe('detection', () => {
+ it('resolves { origin, models } from the first origin that answers /health', async () => {
+ installFetch(modly, { refuse: ['http://127.0.0.1'] });
+ const found = await detectModly({ timeoutMs: 500 });
+ expect(found.origin).toBe('http://localhost:8765');
+ expect(found.models).toHaveLength(2);
+ });
+
+ it('resolves null, never throws, when nothing is listening', async () => {
+ installFetch(modly, { refuse: ['http://'] });
+ await expect(detectModly({ timeoutMs: 200 })).resolves.toBeNull();
+ });
+
+ it('rejects a server that answers /health but is not Modly', async () => {
+ vi.stubGlobal('fetch', vi.fn(async () => json({ ok: true })));
+ await expect(detectModly({ timeoutMs: 200 })).resolves.toBeNull();
+ });
+
+ it('reports blocked when Chrome\'s Local Network Access permission is denied', async () => {
+ installFetch(modly, { refuse: ['http://'] });
+ vi.stubGlobal('navigator', {
+ userAgent: 'Mozilla/5.0 Chrome/142.0',
+ permissions: {
+ query: vi.fn(async ({ name }) => {
+ if (name !== 'local-network-access') throw new TypeError('bad permission');
+ return { state: 'denied' };
+ }),
+ },
+ });
+ const probe = await probeModly({ timeoutMs: 200 });
+ expect(probe).toMatchObject({ status: 'blocked', reason: 'lna-denied', origin: null });
+ });
+
+ it('reports blocked mixed content for Safari on an https page', async () => {
+ installFetch(modly, { refuse: ['http://'] });
+ vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Macintosh) Version/18.0 Safari/605.1.15' });
+ vi.stubGlobal('location', { protocol: 'https:' });
+ const probe = await probeModly({ timeoutMs: 200 });
+ expect(probe).toMatchObject({ status: 'blocked', reason: 'mixed-content' });
+ });
+
+ it('reports not-running when nothing blocks and nothing answers', async () => {
+ installFetch(modly, { refuse: ['http://'] });
+ vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 Firefox/140.0' });
+ vi.stubGlobal('location', { protocol: 'https:' });
+ const probe = await probeModly({ timeoutMs: 200 });
+ expect(probe.status).toBe('not-running');
+ });
+});
+
+describe('origin override', () => {
+ it('normalizes typed addresses and puts the override first in MODLY_ORIGINS', () => {
+ const store = new Map();
+ vi.stubGlobal('localStorage', {
+ getItem: (k) => store.get(k) ?? null,
+ setItem: (k, v) => store.set(k, String(v)),
+ removeItem: (k) => store.delete(k),
+ });
+ expect(normalizeModlyOrigin('localhost:9000/')).toBe('http://localhost:9000');
+ expect(() => normalizeModlyOrigin('ftp://x')).toThrow(ModlyError);
+ const ref = MODLY_ORIGINS;
+ setModlyOriginOverride('192.168.1.20:8765');
+ expect(ref).toEqual(['http://192.168.1.20:8765', ...MODLY_DEFAULT_ORIGINS]);
+ expect(getModlyOriginOverride()).toBe('http://192.168.1.20:8765');
+ setModlyOriginOverride('');
+ expect(ref).toEqual([...MODLY_DEFAULT_ORIGINS]);
+ });
+});
+
+describe('generateWithModly', () => {
+ it('posts the multipart contract, polls with progress, and returns a GLB blob', async () => {
+ const progress = [];
+ const res = await generateWithModly(ORIGIN, {
+ image: new File([PNG], 'chair.png', { type: 'image/png' }),
+ modelId: 'sf3d',
+ params: { remesh: 'triangle' },
+ onProgress: (pct, step) => progress.push([pct, step]),
+ pollIntervalMs: 1,
+ });
+ expect(res.blob.type).toBe('model/gltf-binary');
+ expect(res.blob.size).toBe(12);
+ expect(res).toMatchObject({ filename: 'sf3d_0001.glb', jobId: 'run-1', modelId: 'sf3d', workspacePath: 'Default/sf3d_0001.glb', api: 'workflow-runs' });
+ expect(modly.runs.get('run-1').params).toEqual({ remesh: 'triangle' });
+ expect(modly.runs.get('run-1').image.type).toBe('image/png');
+ expect(progress).toEqual([
+ [0, 'Sending image to Modly'],
+ [0, 'Waiting for the previous generation…'],
+ [40, 'Generating mesh'],
+ [100, 'Fetching the mesh from Modly'],
+ ]);
+ const exportCall = modly.calls.find((c) => c.path === '/export/glb');
+ expect(new URLSearchParams(exportCall.search).get('path')).toBe('Default/sf3d_0001.glb');
+ });
+
+ it('sniffs an untyped image blob so Modly does not reject it as a non-image', async () => {
+ const res = await generateWithModly(ORIGIN, { image: new Blob([PNG]), modelId: 'sf3d', pollIntervalMs: 1 });
+ expect(res.jobId).toBe('run-1');
+ expect(modly.runs.get('run-1').image.type).toBe('image/png');
+ });
+
+ it('refuses an input that is not an image before calling Modly', async () => {
+ await expect(generateWithModly(ORIGIN, { image: new Blob(['hello']), modelId: 'sf3d' })).rejects.toMatchObject({ code: 'BAD_INPUT' });
+ expect(modly.calls).toHaveLength(0);
+ });
+
+ it('falls back to the legacy /generate routes on a Modly without /workflow-runs', async () => {
+ modly = makeModly({ workflowRuns: false });
+ installFetch(modly);
+ const res = await generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 });
+ expect(res.api).toBe('legacy');
+ expect(modly.calls.some((c) => c.path === '/generate/status/run-1')).toBe(true);
+ });
+
+ it('maps a 400 Unknown model to UNKNOWN_MODEL with Modly\'s text', async () => {
+ const err = await generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'nope' }).catch((e) => e);
+ expect(err).toBeInstanceOf(ModlyError);
+ expect(err).toMatchObject({ code: 'UNKNOWN_MODEL', status: 400, message: 'Unknown model ID: nope' });
+ });
+
+ it('maps a failed run to GENERATION_FAILED with the exception line and keeps the traceback', async () => {
+ const tb = 'Traceback (most recent call last):\n File "gen.py", line 9, in generate\n run()\ntorch.OutOfMemoryError: CUDA out of memory. Tried to allocate 2.00 GiB';
+ modly = makeModly({ script: [{ status: 'running', progress: 10, step: 'Loading model' }, { status: 'error', progress: 10, error: tb }] });
+ installFetch(modly);
+ const err = await generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }).catch((e) => e);
+ expect(err).toMatchObject({ code: 'GENERATION_FAILED', message: 'CUDA out of memory. Tried to allocate 2.00 GiB', detail: tb });
+ });
+
+ it('maps a run cancelled inside Modly to CANCELLED', async () => {
+ modly = makeModly({ script: [{ status: 'cancelled', progress: 5 }] });
+ installFetch(modly);
+ await expect(
+ generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
+ ).rejects.toMatchObject({ code: 'CANCELLED' });
+ });
+
+ it('maps a run Modly forgot (404 mid-poll) to RUN_LOST', async () => {
+ installFetch(modly);
+ const real = globalThis.fetch;
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async (url, init) => (/\/workflow-runs\/run-1$/.test(String(url)) ? json({ detail: 'Run run-1 not found' }, 404) : real(url, init))),
+ );
+ await expect(
+ generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
+ ).rejects.toMatchObject({ code: 'RUN_LOST' });
+ });
+
+ it('aborting the signal mid-run calls Modly\'s cancel endpoint and rejects CANCELLED', async () => {
+ modly = makeModly({ script: [{ status: 'running', progress: 20, step: 'Generating mesh' }] });
+ installFetch(modly);
+ const ctrl = new AbortController();
+ const promise = generateWithModly(ORIGIN, {
+ image: new File([PNG], 'a.png', { type: 'image/png' }),
+ modelId: 'sf3d',
+ signal: ctrl.signal,
+ pollIntervalMs: 50,
+ onProgress: (pct) => {
+ if (pct === 20) ctrl.abort();
+ },
+ });
+ await expect(promise).rejects.toMatchObject({ code: 'CANCELLED' });
+ await vi.waitFor(() => expect(modly.calls.some((c) => c.method === 'POST' && c.path === '/workflow-runs/run-1/cancel')).toBe(true));
+ expect(modly.runs.get('run-1').cancelled).toBe(true);
+ });
+
+ it('rejects an output that is not a binary glTF with NOT_GLB', async () => {
+ modly = makeModly({ exportBytes: new TextEncoder().encode('{"scene":"json, not a glb"}') });
+ installFetch(modly);
+ await expect(
+ generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
+ ).rejects.toMatchObject({ code: 'NOT_GLB' });
+ });
+
+ it('refuses a reported output path that escapes the workspace', async () => {
+ modly = makeModly({ outputPath: '../../etc/passwd' });
+ installFetch(modly);
+ await expect(
+ generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
+ ).rejects.toMatchObject({ code: 'BAD_PATH' });
+ expect(modly.calls.some((c) => c.path === '/export/glb')).toBe(false);
+ });
+
+ it('cancelModlyRun resolves false instead of throwing when Modly is gone', async () => {
+ installFetch(modly, { refuse: ['http://'] });
+ await expect(cancelModlyRun(ORIGIN, 'run-9')).resolves.toBe(false);
+ });
+});
+
+describe('workspace paths and error text', () => {
+ it('validates paths with the same rules as Modly\'s CLI', () => {
+ expect(validateModlyWorkspacePath('Default/a.glb')).toBe('Default/a.glb');
+ for (const bad of ['', '/etc/x.glb', '\\x.glb', 'a/../b.glb', 'C:/x.glb', 'Default/D:x.glb', 'http://evil/x.glb', 'file:x']) {
+ expect(() => validateModlyWorkspacePath(bad)).toThrow(ModlyError);
+ }
+ });
+
+ it('reads scene_candidate first, then strips /workspace/ from output_url', () => {
+ expect(modlyRunWorkspacePath({ scene_candidate: { workspace_path: 'A/b.glb' }, output_url: '/workspace/X/y.glb' })).toBe('A/b.glb');
+ expect(modlyRunWorkspacePath({ output_url: '/workspace/My%20Set/y.glb' })).toBe('My Set/y.glb');
+ expect(() => modlyRunWorkspacePath({})).toThrow(ModlyError);
+ });
+
+ it('summarizes a traceback to its final exception message', () => {
+ expect(summarizeModlyError('Traceback...\nValueError: bad image')).toBe('bad image');
+ expect(summarizeModlyError('')).toMatch(/without details/);
+ });
+});
+
+describe('modlyMeshOp', () => {
+ it('refuses a Blob: Modly has no mesh upload endpoint', async () => {
+ await expect(modlyMeshOp(ORIGIN, { glb: new Blob([glbBytes()]), op: 'decimate' })).rejects.toMatchObject({ code: 'UPLOAD_UNSUPPORTED' });
+ expect(modly.calls).toHaveLength(0);
+ });
+
+ it('runs an op on a workspace path and downloads the result', async () => {
+ const res = await modlyMeshOp(ORIGIN, { glb: { workspacePath: 'Default/sf3d_0001.glb' }, op: 'decimate', params: { target_faces: 5000 } });
+ expect(res).toMatchObject({ workspacePath: 'Default/sf3d_0001_dec.glb', filename: 'sf3d_0001_dec.glb', details: { face_count: 5000 } });
+ expect(res.blob.type).toBe('model/gltf-binary');
+ const post = modly.calls.find((c) => c.path === '/optimize/op/decimate');
+ expect(JSON.parse(post.init.body)).toEqual({ path: 'Default/sf3d_0001.glb', params: { target_faces: 5000 } });
+ });
+
+ it('maps an unknown op to NOT_FOUND with Modly\'s text', async () => {
+ await expect(modlyMeshOp(ORIGIN, { glb: 'Default/a.glb', op: 'explode' })).rejects.toMatchObject({ code: 'NOT_FOUND', message: 'Unknown mesh operation: explode' });
+ });
+
+ it('lists ops with normalized param schemas', async () => {
+ const ops = await listModlyMeshOps(ORIGIN);
+ expect(ops[0]).toMatchObject({ id: 'decimate', destructive: true, category: 'topology' });
+ expect(ops[0].paramsSchema[0]).toMatchObject({ id: 'target_faces', default: 10000 });
+ });
+});