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-ui): Match my photo engine, per-engine image slot cap

nirholasd85ce1936c4c
diff --git a/pages/forge.html b/pages/forge.html
index 78a22e360..7882d2852 100644
--- a/pages/forge.html
+++ b/pages/forge.html
@@ -1026,6 +1026,17 @@
.view-slot.dragging {
opacity: 0.4;
}
+ /* Past the selected engine's image cap (Pixal3D: 4), Match my photo
+ never reads a 5th/6th view, so the slot is visibly inert rather than
+ silently ignored. src/forge.js toggles data-disabled per engine. */
+ .view-slot[data-disabled='true'] {
+ opacity: 0.35;
+ cursor: not-allowed;
+ border-style: dotted;
+ }
+ .view-slot[data-disabled='true']:hover {
+ border-color: var(--stroke-strong);
+ }
/* Inner regions toggled by the slot's data-state. */
.vs-empty,
.vs-uploading,
@@ -1144,6 +1155,31 @@
text-align: center;
}
+ /* Match my photo (Pixal3D): shown only while that engine is selected
+ (src/forge.js updatePixal3dPanel). */
+ .pixal3d-panel {
+ margin-top: var(--space-sm);
+ padding: var(--space-sm);
+ border: 1px solid var(--stroke);
+ border-radius: var(--radius-md);
+ background: var(--surface-1);
+ }
+ .pixal3d-panel-title {
+ margin: 0 0 var(--space-xs);
+ font-size: var(--text-xs);
+ color: var(--ink-dim);
+ }
+ .pixal3d-fill-row {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ font-size: var(--text-xs);
+ cursor: pointer;
+ }
+ .pixal3d-fill-row input:disabled {
+ cursor: not-allowed;
+ }
+
/* Live multi-view counter: turns the anonymous empty boxes into a
legible "0 of 6" progress with pips, and teaches that more views ⇒
sharper mesh. Updated by src/forge.js as slots fill. */
@@ -3894,6 +3930,20 @@
(<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>
+ <!-- Match my photo (Pixal3D): only shown while that engine is selected.
+ Front/Back/Left/Right are the same first four slots every engine
+ uses, so no separate upload UI, just the cap (handled in JS via
+ activeMaxImages()) and this single opt-in for a one-photo job. -->
+ <section class="pixal3d-panel is-hidden" id="pixal3d-panel" aria-labelledby="pixal3d-panel-title">
+ <p class="pixal3d-panel-title" id="pixal3d-panel-title">
+ <strong>Match my photo</strong> fuses your 1-4 photos pixel-aligned instead of
+ guessing the unseen sides. Label them Front/Back/Left/Right by drop order.
+ </p>
+ <label class="pixal3d-fill-row" for="pixal3d-fill-sides">
+ <input type="checkbox" id="pixal3d-fill-sides" />
+ Only one photo? Let the worker synthesize the other three sides.
+ </label>
+ </section>
<!-- 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">
diff --git a/src/forge.js b/src/forge.js
index 43403d300..a8cdc1446 100644
--- a/src/forge.js
+++ b/src/forge.js
@@ -128,6 +128,8 @@ const els = {
viewsCounter: document.getElementById('views-counter'),
viewsCounterText: document.getElementById('views-counter-text'),
viewsPips: document.getElementById('views-pips'),
+ pixal3dPanel: document.getElementById('pixal3d-panel'),
+ pixal3dFillSides: document.getElementById('pixal3d-fill-sides'),
sketchReqTag: document.getElementById('sketch-req-tag'),
generateAnyway: document.getElementById('generate-anyway'),
refineLocally: document.getElementById('refine-locally'),
@@ -291,6 +293,10 @@ const ENGINE_LABELS = {
replicate_byok: 'Replicate',
hunyuan3d: 'Hunyuan3D',
triposg: 'TripoSG',
+ // Pixal3D fuses every reference photo pixel-aligned instead of hallucinating
+ // unseen sides from one view: "Match my photo" is what that buys the user,
+ // not the vendor name.
+ pixal3d: 'Match my photo',
};
// Where to mint a key per BYOK provider, keyed by the backend's `byok` name.
@@ -314,6 +320,32 @@ const slots = VIEW_LABELS.map(() => ({
errorMsg: '',
}));
+// Most engines fuse up to MAX_VIEWS (6). Pixal3D's "Match my photo" lane caps
+// at 4 (its worker only knows front/back/left/right, slots 0-3, the same
+// four labels this grid already uses first) and the catalog is the only
+// source of that number, never a hardcoded second constant here.
+function activeMaxImages() {
+ const b = catalog?.backends?.find((x) => x.id === selectedEngine.backend);
+ const declared = Number(b?.max_images) > 0 ? Number(b.max_images) : MAX_VIEWS;
+ // Never exceed the slot grid itself: a backend can only tighten the cap,
+ // not widen it past the array nextFreeAfter/firstFreeSlot scan.
+ return Math.min(declared, MAX_VIEWS);
+}
+
+function slotEnabled(i) {
+ return i < activeMaxImages();
+}
+
+// Drop every slot beyond the active engine's cap so a switch from a 6-view
+// engine to Pixal3D never silently ships a 400 for photos the user can still
+// see sitting in the grid.
+function pruneSlotsOverCap() {
+ const cap = activeMaxImages();
+ for (let i = cap; i < slots.length; i++) {
+ if (slots[i].state !== 'empty') clearSlot(i);
+ }
+}
+
// File picker target: the slot index the picker was opened for, or null to fill
// from the first free slot.
let pickerTarget = null;
@@ -942,6 +974,11 @@ function selectEngine(btn, silent) {
// re-evaluate the lock whenever the engine changes under High. Reuses the cached
// access verdict — no extra round-trip, no loading flash.
if (selectedTier === 'high') reflectHighAccess('high', { silent: true });
+ // A switch to a tighter-capped engine (Pixal3D: 4) drops any photos sitting
+ // in the slots it can't use, then every slot repaints against the new cap:
+ // enabled/disabled state, the pips denominator, and the fill-sides toggle.
+ pruneSlotsOverCap();
+ for (let i = 0; i < slots.length; i++) renderSlot(i);
}
// Show the key field only for BYOK engines, with provider-specific hint + link.
@@ -1275,14 +1312,15 @@ function buildSlots() {
openPicker(i);
});
- // Click empty/error → browse for this slot.
+ // Click empty/error → browse for this slot (never a slot past the active
+ // engine's cap, Pixal3D only reads the first four).
slot.addEventListener('click', () => {
- if (slots[i].state === 'empty' || slots[i].state === 'error') openPicker(i);
+ if (slotEnabled(i) && (slots[i].state === 'empty' || slots[i].state === 'error')) openPicker(i);
});
slot.addEventListener('keydown', (e) => {
if (e.key === 'Enter' || e.key === ' ') {
e.preventDefault();
- if (slots[i].state === 'empty' || slots[i].state === 'error') openPicker(i);
+ if (slotEnabled(i) && (slots[i].state === 'empty' || slots[i].state === 'error')) openPicker(i);
}
});
@@ -1310,6 +1348,7 @@ function buildSlots() {
slot.addEventListener('drop', (e) => {
e.preventDefault();
slot.classList.remove('drop-target');
+ if (!slotEnabled(i)) return;
const from = e.dataTransfer.getData('application/x-forge-slot');
if (from !== '') {
swapSlots(Number(from), i);
@@ -1338,29 +1377,39 @@ function buildViewsPips() {
}
// Live "N of 6 views" readout + pips. Teaches that more views sharpen the mesh,
-// so users don't stop at a single photo thinking it's enough.
+// so users don't stop at a single photo thinking it's enough. The denominator
+// tracks the selected engine's own cap (4 for Pixal3D, 6 otherwise); the pips
+// grid is built once at MAX_VIEWS size, so pips past the active cap just hide.
function updateViewsCounter() {
if (!els.viewsCounter || !els.viewsCounterText) return;
+ const cap = activeMaxImages();
const n = slots.filter((s) => s.state === 'uploaded').length;
const pips = els.viewsPips ? els.viewsPips.children : [];
- for (let i = 0; i < pips.length; i++) pips[i].dataset.filled = String(i < n);
+ for (let i = 0; i < pips.length; i++) {
+ pips[i].dataset.filled = String(i < n);
+ pips[i].style.display = i < cap ? '' : 'none';
+ }
let tail;
if (n === 0) tail = ' — add a photo to begin';
- else if (n < MAX_VIEWS) tail = ' · <span class="vc-quality">more views = sharper</span>';
+ else if (n < cap) tail = ' · <span class="vc-quality">more views = sharper</span>';
else tail = ' · <span class="vc-quality">full coverage</span>';
- els.viewsCounterText.innerHTML = `<strong>${n}</strong> of ${MAX_VIEWS} views${tail}`;
+ els.viewsCounterText.innerHTML = `<strong>${n}</strong> of ${cap} views${tail}`;
}
function renderSlot(i) {
const el = slotEl(i);
if (!el) return;
const s = slots[i];
+ const enabled = slotEnabled(i);
el.dataset.state = s.state;
+ el.dataset.disabled = String(!enabled);
+ el.tabIndex = enabled ? 0 : -1;
el.draggable = s.state === 'uploaded';
// Slot changes flip the input mode (prompt-only ↔ photo), which changes
// which engines may serve — keep the selector honest in the same frame.
updateEngineAvailability();
updateViewsCounter();
+ updatePixal3dPanel();
const img = el.querySelector('.vs-thumb');
if (s.objectUrl) {
@@ -1373,7 +1422,9 @@ function renderSlot(i) {
el.querySelector('.vs-error-msg').textContent = s.errorMsg || 'Upload failed';
const labels = {
- empty: `${VIEW_LABELS[i]} view, empty — add a photo`,
+ empty: enabled
+ ? `${VIEW_LABELS[i]} view, empty, add a photo`
+ : `${VIEW_LABELS[i]} view, not used by ${ENGINE_LABELS.pixal3d}`,
uploading: `${VIEW_LABELS[i]} view, uploading`,
uploaded: `${VIEW_LABELS[i]} view, uploaded — drag to reorder`,
error: `${VIEW_LABELS[i]} view, upload failed`,
@@ -1381,6 +1432,26 @@ function renderSlot(i) {
el.setAttribute('aria-label', labels[s.state] || VIEW_LABELS[i]);
}
+// Shows/hides the "fill in the other sides" opt-in beneath the drop zone.
+// Only Pixal3D offers it, and only while at most one photo is uploaded. The
+// worker's MV-Adapter rung synthesizes the other three sides from a single
+// reference, so it has nothing to do once a second photo narrows the job to
+// plain multi-view fusion.
+function updatePixal3dPanel() {
+ if (!els.pixal3dPanel) return;
+ const isPixal3d = selectedEngine.backend === 'pixal3d';
+ els.pixal3dPanel.classList.toggle('is-hidden', !isPixal3d);
+ if (!els.pixal3dFillSides) return;
+ if (!isPixal3d) {
+ els.pixal3dFillSides.checked = false;
+ return;
+ }
+ const uploadedCount = slots.filter((s) => s.state === 'uploaded').length;
+ const eligible = uploadedCount <= 1;
+ els.pixal3dFillSides.disabled = !eligible;
+ if (!eligible) els.pixal3dFillSides.checked = false;
+}
+
function clearSlot(i) {
const s = slots[i];
if (s.objectUrl) URL.revokeObjectURL(s.objectUrl);
@@ -1398,11 +1469,13 @@ function swapSlots(a, b) {
}
function firstFreeSlot() {
- return slots.findIndex((s) => s.state === 'empty' || s.state === 'error');
+ const cap = activeMaxImages();
+ return slots.findIndex((s, i) => i < cap && (s.state === 'empty' || s.state === 'error'));
}
function nextFreeAfter(i) {
- for (let j = i + 1; j < slots.length; j++) {
+ const cap = activeMaxImages();
+ for (let j = i + 1; j < cap; j++) {
if (slots[j].state === 'empty' || slots[j].state === 'error') return j;
}
return -1;
@@ -1415,13 +1488,14 @@ function openPicker(index) {
}
// Distribute dropped/picked files into slots, starting at `startIndex` (or the
-// first free slot when null), filling free slots up to MAX_VIEWS.
+// first free slot when null), filling free slots up to the active engine's cap.
function handleFiles(startIndex, fileList) {
const files = Array.from(fileList).filter((f) => f && f.type && f.type.startsWith('image/'));
if (!files.length) return;
- let idx = startIndex == null ? firstFreeSlot() : startIndex;
+ const cap = activeMaxImages();
+ let idx = startIndex == null || startIndex >= cap ? firstFreeSlot() : startIndex;
for (const file of files) {
- if (idx < 0 || idx >= MAX_VIEWS) idx = firstFreeSlot();
+ if (idx < 0 || idx >= cap) idx = firstFreeSlot();
if (idx < 0) break; // all slots taken
uploadToSlot(idx, file);
idx = nextFreeAfter(idx);
@@ -1690,6 +1764,21 @@ async function startJob({ prompt, imageUrls, skipValidation, payment, seed, prog
// only — the director rewrites a prompt, and an image submission has
// none to rewrite.
: { prompt, aspect_ratio: aspectRatio, director: true, ...base };
+ // Match my photo (Pixal3D): tag each uploaded view with the slot it actually
+ // sits in (Front/Back/Left/Right → front/back/left/right), so a user who
+ // drag-reordered or skipped a slot still gets the label they placed the
+ // photo under, not a blind 0/1/2/3 guess. One photo + the opt-in asks the
+ // worker to synthesize the other three sides instead (MV-Adapter).
+ if (selectedEngine.backend === 'pixal3d' && Array.isArray(imageUrls) && imageUrls.length) {
+ const pixal3dLabels = catalog?.backends?.find((b) => b.id === 'pixal3d')?.view_labels;
+ if (Array.isArray(pixal3dLabels)) {
+ const uploadedSlotIndexes = slots
+ .map((s, i) => (s.state === 'uploaded' && s.url ? i : -1))
+ .filter((i) => i >= 0);
+ body.view_labels = uploadedSlotIndexes.map((i) => pixal3dLabels[i] ?? null);
+ }
+ if (imageUrls.length === 1 && els.pixal3dFillSides?.checked) body.fill_other_sides = true;
+ }
// What this maker said they are building for, remembered from an earlier
// model. Absent until they answer once; the server ignores an unknown value.
const destination = storedForgeDestination();
diff --git a/tests/forge-view-slots.test.js b/tests/forge-view-slots.test.js
index 12b8b7784..2b67f239b 100644
--- a/tests/forge-view-slots.test.js
+++ b/tests/forge-view-slots.test.js
@@ -59,13 +59,25 @@ describe('/forge reference-view slots', () => {
expect(clientViewLabels().length).toBeLessThanOrEqual(serverMaxViews());
});
- it('scans for the next free slot within the array, not a separate constant', () => {
+ it('scans for the next free slot within activeMaxImages(), which is clamped to the array itself', () => {
const fn = clientSrc.slice(clientSrc.indexOf('function nextFreeAfter'));
const body = fn.slice(0, fn.indexOf('\n}') + 2);
- // The loop bound is the array itself: filling the LAST slot must return
- // -1 ("no free slot"), never read one past the end.
- expect(body).toContain('j < slots.length');
+ // The loop bound is activeMaxImages() (a per-engine cap, e.g. Pixal3D's 4),
+ // never a separate hardcoded constant that could drift from the array.
+ expect(body).toContain('activeMaxImages()');
+ expect(body).toContain('j < cap');
expect(body).not.toContain('j < MAX_VIEWS');
+ expect(body).not.toContain('j < slots.length');
+ });
+
+ it('activeMaxImages() can only tighten the cap, never widen it past the slot array', () => {
+ const fn = clientSrc.slice(clientSrc.indexOf('function activeMaxImages'));
+ const body = fn.slice(0, fn.indexOf('\n}') + 2);
+ // A backend's advertised max_images can shrink the usable range but must
+ // never exceed MAX_VIEWS, or nextFreeAfter/firstFreeSlot would read past
+ // the end of slots[] exactly like the bug this file is named for.
+ expect(body).toContain('Math.min(');
+ expect(body).toContain('MAX_VIEWS');
});
it('nextFreeAfter semantics: returns -1 past the end rather than throwing', () => {