Browser runtime SDK

Status: Normative for component selection and security; detailed method signatures remain tied to the shipped runtime version.

The browser runtime is the preferred way to embed published Vertcie content. Pin the documented runtime version associated with the deployment.

Drop-in client elements

For image output rather than an interactive configurator, see Standalone runtime images. The separate <vertcie-image> module looks up an image, renders a complete signature on a miss, disposes the model, and optionally stores the result on an authorized board. It does not depend on Render Studio. The image module and storage endpoint are implementation-preview features until their coordinated deployment is verified.

Most browser integrations should load the client-element module once and use one of the two wrapper elements. The wrappers select the current Runtime release, follow the active publication revision by default, and initialize the underlying runtime component.

<script
  type="module"
  src="https://cdn.vertcie.com/runtime/vertcie-client-elements.js"
></script>

<vertcie-client-expanders
  pid="PUBLISHED_FILE_ID"
  api-key="VERTCIE_PUBLIC_API_KEY"
></vertcie-client-expanders>

Use the Signature client when the integration is driven by a canonical product signature:

<vertcie-client-signature
  pid="PUBLISHED_FILE_ID"
  signature="PRODUCT_SIGNATURE"
  api-key="VERTCIE_PUBLIC_API_KEY"
></vertcie-client-signature>

The pid attribute is the permanent Published File ID. endpoint defaults to https://app.vertcie.com, and the active revision is followed unless a positive revision attribute is supplied. api-key may instead be supplied once through window.VERTCIE_CLIENT_CONFIG.apiKey before the module loads. Browser keys must be origin-restricted and limited to public runtime permissions.

Production embeds may also set runtime-version to an exact Expanders or Signature package version. A pinned runtime skips the mutable release lookup and changes only when the embed deliberately adopts another version. The equivalent imperative option is runtimeVersion; it is consumed by the wrapper and is not passed into the renderer configuration.

Inside the authenticated Vertcie workspace, omit api-key and use the current workspace origin as endpoint; the runtime sends session credentials. External embeds use an origin-restricted public runtime key because they do not share the Vertcie workspace session.

Editable runtime rules

Cross-option availability and forced selections are authored in the card's Rules Editor. Conditions and actions are selected from the current workflow by their displayed names; the saved document stores stable group and choice IDs. Rule order is controlled by priority, every target is validated before save, and each save creates an immutable Rules version. The active Rules version is published as runtimeRules in the Expanders manifest and is consumed by both the default Expanders UI and custom presentation layers.

Supported conditions are equals, does not equal, includes, and exists. Supported actions enable or disable a choice, select a structural choice, or select a material choice. Product-family exceptions therefore remain data that an editor can inspect and update in the UI; custom runtime source must not contain product IDs, option labels, or house-rule matrices.

Custom elements are not void HTML elements, so plain HTML must include the closing tag. JSX may use <vertcie-client-expanders ... /> and <vertcie-client-signature ... /> shorthand.

Runtime components

For applications that need direct lifecycle control, Runtime exposes the lower-level <vertcie-expanders> and <vertcie-signature> elements. Initialize either component with the permanent Published File ID and choose whether the integration follows the active revision or pins an immutable revision.

Follow the active revision:

const expanders = document.querySelector("vertcie-expanders");

await expanders.initialize({
  publishedFileId: "PUBLISHED_FILE_ID",
  useLatest: true,
  endpoint: "https://VERTCIE_HOST",
  apiKey: "VERTCIE_PUBLIC_API_KEY",
});

Pin an exact revision:

await expanders.initialize({
  publishedFileId: "PUBLISHED_FILE_ID",
  revision: 4,
  endpoint: "https://VERTCIE_HOST",
  apiKey: "VERTCIE_PUBLIC_API_KEY",
});

The same useLatest and revision properties apply to <vertcie-signature>.

• useLatest: true follows the currently active revision without changing the customer integration.
• revision: N pins immutable revision N.
• Do not provide useLatest: true and revision together.
• Omitting both follows the active revision for backward compatibility.
• useLatest: false requires an explicit revision or an exact supplied manifest.
• A pinned load fails if the manifest does not match the requested Published File ID, revision, and client.

The Runtime Catalog provides separate copy controls for the permanent Published File ID, the selected pinned runtime configuration, and the explicit latest runtime configuration.

Choose the smallest abstraction

ListModelOptions and ListOptionShaders are also public compatibility exports for consuming model option and shader lists. VERTCIE_CLIENT_VERSION identifies the shipped client. New UI code normally prefers VertcieScene or VertcieExpanders unless it specifically needs the list adapters.

Do not instantiate a full viewport when an image is sufficient. Do not reproduce selection logic by parsing undocumented hierarchy internals when VertcieScene or the resolve-selection endpoint provides it.

Multi-product compositions

A saved Compositor scene owns each product's resource revision, transform, visibility, Expander selections, and canonical Signature. Runtime mode chooses the editing surface; it does not create a second configuration state.

Customer-specific Published File IDs and Signatures belong in a separate integration guide, not in this platform SDK. The examples below therefore use interchangeable placeholders.

Importing the deployable module automatically registers the <vertcie-compositor> custom element. HTML custom elements require an explicit closing tag; do not use self-closing syntax.

<vertcie-compositor id="composition"></vertcie-compositor>

<script type="module">
  import "https://cdn.vertcie.com/runtime/compositor/vCOMPOSITOR_VERSION/index.js";

  const compositor = document.querySelector("#composition");
  await compositor.initialize({
    endpoint: "https://VERTCIE_TENANT_API_ORIGIN",
    apiKey: "YOUR_RUNTIME_API_KEY",
    mode: "expanders",
    products: [
      {
        Key: "product-a-1",
        PID: "PUBLISHED_FILE_ID_A",
        Signature: "PRODUCT_SIGNATURE_A",
        Transform: {
          position: [0, 0, 0],
          rotation: [0, 0, 0],
          scale: [1, 1, 1],
        },
        Visible: true,
        showTransformControls: false,
      },
      {
        Key: "product-b-1",
        PID: "PUBLISHED_FILE_ID_B",
        Signature: "PRODUCT_SIGNATURE_B",
        Transform: {
          position: [1.5, 0, 0.15],
          rotation: [0, 0.3926990817, 0],
          scale: [1, 1, 1],
        },
        Visible: true,
        showTransformControls: false,
      },
    ],
  });
</script>

vertcie-compositor {
  display: block;
  width: 100%;
  min-height: 42rem;
}

const compositor = document.querySelector("vertcie-compositor");

await compositor.initialize({
  endpoint: "https://VERTCIE_HOST",
  apiKey: "VERTCIE_PUBLIC_API_KEY",
  mode: "expanders",
  products: [
    {
      Key: "product-a-1",
      PID: "PUBLISHED_FILE_ID_A",
      Signature: "PRODUCT_SIGNATURE_A",
      Transform: {
        position: [0, 0, 0],
        rotation: [0, 0, 0],
        scale: [1, 1, 1],
      },
    },
    {
      Key: "product-b-1",
      PID: "PUBLISHED_FILE_ID_B",
      Signature: "PRODUCT_SIGNATURE_B",
      Transform: {
        position: [1.35, 0, 0],
        rotation: [0, 0, 0],
        scale: [1, 1, 1],
      },
    },
  ],
});

This is Signature Runtime applied to an array. mode: "expanders" adds contextual controls when a model is clicked; it does not change the product input contract. vtx:scene-change returns the updated canonical scene after either a contextual control or code changes a product.

Never address a product by array index. Key is stable instance identity. PID may be used by itself when only one instance of that PID exists.

Transform is applied to the root of that product after its published assets are assembled. All three vectors are absolute values, not deltas:

• position: [x, y, z] moves the product in composition scene units.
• rotation: [x, y, z] rotates the product with XYZ Euler angles in radians.
• scale: [x, y, z] scales the complete product on each axis; [1, 1, 1] is its

published size and every component must be greater than zero.

The root transform wraps the published product's internal option and mesh transforms. Changing a Signature therefore cannot erase the product's placement. Supplying a later Transform through setProductConfigurations replaces the previous root transform atomically and leaves every other keyed product unchanged.

await compositor.setProductConfigurations([
  { Key: "product-a-1", PID: "PUBLISHED_FILE_ID_A", Signature: "PRODUCT_SIGNATURE_A" },
  {
    Key: "product-b-1",
    PID: "PUBLISHED_FILE_ID_B",
    Signature: "PRODUCT_SIGNATURE_B",
    Transform: {
      position: [1.5, 0, 0.15], // move in scene units
      rotation: [0, Math.PI / 8, 0], // rotate 22.5 degrees around Y
      scale: [1.1, 1.1, 1.1], // scale the entire product by 10%
    },
  },
]);

Each returned identity includes Key, PID, Signature, Transform, and Visible, plus its internal resourceId and resolved revision. PID and publishedFileId are the same immutable publication identity. "latest" resolves the active revision and the returned scene pins that actual revision. Both commands use the canonical selection-resolution API and apply the same visibility, shader, and transform-node result as a singular-product runtime. Selection and scene-change events carry the same identity so duplicate instances remain unambiguous.

Custom Figma, Redux, and Three.js applications

Applications that own their visual controls and viewer must follow runtime-custom-ui.md. That guide is the normative, complete contract for:

• loading and validating the Expanders manifest;
• canonical branch ownership, dependencies, Match Keys, and selection flow;
• Redux state ownership, actions, selectors, generation control, and mock/live

normalization;

• authored option labels and shader-to-swatch mapping;
• immutable full-shader resolution and publication-scoped signed assets;
• Three.js material properties, texture slots, color spaces, tiling, rotation,

flips, targeting, precedence, baseline restoration, and disposal;

• mesh visibility, transforms, presentation-state isolation, newest-wins async

behavior, and acceptance tests.

Figma owns presentation only. Redux mirrors the canonical serializable session snapshot. The Expander session remains the configuration authority, and runtime resources remain outside Redux. Missing runtime data must fail visibly and must never be fabricated from GLTF materials, colors, filenames, or design files.

Standalone scene data

import { VertcieScene } from "https://VERTCIE_HOST/catalogs/vertcie-client-min.js";

const scene = new VertcieScene({
  endpoint: "https://VERTCIE_HOST",
  apiKey: "VERTCIE_PUBLIC_API_KEY",
});

const payload = await scene.getPublishedFile("PUBLISHED_FILE_ID");

Build controls from identifiers supplied by the scene. Preserve branch and option array order from the manifest; that authored order is the dropdown order. On a selection change, use the runtime helper or POST /api/v1/publications/{publishedFileId}/selection-resolutions. This endpoint executes the same Expander or Signature manifest contract used by Preview/Publish and returns visibility, materials, transforms, and mesh paths as a single vertcie/runtime-selection-resolution/v1 update. Do not infer conditional groups or sort them by display label.

Hosted runtime control

Optional selection presentation

Published Client UX presentation controls interaction.selectionTransitions and interaction.zoomToOption. Selection transitions default to enabled and may be explicitly disabled; selectionDuration configures the bounded cross-fade duration from 0.1–1.2 seconds. Transitions diff the effective mesh visibility and shader stack, preserving unchanged materials, and become instant when the user requests reduced motion. zoomToOption defaults to disabled.

zoomToOption is option-scoped: after a user selects an Expander option, Core unions the transformed world-space bounding boxes of every asset ID in that option's authored selectedMeshes array and fits all eight corners to the current camera. It does not fit the aggregate configured product, use display labels, or infer parts from object names. An option with no contributed meshes does not move the camera. Optional option focus metadata may specify direction, padding, and durationMs; it changes presentation only and never replaces the option's canonical mesh set.

Expander option presentation is also authorable. presentation.subs.mode accepts dropdown, expanders, or none. presentation.swatches controls the finish grid through bounded columns, pageSize, size, and rolloverZoom values plus the search and filters feature flags. Search matches authored finish labels; filters use authored material subpaths and families. These settings change presentation only and never reorder or alter canonical selection data.

A Vertcie host page exposes window.vertcieClient.vtx. Wait for the host/runtime readiness signal documented by the shipped bundle before calling it. The namespace combines scene-data access and control of the live expander/viewer instance; it is not a general browser automation API.

Lifecycle and state

• Create one runtime owner per container and dispose it when the component unmounts.
• Cancel or ignore stale async results when publishedFileId changes.
• Treat a change to revision or latest/active resolution as a new runtime load, even when publishedFileId remains the same.
• Preserve selection by stable option/shader identifiers, not display labels or array positions.
• Apply model, selection, camera, and environment updates deliberately; do not rely on request completion order.
• Refresh expired signed assets by repeating the supported lookup.
• Feature-detect optional runtime capabilities when supporting more than one deployed runtime version.

Framework integration

Load browser-only runtime code after the DOM is available. In React/Next.js, isolate it in a client component, retain the instance in a ref, and clean it up in the effect disposer. Do not import browser globals during server rendering.

CSP and origin policy

Allow only the deployed Vertcie host and documented asset origins in script-src, connect-src, img-src, and any worker directives required by the runtime. Avoid *. The browser's real origin must match the API key's allowed-origin policy.

Live verification

Test the exact deployed bundle, documented exports, allowed origin, representative products, selections, images, and error states before production rollout.