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.

docs(tutorial): refresh the walkthrough figures and copy

nirholasd38cae06bf38
diff --git a/pages/tutorial.html b/pages/tutorial.html
index 657fe2148..3a3801932 100644
--- a/pages/tutorial.html
+++ b/pages/tutorial.html
@@ -1412,7 +1412,26 @@
// were already reserved, and nothing below them moves.
window.tutorialFigures?.mount(article);
- // Rewrite internal .md links and /docs/* refs so they navigate cleanly
+ // Rewrite the links a tutorial's markdown carries so they navigate
+ // cleanly from /tutorials/<slug>. Every relative href in the file was
+ // written against its real location, docs/tutorials/<slug>.md, so it
+ // has to be resolved against that path and not against the page URL:
+ // "../web-component.md" means docs/web-component.md, and reading it as
+ // a site path sends the reader nowhere. Three destinations exist.
+ const REPO = 'https://github.com/nirholas/three.ws/blob/main';
+ // docs/internal, docs/ops and docs/security stay in the repo and are
+ // filtered out of dist/docs by the copy-static-docs plugin in
+ // vite.config.js, so a tutorial citing one is citing source: send it to
+ // GitHub. Routing it to /docs/ would 404 in production only, because dev
+ // serves the whole docs/ tree off disk.
+ const REPO_ONLY_DOCS = new Set(['internal', 'ops', 'security']);
+ const isRepoOnlyDoc = (abs) =>
+ REPO_ONLY_DOCS.has(abs.slice('/docs/'.length).split('/')[0]);
+ const toRepo = (a, abs, section) => {
+ a.href = REPO + abs + (section ? '#' + section : '');
+ a.target = '_blank';
+ a.rel = 'noopener';
+ };
article.querySelectorAll('a[href]').forEach((a) => {
const h = a.getAttribute('href');
if (
@@ -1422,12 +1441,36 @@
h.startsWith('mailto:')
)
return;
- if (h.endsWith('.md')) {
- const rel = h.replace(/^\/docs\//, '').replace(/\.md$/, '');
- if (rel.startsWith('tutorials/')) {
- a.href = '/' + rel;
- } else {
- a.href = '/docs/#' + rel;
+ // "guide.md#section" is one link, not two: split the heading off so a
+ // cross-doc link that also targets a section reaches the doc AND
+ // scrolls, instead of failing the .md test and rendering unrewritten.
+ const hashAt = h.indexOf('#');
+ const target = hashAt === -1 ? h : h.slice(0, hashAt);
+ const section = hashAt === -1 ? '' : h.slice(hashAt + 1);
+ const base = location.origin + '/docs/tutorials/' + slug;
+ if (target.endsWith('.md')) {
+ const abs = new URL(target, base).pathname;
+ if (!abs.startsWith('/docs/') || isRepoOnlyDoc(abs)) {
+ toRepo(a, abs, section);
+ return;
+ }
+ const doc = abs.slice('/docs/'.length).replace(/\.md$/, '');
+ const path = doc.startsWith('tutorials/')
+ ? '/' + doc
+ : '/docs/' + doc;
+ a.href = path + (section ? '#' + section : '');
+ return;
+ }
+ // A relative link to repo source (../../src/agent-avatar.js,
+ // ../../public/animations/clips). Tutorials cite code constantly and
+ // this page serves tutorials, not the tree, so these resolve into
+ // site paths that do not exist. Send them to the file on GitHub.
+ // Site-absolute links (/pose, /docs/img/x.webp) are real routes and
+ // are left alone.
+ if (target.startsWith('.')) {
+ const abs = new URL(target, base).pathname;
+ if (!abs.startsWith('/docs/') || isRepoOnlyDoc(abs)) {
+ toRepo(a, abs, section);
}
}
});
diff --git a/public/cookbook/recipes/asset_pack.py b/public/cookbook/recipes/asset_pack.py
index a7feb9d05..9fdcc860c 100644
--- a/public/cookbook/recipes/asset_pack.py
+++ b/public/cookbook/recipes/asset_pack.py
@@ -13,7 +13,7 @@ each result, and writes a self-contained gallery you can open in a browser:
Usage:
python3 asset_pack.py "a clay flower pot" "a woven basket" "a brass watering can"
- python3 asset_pack.py --prompts prompts.txt --out ./garden-pack --workers 3
+ python3 asset_pack.py --prompts-file prompts.txt --out ./garden-pack --workers 3
Standard library only. No API key, no account.
diff --git a/public/demos-embed/forge.html b/public/demos-embed/forge.html
index 00046dd71..bf4bdac10 100644
--- a/public/demos-embed/forge.html
+++ b/public/demos-embed/forge.html
@@ -5,7 +5,7 @@
<meta name="viewport" content="width=device-width,initial-scale=1">
<title data-i18n="demos_embed_forge.meta_title">Forge · three.ws</title>
<meta name="robots" content="noindex">
- <script type="module" src="https://three.ws/dist-lib/agent-3d.js"></script>
+ <script type="module" src="/dist-lib/agent-3d.js"></script>
<style>
html, body {
background: transparent !important;
diff --git a/public/demos-embed/selfie.html b/public/demos-embed/selfie.html
index fef5612f4..a11a80bb2 100644
--- a/public/demos-embed/selfie.html
+++ b/public/demos-embed/selfie.html
@@ -5,7 +5,7 @@
<meta name="viewport" content="width=device-width,initial-scale=1">
<title data-i18n="demos_embed_selfie.meta_title">Selfie to Avatar · three.ws</title>
<meta name="robots" content="noindex">
- <script type="module" src="https://three.ws/dist-lib/agent-3d.js"></script>
+ <script type="module" src="/dist-lib/agent-3d.js"></script>
<style>
html, body {
background: transparent !important;
diff --git a/public/tutorial-figures.js b/public/tutorial-figures.js
index 480c355fd..2dcce2e02 100644
--- a/public/tutorial-figures.js
+++ b/public/tutorial-figures.js
@@ -7,6 +7,7 @@
* ![The Forge with a prompt typed in](figure:page:/forge)
* ![Michelle, the default rigged avatar](figure:glb:/avatars/michelle.glb)
* ![Drag to orbit the model](figure:live:/avatars/michelle.glb)
+ * ![The chest this recipe built](figure:img:/cookbook/posters/text-to-3d-cli.png)
*
* Left alone, marked turns that into <img src="figure:page:/forge">, and the
* browser immediately tries to fetch it: one guaranteed-failing request per
@@ -25,8 +26,15 @@
*
* Every kind has a real fallback, so a missing capture degrades instead of
* breaking: a model figure falls back to the interactive <model-viewer> of the
- * same GLB, and a page figure falls back to a link card that opens the real
- * page. A tutorial never renders a broken image icon.
+ * same GLB, a page figure falls back to a link card that opens the real page,
+ * and an `img` figure falls back to the committed file it names. A tutorial
+ * never renders a broken image icon.
+ *
+ * The kind list here must match KINDS in scripts/capture-tutorial-media.mjs.
+ * When it did not, every `figure:img:` in the cookbook was parsed as unknown,
+ * mountFigure returned null, and mount() removed the slot: four recipe posters
+ * and a tutorial's figures vanished from the rendered page with nothing in the
+ * console to say so.
*/
(function () {
'use strict';
@@ -78,7 +86,7 @@
var colon = body.indexOf(':');
if (colon === -1) return null;
var kind = body.slice(0, colon);
- if (kind !== 'page' && kind !== 'glb' && kind !== 'live') return null;
+ if (kind !== 'page' && kind !== 'glb' && kind !== 'live' && kind !== 'img') return null;
var rest = body.slice(colon + 1);
var q = rest.indexOf('?');
return {
@@ -138,7 +146,9 @@
function buildImage(record, alt) {
var frame = el('div', 'tfig-frame tfig-frame-img');
- frame.style.aspectRatio = record.width + ' / ' + record.height;
+ // An adopted `img` with no capture yet carries a src and nothing else, so
+ // the intrinsic-size box and the blur-up placeholder are both optional.
+ if (record.width && record.height) frame.style.aspectRatio = record.width + ' / ' + record.height;
if (record.placeholder) {
frame.style.backgroundImage = 'url("' + record.placeholder + '")';
frame.classList.add('is-loading');
@@ -146,8 +156,8 @@
var img = new Image();
img.src = record.src;
img.alt = alt;
- img.width = record.width;
- img.height = record.height;
+ if (record.width) img.width = record.width;
+ if (record.height) img.height = record.height;
img.loading = 'lazy';
img.decoding = 'async';
img.className = 'tfig-img';
@@ -192,14 +202,20 @@
var zoomable = null;
var kindBadge = null;
+ // An `img` names a file already committed under public/, so it has an
+ // honest fallback of its own: the committed file. Without this it would
+ // fall through to the page card and offer to "open the page" at a .png.
+ var shot = record;
+ if (!shot && directive.kind === 'img') shot = { src: directive.target };
+
if (directive.kind === 'live' || (!record && (directive.kind === 'glb' || directive.kind === 'live'))) {
var orbit = (record && record.orbit) || directive.params.get('orbit');
var frame = el('div', 'tfig-frame tfig-frame-live');
frame.appendChild(buildViewer(directive.target, orbit));
body.appendChild(frame);
kindBadge = badge(ICON_ORBIT, 'Drag to orbit');
- } else if (record && record.src) {
- var built = buildImage(record, alt);
+ } else if (shot && shot.src) {
+ var built = buildImage(shot, alt);
body.appendChild(built.frame);
zoomable = built;
kindBadge = badge(ICON_ZOOM, 'Click to enlarge');
@@ -231,7 +247,7 @@
if (kindBadge) caption.appendChild(kindBadge);
figure.appendChild(caption);
- return { figure: figure, alt: alt, record: record, kind: directive.kind, target: directive.target };
+ return { figure: figure, alt: alt, record: shot, kind: directive.kind, target: directive.target };
}
// ── Lightbox ───────────────────────────────────────────────────────────────