# PLAYTEX AI Image to Three.js browser-session protocol

This protocol lets a user's existing coding agent publish its Image to Three.js work into the browser workspace at `https://www.playtex.ai/image-to-threejs`. PLAYTEX AI does not run another agent. The reference image stays in the user's project; generated status, code, preview, spec, result, evidence, and artifact metadata are relayed to the page for review.

## Connection contract

The user must first click **Create browser session** and copy the generated connection prompt. That prompt contains three short-lived values:

- `relayEndpoint`: the HTTPS Edge Function URL.
- `sessionId`: the public session identifier.
- `writeToken`: a high-entropy capability token that authorizes publishing to this one session.

Treat the write token as a secret. Never print it in generated source, commit it, include it in an artifact, or reuse it after the session expires. Sessions expire 24 hours after creation.

## First action

Immediately confirm the connection with one JSON POST:

```json
{
  "action": "publish",
  "sessionId": "SESSION_ID_FROM_PROMPT",
  "writeToken": "WRITE_TOKEN_FROM_PROMPT",
  "kind": "status",
  "status": "connected",
  "phase": "Connected",
  "progress": 2,
  "message": "Agent connected. Waiting for or validating the reference image."
}
```

Send the request to the exact `relayEndpoint` from the connection prompt with `Content-Type: application/json`. A successful response has `ok: true`.

## Build workflow

1. Work in the user's current project unless they name another directory.
2. Ask for one reference image and intended use only if they have not supplied them. Keep the reference file local and never encode or upload it to the relay.
3. Use the installed `$img2threejs` skill when available. Read its complete `SKILL.md` and all required references before acting. If the skill is unavailable, follow the same staged contract manually; do not invoke or delegate to a second coding agent.
4. Validate the reference, define the quality contract, inventory identity-defining details, create and strictly validate the sculpt spec, then build in locked passes.
5. After each meaningful gate, publish `kind`, `status`, `phase`, `progress`, and `message`. Keep messages factual and under 800 characters.
6. Publish the complete current `createModel.ts` as `modelCode` whenever it materially changes.
7. Render useful angles, compare them with the source, correct visible causes within a bounded loop, and publish the review data.
8. Do not stop at analysis or a plan. Finish the implementation and publish the final output to the browser.

Allowed status values are `connected`, `building`, `reviewing`, `complete`, and `failed`. Allowed kind values are `status`, `stage`, `artifact`, `warning`, and `error`. Progress must be an integer from 0 to 100.

## Live preview contract

Preferred: build a complete standalone `preview.html` and publish its text as `previewHtml`.

The preview must:

- run without a local dev server, filesystem URL, parent-page access, cookies, forms, popups, or navigation;
- load remote Three.js modules only from `https://esm.sh`, `https://cdn.jsdelivr.net`, or `https://unpkg.com`;
- include its own renderer, camera, lights, resize handling, and orbit interaction;
- render the generated factory or an equivalent inlined build, not a placeholder object;
- avoid relying on `allow-same-origin` because the browser deliberately uses an opaque-origin sandbox.

Fallback: publish a PNG, JPEG, or WEBP data URL as `previewImageDataUrl` when a standalone interactive document is not feasible. Do not put the reference image in this field.

The page injects a restrictive Content Security Policy and renders HTML with `sandbox="allow-scripts"` only.

## Publish request

Every update is a JSON POST to the session's relay endpoint:

```json
{
  "action": "publish",
  "sessionId": "SESSION_ID_FROM_PROMPT",
  "writeToken": "WRITE_TOKEN_FROM_PROMPT",
  "kind": "stage",
  "status": "building",
  "phase": "Blockout",
  "progress": 25,
  "message": "Primary silhouette and scale contract are in place.",
  "modelCode": "optional complete createModel.ts source",
  "previewHtml": "optional complete standalone HTML",
  "previewImageDataUrl": "optional data:image/png;base64,...",
  "sculptSpec": { "optional": "JSON value" },
  "result": { "optional": "JSON value" },
  "evidence": { "optional": "JSON value" },
  "artifacts": { "optional": "JSON value" },
  "eventPayload": { "optional": "small structured event metadata" }
}
```

Omitted artifact fields preserve their last published value. Use a new request only when state changes; do not flood the relay. The browser polls every two seconds and retains up to 200 activity events.

Approximate field limits:

- `modelCode`: 750,000 characters
- `previewHtml`: 1,500,000 characters
- `previewImageDataUrl`: 2,750,000 characters
- `sculptSpec`: 500 KB JSON
- `result`: 300 KB JSON
- `evidence`: 750 KB JSON
- `artifacts`: 500 KB JSON

## Required final publish

A complete run publishes `status: "complete"`, `progress: 100`, and:

- `modelCode`: the verified `createModel.ts` source, importing `three`, returning a `THREE.Group`, and preserving `root.userData.sculptRuntime`;
- `previewHtml` or `previewImageDataUrl`;
- `sculptSpec`: component hierarchy, materials, topology choices, attachments, pivots, sockets, build passes, and review targets;
- `result`: suitability, fidelity from 0 to 1, assumptions, limitations, type-check/build verdict, and reviewed-angle count;
- `evidence`: reference-versus-render measurements and useful multi-angle review data, but never the reference image bytes;
- `artifacts`: a manifest of local files and their roles. Paths are metadata only; the relay does not fetch them.

If the run cannot complete, publish `status: "failed"`, a precise `phase` and `message`, plus any useful partial source or evidence. Ask for better input when the reference cannot support the requested fidelity.

## Optional skill installation

```bash
npx skills add https://github.com/hoainho/img2threejs --skill img2threejs -g
```

Remove `-g` for a project-local install. The upstream workflow is Apache-2.0 licensed.

## Privacy and security

- Never upload the reference image to PLAYTEX AI.
- Generated output is intentionally sent to the user's private browser session so it can be rendered there.
- Never send credentials, environment variables, project secrets, unrelated source, or dependency contents.
- Do not request a PLAYTEX AI account, PLAYTEX AI API key, or model-provider key for the relay.
- The write token authorizes only one expiring session. The browser receives a separate read token.
- Stay inside the authorized project and installed-skill directories.

## Documentation

- Workspace: https://www.playtex.ai/image-to-threejs
- Human guide: https://www.playtex.ai/guides/image-to-threejs-guide
- Manifest: https://www.playtex.ai/image-to-threejs/agent.json

Last reviewed: July 23, 2026.