` with no height gets a sensible `70vh` default rather than\nrendering invisibly).\n\n### Scaffold a deployable page\n\n```bash\nnpx 3d-ar-studio create my-ar-site # a folder you can publish as-is\ncd my-ar-site\nnpx 3d-ar-studio dev # look at it locally\nnpx 3d-ar-studio deploy # push it and turn on GitHub Pages\n```\n\n`deploy` prints every `git` and `gh` command before it runs it. It needs\n[git](https://git-scm.com) and the [GitHub CLI](https://cli.github.com); without them it tells\nyou the three manual steps instead of failing silently.\n\nTemplates: `static` (one HTML file, no build), `vite`, `react`.\n\nBoth `3d-ar-studio` and `ar-studio` run the CLI. The MCP server is a separate\nbinary in its own package, so `npx 3d-ar-studio-mcp` resolves cleanly: see\n[MCP server](#mcp-server).\n\n---\n\n## Your own models\n\nThe tray is filled from three.ws by default: a few hundred public-domain (CC0) props, free for\ncommercial use, served with open CORS. Swap in your own with the `assets` option.\n\n**A JSON file anywhere.** Five common shapes are read without reshaping:\n\n```js\ncreateArStudio(el, { assets: 'https://cdn.acme.com/models.json' })\n```\n\n```jsonc\n// Any of these work:\n[ { \"url\": \"https://cdn.acme.com/chair.glb\", \"name\": \"Aero chair\" } ]\n{ \"items\": [ … ] }\n{ \"objects\": [ … ] } // three.ws object library\n{ \"creations\": [ … ] } // three.ws forge gallery\n{ \"models\": [ … ] }\n```\n\nPer entry, the model URL is read from the first present of `src`, `url`, `glb`, `glb_url`,\n`glbUrl`, `file` or `model`; the label from `title`, `label`, `name` or `prompt`; and the\nthumbnail from `poster`, `thumb`, `thumbnail`, `image` or `preview_image_url`. Anything that\nis not an https (or site-relative) URL is dropped rather than handed to the loader.\n\n**A list you hold in code:**\n\n```js\nimport { staticSource } from '3d-ar-studio/sources'\n\ncreateArStudio(el, {\n assets: staticSource({\n label: 'Our furniture',\n items: [{ src: 'https://cdn.acme.com/chair.glb', title: 'Aero chair', poster: '…' }],\n }),\n})\n```\n\n**Several tabs at once, in the order you want them:**\n\n```js\ncreateArStudio(el, { assets: ['recent', myCatalogue, 'objects', 'link'] })\n```\n\nBuilt-in keys: `'three.ws'` (the default set), `'recent'`, `'objects'`, `'community'`, `'link'`.\n\n**Anything else.** A source is an object with a `list()`:\n\n```js\ncreateArStudio(el, {\n assets: {\n id: 'search',\n label: 'Search',\n searchable: true,\n async list() {\n const rows = await fetch('/api/models').then((r) => r.json())\n return rows.map((m) => ({ src: m.glb, title: m.name, poster: m.thumb }))\n },\n },\n})\n```\n\nThrowing from `list()` is fine: the tray renders a designed error state with a Retry button.\n\n**Your users can retarget it too**, without touching your code: `?assets=https://…/manifest.json`\non the page URL. Only https URLs are accepted, and every model source is re-validated before it\nreaches the loader, so a hostile link can add a catalogue but can never smuggle a\n`javascript:` or `data:` model into the scene. Set `allowUrlOverride: false` to switch that off.\n\n### CORS\n\nModels are loaded by the browser, so the host serving your `.glb` files has to allow\ncross-origin requests (`access-control-allow-origin`). If a model fails to load, that is\nalmost always why, and the studio says so in the status line rather than failing silently.\n\n---\n\n## Options\n\n| Option | Default | What it does |\n| --- | --- | --- |\n| `assets` | `'three.ws'` | Where models come from: a preset key, a manifest URL, a source object, or an array of them. |\n| `generate` | enabled | `{ enabled, endpoint, kind, tier, timeoutMs, pollMs }`. `endpoint` is any MCP server exposing a compatible generate tool. |\n| `rooms` | enabled | `{ enabled, server }`. Point `server` at your own Colyseus deployment to host shared rooms yourself. |\n| `animations` | three.ws idle clip | `{ enabled, manifestUrl, clip }`. The clip retargeted onto humanoid models that ship no animation. |\n| `lighting` | `'studio'` HDRI | `{ preset, urls }`. `preset: null` uses procedural lighting only and downloads no HDRI. |\n| `branding` |: | `{ title, accent, backHref, backLabel }`. |\n| `shareBaseUrl` | this page | Where share links and QR codes point. |\n| `origin` | `https://three.ws` | Origin for the hosted \"View in your space\" launcher and viewer links. |\n| `persistKey` | `'ar-studio:scene:v1'` | localStorage key for the saved scene. Change it to run two studios on one origin. |\n| `persist` | `true` | Restore the last scene on load. |\n| `maxPlacements` | `20` | Cap on simultaneous models. Keeps low-end phones interactive. |\n| `fullscreen` | auto | Render as a fixed full-screen layer. Defaults to true only when mounted on `document.body`. |\n| `allowUrlOverride` | `true` | Honour `?assets=`, `?src=`, `?room=` and `?forge=` on the hosting page's URL. |\n| `onEvent` | `null` | Called with `(event, detail)` for every notable action. Wire it to your analytics. |\n\n### URL parameters\n\n| Parameter | Effect |\n| --- | --- |\n| `?assets=
` | Swap the catalogue. |\n| `?src=&title=` | Load models into the scene. Repeatable. |\n| `#s=` | Reopen a full arrangement, transforms included. Written by `shareUrl()`. |\n| `?room=` | Join a shared room. |\n| `?forge=` | Start a generation on load. |\n\n### Methods\n\n```js\nawait studio.addModel({ src, title }) // place a model\nstudio.clear() // remove everything; returns what was there\nstudio.getScene() // [{ src, title, x, z, yaw, scale }]\nawait studio.setScene(items) // replace the arrangement\nstudio.shareUrl() // a link that reopens it exactly\nawait studio.generate('a brass desk lamp') // text to 3D, into the room\nstudio.viewInYourSpace(src, title) // open the hosted launch page for one model\nawait studio.startCamera() // needs a user gesture on iOS\nawait studio.enterAR() // best AR path for this device\nstudio.openArSheet() // the \"Place in your space\" hand-off sheet\nstudio.closeArSheet()\nawait studio.placeInYourSpace() // straight to the native viewer, no sheet\nawait studio.toggleImmersive() // enter or leave WebXR specifically\nawait studio.openRoom() // returns the room code\nstudio.destroy() // releases camera, socket and GPU context\n```\n\n### Events\n\n`studio.on(name, fn)` returns an unsubscribe function. The same events also fire as\n`ar-studio:` DOM events on the mounted element.\n\n| Event | Detail |\n| --- | --- |\n| `add` | `{ placement, remote }` |\n| `remove` | `{ src, title }` |\n| `select` | `{ placement }` (null when deselected) |\n| `clear` | `{ items }` |\n| `generate` | `{ model }` |\n| `generate-error` | `{ error, prompt }` |\n| `camera` | `{ active }` |\n| `xr` | `{ active }` |\n| `native-ar` | `{ src, title, viewer }` where viewer is `quicklook`, `sceneviewer` or `none` |\n| `native-ar-error` | `{ error, src }` |\n| `ar-sheet` | `{ open }` when the hand-off sheet opens or closes |\n| `room` | `{ status, code }` |\n| `share` | `{ url }` |\n\n---\n\n## Web component\n\n```html\n\n```\n\n`element.studio` is the live instance. Importing `3d-ar-studio/auto` (what the CDN bundle\ndoes) registers the element for you.\n\n---\n\n## Keyboard and accessibility\n\nEvery control is a real button with an accessible name, the source tabs implement the full\nARIA tablist contract, and each dialog takes and returns focus.\n\n| Key | Action |\n| --- | --- |\n| Arrows | Nudge the selected model, camera-relative. Hold Shift for fine steps. |\n| `R` | Rotate 45°. |\n| `D` | Duplicate. |\n| Delete / Backspace | Remove, with an undo in the status line. |\n| Escape | Close the open panel, or deselect. |\n\n`prefers-reduced-motion` removes the spawn-in animation and every transition.\n\n---\n\n## MCP server\n\n```bash\nnpx 3d-ar-studio-mcp\n```\n\n```json\n{\n \"mcpServers\": {\n \"3d-ar-studio\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"3d-ar-studio-mcp\"]\n }\n }\n}\n```\n\nNo API key. Every tool is free and keyless.\n\n| Tool | What it does |\n| --- | --- |\n| `generate_3d_model` | Turn a text prompt into a textured GLB. Returns the model plus links that open it in AR. |\n| `check_generation` | Collect a generation that was still rendering when the first call returned. |\n| `search_models` | Search the free CC0 library (or any catalogue you configure) by name, category and tag. |\n| `compose_ar_scene` | Arrange several models into one scene and return a single link that reopens it exactly. |\n| `export_ar` | Turn any GLB URL into a device-aware \"View in your space\" link. |\n| `create_ar_page` | Emit a complete, self-contained HTML page embedding the studio, ready to commit. |\n\n| Environment variable | Default | What it changes |\n| --- | --- | --- |\n| `AR_STUDIO_PAGE_URL` | the hosted demo | The page `compose_ar_scene` links to. Set it to your own deployment. |\n| `AR_STUDIO_ASSETS` | the free CC0 library | Catalogue `search_models` searches. |\n| `AR_STUDIO_MCP_ENDPOINT` | three.ws 3D Studio | The MCP endpoint used for generation. |\n| `AR_STUDIO_ORIGIN` | `https://three.ws` | Origin for hosted AR launch and viewer links. |\n\nA session looks like this:\n\n```\n> Put a mid-century lamp and a potted fern in my living room.\n\n generate_3d_model { prompt: \"a brass mid-century desk lamp\" } → lamp.glb\n search_models { query: \"potted plant\" } → fern.glb\n compose_ar_scene { models: [{ src: lamp.glb, x: 0, z: -1.4 },\n { src: fern.glb, x: 0.9, z: -1.2 }] }\n\n → one link; open it on a phone and both objects stand in the room.\n```\n\n---\n\n## Device support\n\n| Device | Path | What you get |\n| --- | --- | --- |\n| Android Chrome | WebXR `immersive-ar` | The whole scene in the room: hit-test placement, per-model anchors, light estimation, depth occlusion. |\n| iOS Safari | AR Quick Look | One model at a time in Apple's own viewer, with real ARKit tracking, scale and occlusion. The model is converted to USDZ on the device. Camera passthrough with gyro world-lock composes the multi-model scene in-page alongside it. |\n| Android without WebXR | Scene Viewer | One model at a time through ARCore, with a browser fallback if ARCore is missing. |\n| Desktop | Preview | Grid floor, drag-look, QR hand-off to a phone. |\n| Headsets | WebXR | Same as Android Chrome. |\n\nThe **AR** button in the top bar always takes the best path the device has, labels itself so it\nnever promises the wrong one, and acts on the selected model (or the last one placed).\n\nCamera and WebXR both need a secure context: `https://` or `localhost`.\n\n### Placing one model in someone's real room\n\nOn a device with WebXR the AR button goes straight into an immersive session. Everywhere else\nit opens the **hand-off sheet**: which model is going, a picker when the scene holds more than\none, and a single primary button that opens the device's own AR viewer.\n\nThe sheet exists for one specific reason, and it is worth knowing about if you are building\nyour own UI on top of this package:\n\n> **iOS opens AR Quick Look only while the page still holds the user gesture that asked for\n> it.** Converting a GLB to USDZ takes a second or two. Start the conversion inside the tap\n> handler and by the time the `` is clicked the gesture has expired, Safari\n> silently declines, and the button looks broken. That is the single most common reason a\n> \"View in AR\" button does nothing on an iPhone.\n\nThere is a second trap right behind it, and it is worse because the failure looks like success:\n\n> **Safari decides whether a URL is an AR asset from its file extension.** A `blob:` URL has no\n> path, so it has no extension. Hand one to `` with no filename and Safari still\n> opens Quick Look, but as a generic 3D preview: the viewer comes up in **Object** mode with AR\n> unavailable. Setting `download=\"something.usdz\"` on the anchor gives Safari the name it\n> sniffs, and Quick Look enters AR. `openQuickLook()` does this for you.\n\nSo the package splits preparing from opening, and never does them in one tap:\n\n```js\nimport { prepareNativeAr, isQuickLookReady } from '3d-ar-studio';\n\n// Ahead of the tap: convert, cache, and keep the result.\nconst handoff = await prepareNativeAr({\n src: 'https://example.com/chair.glb',\n title: 'Chair',\n key: 'chair@1.0', // cache identity; include the scale if you bake one in\n});\n\n// Inside the tap, synchronously. No await between the click and open().\nbutton.addEventListener('click', () => handoff?.open());\n```\n\n`prepareNativeAr` resolves to `null` on a device with no native AR viewer, `{ viewer:\n'quicklook' }` on iOS with a `blob:` USDZ ready to open, and `{ viewer: 'sceneviewer' }` on\nAndroid, where nothing needs converting at all. Conversions are cached (four at a time,\nleast-recently-used, object URLs revoked on eviction); `isQuickLookReady(key)`,\n`releaseQuickLook(key)` and `clearQuickLookCache()` let you drive that cache yourself.\n\nThe studio warms the cache in the background for whichever model the button would send, which\nis why the second tap of the day is instant. `placeInYourSpace()` still exists and still does\nboth halves in one call: reach for it when the USDZ is already cached, or when you are calling\nit from your own already-prepared button.\n\nExporting from the live scene rather than refetching the GLB is deliberate too: no second\ndownload, no second CORS round trip, and the person gets the pose and the size they are\nlooking at. `objectToUsdzBlob(object3D)` is exported if you want that for your own three.js\nscene.\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm test # 55 unit tests, no browser needed\nnpm run build # dist/ bundles\nnpm run build:site # docs/ (the GitHub Pages site)\nnpm run test:browser # 18 end-to-end checks in a real browser (needs Playwright)\nnpm run inspect # MCP Inspector against the local server\n```\n\nThe published site is committed under `docs/` and served by GitHub Pages from the `main`\nbranch. There is no CI workflow: `npm run build && npm run build:site`, commit, push.\n\n---\n\n## Licence and credits\n\nApache-2.0.\n\nThe bundle includes [three.js](https://threejs.org) (MIT) and\n[colyseus.js](https://colyseus.io) (MIT). The default model library is CC0 content from\n[Poly Haven](https://polyhaven.com), and the default generation and animation lanes are hosted\nby [three.ws](https://three.ws). None of them is required: every one is a URL you can change.\n",
"bytes": 18312,
"sha": "11766392205824a63fce394bf4a18a579f94e03ab708fc419c6ffd6f2911be98",
"repo_slug": "nirholas/3d-ar-studio",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_nirholas_3d_ar_studio_aa478529/readme"
}