Headless Renderer

npm install @simplio3d/viewer three

# NOT YET PUBLISHED — this returns 404 today. Vendor dist/simplio3d-viewer.standalone.js
# from the platform repo instead, and import it by relative path.

# three is a PEER dependency, deliberately. If the package bundled it, a host
# that already runs three would get two copies: instanceof fails across the
# boundary, THREE.Cache splits, disposal leaks — and none of it throws.

import { createViewer } from '@simplio3d/viewer';

const viewer = await createViewer({
  el: '#stage',              // element or CSS selector
  projectId: 'proj_123',
  shareToken: 'e060a524…',   // from the project's Share dialog
});

// Your UI, your framework. Build it from viewer.blocks (authored order).
viewer.select('blk_frame', 'walnut');

<!-- TODAY: vendor the bundle and serve it from your own origin. -->
<script type="module">
  import { createViewer } from './vendor/simplio3d-viewer.standalone.js';
  await createViewer({ el: '#stage', projectId, shareToken });
</script>

<!-- ONCE PUBLISHED, the same file is reachable from a CDN — 404 until then:
  import { createViewer } from 'https://cdn.jsdelivr.net/npm/@simplio3d/viewer/dist/simplio3d-viewer.standalone.js';
-->

<!-- The standalone build BUNDLES three (~268 kB gzip), because three ships no
     UMD build and a plain HTML page cannot resolve a bare specifier.
     If your page already loads three, use dist/index.js with an import map
     instead so you do not end up with two copies. -->

// viewer.blocks is the authored order — never sort it.
// viewer.visibility is the result of conditional-logic evaluation.
for (const block of viewer.blocks) {
  if (viewer.visibility[block.id] === false) continue;
  for (const variant of block.dropdownVariants ?? []) {
    renderSwatch(variant.label, () => viewer.select(block.id, variant.value));
  }
}

// Re-render your controls when a rule shows or hides a block.
viewer.on('applied', () => rebuildUI());

viewer.getState();
// {
//   'blk_frame':  'walnut',                  // dropdown, select-material,
//                                            // thumbnail-selector, toggle-switch, carousel
//   'blk_extras': ['armrests', 'headrest'],  // checkbox — chosen values
//   'blk_size':   { width: 120, height: 40 } // number-input — keyed by NUMERAL VARIANT id
// }

// number-input is a MAP, not a number: one block can expose several numeric
// parameters, and conditional rules target a specific one.

// setState is ATOMIC — use it to restore a saved configuration. A loop of
// select() calls re-applies after each one and is order-dependent.
viewer.setState(savedConfiguration);

// Returns a high-resolution, TRANSPARENT PNG Blob.
// This is what fills configuration.screenshotUrl on a quote submission.
const blob = await viewer.snapshot();

const form = new FormData();
form.append('screenshot', blob, 'configuration.png');

viewer.camera.reset();                       // back to the project's saved camera
viewer.camera.frame();                       // fit the whole product
viewer.camera.set([3, 2, 5], [0, 0.5, 0]);   // position, target

const off = viewer.on('option.changed', (d) => console.log(d.blockId, d.value));
off(); // unsubscribe

// 'ready' | 'progress' | 'option.changed' | 'applied' | 'visibility.changed' | 'error'

// NOTE: 'progress', model-load 'error's, the first 'applied' and 'ready' all fire
// BEFORE createViewer resolves, so viewer.on() cannot see them. Pass callbacks in:
await createViewer({
  el, projectId, shareToken,
  onProgress: ({ loaded, total }) => setBar(loaded / total),
  onError: (err) => console.warn(err.message),
});

const { scene, camera, renderer, controls, parts } = viewer.three;

// Add a floor, a custom light rig, post-processing, a second camera…
scene.add(myFloor);

// parts is a name → meshes index. One name can map to SEVERAL meshes:
// duplicate mesh names across subgroups are intentional on this platform,
// which is why scene.getObjectByName() (first match only) under-applies.
console.log(parts.get('Leg')?.length);

viewer.dispose();
// Releases the WebGL context, listeners, geometries and materials.
// Safe to mount/unmount repeatedly — without forceContextLoss a browser
// runs out of WebGL contexts after ~16 mounts and later ones render nothing.

import { createViewer, ShareFetchError } from '@simplio3d/viewer';

try {
  await createViewer({ el, projectId, shareToken });
} catch (err) {
  if (err instanceof ShareFetchError && err.isUnavailable) {
    // The project OWNER's billing lapsed. Show a neutral message.
    // Do NOT retry, and do NOT surface billing detail to a shopper.
    showUnavailable();
  }
}

<iframe
  src="https://YOUR_APP_DOMAIN/share/PROJECT_ID/SHARE_TOKEN?ui=viewer"
  width="100%"
  height="600"
  frameborder="0"
  allowfullscreen
  allow="accelerometer; autoplay; camera; clipboard-write; encrypted-media; gyroscope; picture-in-picture; xr-spatial-tracking"
></iframe>