Skip to content

3D engine that AI agents drive

20.0 KB
Raw Blame
import './home.js';
import './documentation.css';
import guide from '../docs/guide.md?raw';
import { highlightCode } from './code-highlight.js';
import { createLiveExample, autoRunVisibleExamples } from './docs-live.js';
import { createApiReference } from './docs-api.js';
import { topicAliases, topicSlug, guideTopics, learnTopics, orderTopics } from './documentation-topics.js';
import { parseDocumentationHash } from './documentation-hash.js';

const learnSources = import.meta.glob('../docs/learn/*.md', { query: '?raw', import: 'default', eager: true });

const article = document.querySelector('#doc-article');
const topicNavigation = document.querySelector('#doc-toc');
const pageOutline = document.querySelector('#doc-outline');
const search = document.querySelector('#doc-search');
const results = document.querySelector('#doc-results');
const topicMenu = document.querySelector('#doc-topic-menu');
const copyPage = document.querySelector('#copy-doc-page');
const copyStatus = document.querySelector('#doc-copy-status');
const desktopTopics = matchMedia('(min-width: 1051px)');
topicMenu.open = desktopTopics.matches;
desktopTopics.addEventListener('change', () => { topicMenu.open = desktopTopics.matches; });

const iconPaths = {
  start: '<path d="m9 5 10 7-10 7V5Z"/>',
  cube: '<path d="m12 3 9 5v8l-9 5-9-5V8l9-5Z M3 8l9 5 9-5 M12 13v8"/>',
  world: '<circle cx="12" cy="12" r="9"/><path d="M3 12h18M12 3c3 3 3 15 0 18M12 3c-3 3-3 15 0 18"/>',
  motion: '<path d="M5 5h14v14H5z M9 9l6 3-6 3V9Z"/>',
  image: '<rect x="3" y="4" width="18" height="16" rx="3"/><path d="m3 16 5-5 4 4 3-3 6 6"/><circle cx="16" cy="8" r="1"/>',
  book: '<path d="M12 6c-3-2-6-2-9-1v14c3-1 6-1 9 1 3-2 6-2 9-1V5c-3-1-6-1-9 1Zm0 0v14"/>',
  copy: '<rect x="8" y="8" width="12" height="13" rx="2"/><path d="M15 8V3H3v12h5"/>',
  arrow: '<path d="M5 12h14m-6-6 6 6-6 6"/>',
  chevron: '<path d="m6 9 6 6 6-6"/>',
  tip: '<path d="M9 18h6M10 21h4M12 3a6 6 0 0 0-3.5 10.9c.6.5 1 1.2 1 2.1h5c0-.9.4-1.6 1-2.1A6 6 0 0 0 12 3Z"/>',
  note: '<circle cx="12" cy="12" r="9"/><path d="M12 11v6M12 7.5v.01"/>',
  warning: '<path d="M12 3 2 21h20L12 3Zm0 7v5m0 3v.01"/>',
  check: '<path d="m5 12 5 5 9-10"/>',
  terminal: '<rect x="3" y="4" width="18" height="16" rx="3"/><path d="m7 9 3 3-3 3M13 15h4"/>',
};

function icon(name) {
  return `<svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linejoin="round" stroke-linecap="round" aria-hidden="true">${iconPaths[name]}</svg>`;
}

function escapeHtml(value) {
  return value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character]));
}

function inlineText(value) {
  return escapeHtml(value)
    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
    .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (match, label, href) => {
      const external = /^https?:/.test(href) && new URL(href, 'https://crucible.codepawl.com').origin !== 'https://crucible.codepawl.com';
      return `<a href="${href}"${external ? ' rel="noopener"' : ''}>${label}</a>`;
    });
}

// Code spans are cut out first, so `**` or `[x](y)` inside code stays literal.
function inline(value) {
  return value.split(/(`[^`]+`)/g).map(piece => piece.startsWith('`') && piece.endsWith('`') && piece.length > 1
    ? `<code>${escapeHtml(piece.slice(1, -1))}</code>`
    : inlineText(piece)).join('');
}

const { groups, topics } = orderTopics([...guideTopics(guide), ...learnTopics(learnSources)].filter(topic => !(topic.id in topicAliases)));
let currentTopic;
let exampleStarter;

async function copyText(button, text, code) {
  try {
    await navigator.clipboard.writeText(text);
    button.innerHTML = `${icon('check')}${code ? 'Copied' : 'Page copied'}`;
    copyStatus.textContent = `✓ ${code ? 'Code' : 'Page Markdown'} copied to clipboard.`;
  } catch {
    if (code) {
      const range = document.createRange();
      range.selectNodeContents(code);
      const selection = getSelection();
      selection.removeAllRanges();
      selection.addRange(range);
      copyStatus.textContent = '⚠ Clipboard unavailable. Copy the selected code.';
    } else {
      const source = document.createElement('textarea');
      source.className = 'doc-copy-fallback';
      source.readOnly = true;
      source.setAttribute('aria-label', 'Page Markdown. Select and copy this text.');
      source.value = text;
      document.querySelector('.doc-copy-fallback')?.remove();
      copyStatus.after(source);
      source.focus();
      source.select();
      copyStatus.textContent = '⚠ Clipboard unavailable. Copy the selected Markdown below.';
    }
  }
  setTimeout(() => {
    button.innerHTML = `${icon('copy')}${code ? 'Copy code' : 'Copy page'}`;
  }, 2000);
}

const languages = { js: 'javascript', javascript: 'javascript', html: 'xml', xml: 'xml', sh: 'bash', bash: 'bash' };
const languageLabels = { javascript: 'JavaScript', xml: 'HTML', bash: 'Shell' };

function fenceInfo(block) {
  const [language = '', ...flags] = block.match(/^```([^\n]*)/)[1].trim().split(/\s+/);
  const options = {};
  for (const flag of flags) {
    const [key, value = true] = flag.split('=');
    options[key] = value;
  }
  return { language, options, source: block.replace(/^```[^\n]*\n/, '').replace(/```\s*$/, '').trimEnd() };
}

function codeBlock({ language: sourceLanguage, options, source }, title) {
  const language = languages[sourceLanguage];
  const label = options.file ?? (sourceLanguage === 'text' ? 'Output' : languageLabels[language] ?? (sourceLanguage || 'Plain text'));
  const container = document.createElement('div');
  container.className = sourceLanguage === 'text' ? 'code-block code-output' : 'code-block';
  const header = document.createElement('div');
  header.className = 'code-header';
  const languageLabel = document.createElement('span');
  languageLabel.className = 'code-language';
  languageLabel.innerHTML = sourceLanguage === 'text' ? `${icon('terminal')}${escapeHtml(label)}` : escapeHtml(label);
  header.append(languageLabel);
  const pre = document.createElement('pre');
  const code = document.createElement('code');
  code.className = language ? `hljs language-${language}` : 'hljs';
  code.innerHTML = language ? highlightCode(source, language) : escapeHtml(source);
  if (sourceLanguage !== 'text') {
    const button = document.createElement('button');
    button.className = 'copy-code';
    button.innerHTML = `${icon('copy')}Copy code`;
    button.setAttribute('aria-label', `Copy ${label} code from ${title}`);
    button.addEventListener('click', () => copyText(button, source, code));
    header.append(button);
  }
  pre.append(code);
  container.append(header, pre);
  return container;
}

// `npm install x` becomes one tab per package manager, the same choice the homepage offers.
const packageManagers = [
  { name: 'npm', command: command => command },
  { name: 'pnpm', command: command => command.replace(/^npm install/, 'pnpm add').replace(/^npm create/, 'pnpm create').replace(/^npm run /, 'pnpm ') },
  { name: 'yarn', command: command => command.replace(/^npm install/, 'yarn add').replace(/^npm create/, 'yarn create').replace(/ -- /, ' ').replace(/^npm run /, 'yarn ') },
  { name: 'bun', command: command => command.replace(/^npm install/, 'bun add').replace(/^npm create/, 'bun create').replace(/ -- /, ' ').replace(/^npm run /, 'bun run ') },
];
let chosenPackageManager = 'npm';
try { chosenPackageManager = localStorage.getItem('docs-package-manager') ?? 'npm'; } catch { /* Storage can be blocked. */ }

function installBlock(info, title) {
  const container = document.createElement('div');
  container.className = 'install-block';
  const tabs = document.createElement('div');
  tabs.className = 'install-tabs';
  tabs.setAttribute('role', 'group');
  tabs.setAttribute('aria-label', 'Package manager');
  const holder = document.createElement('div');
  function show(name) {
    const manager = packageManagers.find(entry => entry.name === name) ?? packageManagers[0];
    const source = info.source.split('\n').map(line => manager.command(line)).join('\n');
    holder.replaceChildren(codeBlock({ language: 'sh', options: {}, source }, title));
    for (const button of tabs.children) button.setAttribute('aria-pressed', String(button.dataset.manager === manager.name));
  }
  for (const manager of packageManagers) {
    const button = document.createElement('button');
    button.type = 'button';
    button.dataset.manager = manager.name;
    button.innerHTML = `<span class="package-logo package-logo-${manager.name}" aria-hidden="true"></span>${manager.name}`;
    button.addEventListener('click', () => {
      chosenPackageManager = manager.name;
      try { localStorage.setItem('docs-package-manager', manager.name); } catch { /* Storage can be blocked. */ }
      for (const block of document.querySelectorAll('.install-block')) block.showManager(manager.name);
    });
    tabs.append(button);
  }
  container.showManager = show;
  container.append(tabs, holder);
  show(chosenPackageManager);
  return container;
}

// A card list: one card per line, `Title | link | description | optional picture`.
function cardList(info) {
  const list = document.createElement('div');
  list.className = 'doc-cards';
  for (const line of info.source.split('\n').filter(Boolean)) {
    const [title, href, description = '', picture] = line.split('|').map(part => part.trim());
    const card = document.createElement('a');
    card.className = picture ? 'doc-card has-picture' : 'doc-card';
    card.href = href;
    card.innerHTML = `${picture ? `<img src="${escapeHtml(picture)}" alt="" loading="lazy" decoding="async">` : ''}<strong>${inline(title)} ${icon('arrow')}</strong><span>${inline(description)}</span>`;
    list.append(card);
  }
  return list;
}

function webglCheck() {
  const probe = document.createElement('canvas').getContext('webgl2');
  probe?.getExtension('WEBGL_lose_context')?.loseContext();
  const element = document.createElement('p');
  element.className = probe ? 'doc-check doc-check-ok' : 'doc-check doc-check-failed';
  element.setAttribute('role', 'status');
  element.innerHTML = probe
    ? `${icon('check')}<span>This browser supports WebGL2.</span>`
    : `${icon('warning')}<span>This browser has no WebGL2. Turn on hardware acceleration in its settings, or use a current Chrome, Edge, Firefox or Safari.</span>`;
  return element;
}

function renderFence(block, section) {
  const info = fenceInfo(block);
  if (info.options.live) {
    section.append(createLiveExample({ source: info.source, title: currentTopic.title, poster: info.options.poster, file: info.options.file }));
  } else if (info.options.install) {
    section.append(installBlock(info, currentTopic.title));
  } else if (info.language === 'cards') {
    section.append(cardList(info));
  } else if (info.language === 'api') {
    section.append(createApiReference());
  } else if (info.language === 'check') {
    section.append(webglCheck());
  } else {
    section.append(codeBlock(info, currentTopic.title));
  }
}

function figure(paragraph) {
  const match = paragraph.match(/^!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)$/);
  const [, alt, source, caption] = match;
  const element = document.createElement('figure');
  element.className = 'doc-figure';
  if (/\.(webm|mp4)$/.test(source)) {
    const still = matchMedia('(prefers-reduced-motion: reduce)').matches;
    element.innerHTML = `<video src="${source}" ${still ? 'controls' : 'autoplay loop'} muted playsinline preload="metadata" aria-label="${escapeHtml(alt)}"></video>`;
  } else {
    element.innerHTML = `<img src="${source}" alt="${escapeHtml(alt)}" loading="lazy" decoding="async">`;
  }
  if (caption) element.insertAdjacentHTML('beforeend', `<figcaption>${inline(caption)}</figcaption>`);
  return element;
}

// `> **Tip:** text` becomes a callout that leads with its own icon.
function callout(paragraph) {
  const text = paragraph.split('\n').map(line => line.replace(/^>\s?/, '')).join(' ');
  const kind = text.match(/^\*\*(Tip|Note|Warning):\*\*/)?.[1]?.toLowerCase() ?? 'note';
  const element = document.createElement('aside');
  element.className = `doc-callout doc-callout-${kind}`;
  element.innerHTML = `${icon(kind)}<p>${inline(text)}</p>`;
  return element;
}

function list(paragraph, ordered) {
  const element = document.createElement(ordered ? 'ol' : 'ul');
  const items = paragraph.split(/\n(?=\d+\.\s|[-*]\s)/);
  for (const line of items) {
    const item = document.createElement('li');
    item.innerHTML = inline(line.replace(/^(\d+\.|[-*])\s/, '').replace(/\n\s*/g, ' '));
    element.append(item);
  }
  return element;
}

function heading(paragraph) {
  const [, hashes, text] = paragraph.match(/^(#{2,4})\s+(.+)$/);
  const level = hashes.length;
  const element = document.createElement(`h${level}`);
  const step = level === 2 && text.match(/^(\d+)\.\s+(.+)$/);
  element.id = topicSlug(step ? step[2] : text);
  if (step) {
    element.className = 'doc-step';
    element.innerHTML = `<span class="doc-step-number" aria-hidden="true">${step[1]}</span><span>${inline(step[2])}</span>`;
    element.dataset.outline = step[2];
  } else {
    element.innerHTML = inline(text);
    element.dataset.outline = text;
  }
  return element;
}

function renderParagraph(paragraph, section) {
  if (/^#{2,4}\s/.test(paragraph) && !paragraph.includes('\n')) {
    section.append(heading(paragraph));
  } else if (paragraph.startsWith('|')) {
    const table = document.createElement('table');
    const rows = paragraph.split('\n').filter(row => !/^\|[\s:|-]+\|$/.test(row));
    table.innerHTML = rows.map((row, rowIndex) => `<tr>${row.split('|').slice(1, -1).map(cell => `<${rowIndex ? 'td' : 'th'}>${inline(cell.trim())}</${rowIndex ? 'td' : 'th'}>`).join('')}</tr>`).join('');
    const scroll = document.createElement('div');
    scroll.className = 'table-scroll';
    scroll.append(table);
    section.append(scroll);
  } else if (/^!\[[^\]]*\]\([^)]+\)$/.test(paragraph)) {
    section.append(figure(paragraph));
  } else if (paragraph.startsWith('>')) {
    section.append(callout(paragraph));
  } else if (/^\d+\.\s/.test(paragraph)) {
    section.append(list(paragraph, true));
  } else if (/^[-*]\s/.test(paragraph)) {
    section.append(list(paragraph, false));
  } else {
    const element = document.createElement('p');
    element.innerHTML = inline(paragraph.replace(/\n/g, ' '));
    section.append(element);
  }
}

function renderNavigation() {
  const words = search.value.toLowerCase().trim().split(/\s+/).filter(Boolean);
  const matching = topics.filter(topic => words.every(word => topic.raw.toLowerCase().includes(word) || topic.title.toLowerCase().includes(word)));
  topicNavigation.replaceChildren();
  for (const group of groups) {
    const members = matching.filter(topic => group.ids.includes(topic.id));
    if (!members.length) continue;
    const region = document.createElement('div');
    region.className = 'doc-topic-group';
    const groupHeading = document.createElement('h2');
    groupHeading.innerHTML = `${icon(group.icon)}${escapeHtml(group.title)}`;
    region.append(groupHeading);
    for (const topic of members) {
      const link = document.createElement('a');
      link.href = `#${topic.id}`;
      link.textContent = topic.title;
      if (topic === currentTopic) link.setAttribute('aria-current', 'page');
      link.addEventListener('click', () => {
        if (!desktopTopics.matches) topicMenu.open = false;
        if (location.hash === link.hash) article.focus();
      });
      region.append(link);
    }
    topicNavigation.append(region);
  }
  results.textContent = words.length ? matching.length ? `${matching.length} ${matching.length === 1 ? 'topic' : 'topics'} found` : '⌕ No matching topics. Try camera, memory, or agents.' : '';
}

function renderOutline(section) {
  const headings = [...section.querySelectorAll('h2[id]')];
  pageOutline.replaceChildren();
  pageOutline.hidden = headings.length < 2;
  if (pageOutline.hidden) return;
  const title = document.createElement('h2');
  title.textContent = 'On this page';
  pageOutline.append(title);
  for (const element of headings) {
    const link = document.createElement('a');
    link.href = `#${currentTopic.id}/${element.id}`;
    link.textContent = element.dataset.outline.replace(/`/g, '');
    if (element.classList.contains('doc-step')) link.prepend(`${element.querySelector('.doc-step-number').textContent}. `);
    pageOutline.append(link);
  }
}

function parseHash() {
  const { topic: requestedTopic, section: requestedSection } = parseDocumentationHash(location.hash);
  return { hashTopic: requestedTopic, requestedTopic: topicAliases[requestedTopic] ?? requestedTopic, requestedSection };
}

function stopExamples() {
  exampleStarter?.disconnect();
  for (const example of article.querySelectorAll('.live-example')) example.liveExample.dispose();
}

function openTopic(focus = false) {
  const { hashTopic, requestedTopic, requestedSection } = parseHash();
  const sameTopic = currentTopic && currentTopic.id === requestedTopic;
  if (sameTopic && requestedSection) {
    document.getElementById(requestedSection)?.scrollIntoView({ behavior: matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth' });
    return;
  }
  stopExamples();
  currentTopic = topics.find(topic => topic.id === requestedTopic) ?? topics.find(topic => topic.id === 'introduction');
  // Compare the raw hash, so an alias such as #getting-started is rewritten to the topic it names.
  if (hashTopic !== currentTopic.id) history.replaceState(null, '', `#${currentTopic.id}`);
  const section = document.createElement('section');
  section.id = currentTopic.id;
  const title = document.createElement('h1');
  title.textContent = currentTopic.title;
  section.append(title);
  const content = currentTopic.raw.replace(/^#{1,2} [^\n]*\n/, '').trim().replace(/\r\n/g, '\n');
  for (const block of content.split(/(```[^\n]*\n[\s\S]*?```)/g)) {
    if (block.startsWith('```')) renderFence(block, section);
    else for (const paragraph of block.trim().split(/\n\s*\n/)) if (paragraph.trim()) renderParagraph(paragraph.trim(), section);
  }
  article.replaceChildren(section);
  const index = topics.indexOf(currentTopic);
  const pagination = document.createElement('nav');
  pagination.className = 'doc-pagination';
  pagination.setAttribute('aria-label', 'Adjacent topics');
  for (const [topic, direction] of [[topics[index - 1], 'Previous'], [topics[index + 1], 'Next']]) {
    if (!topic) continue;
    const link = document.createElement('a');
    link.href = `#${topic.id}`;
    link.className = `doc-pagination-${direction.toLowerCase()}`;
    link.innerHTML = `<span>${direction}</span><strong>${escapeHtml(topic.title)} ${direction === 'Next' ? icon('arrow') : ''}</strong>`;
    pagination.append(link);
  }
  article.append(pagination);
  document.querySelector('#doc-topic-name').textContent = currentTopic.title;
  document.title = `${currentTopic.title} · Crucible documentation`;
  copyStatus.textContent = '';
  document.querySelector('.doc-copy-fallback')?.remove();
  copyPage.innerHTML = `${icon('copy')}Copy page`;
  renderNavigation();
  renderOutline(section);
  exampleStarter = autoRunVisibleExamples(article);
  section.addEventListener('api-ready', () => {
    renderOutline(section);
    if (requestedSection) document.getElementById(requestedSection)?.scrollIntoView();
  }, { once: true });
  if (requestedSection) {
    requestAnimationFrame(() => document.getElementById(requestedSection)?.scrollIntoView());
  } else if (focus) {
    article.focus({ preventScroll: true });
    window.scrollTo({ top: 0 });
    for (const animation of article.getAnimations()) animation.cancel();
    if (!matchMedia('(prefers-reduced-motion: reduce)').matches) {
      article.animate([{ opacity:0.6, transform:'translateY(6px)' }, { opacity:1, transform:'translateY(0)' }], { duration:170, easing:'cubic-bezier(.2,0,0,1)' });
    }
  }
}

copyPage.innerHTML = `${icon('copy')}Copy page`;
document.querySelector('#doc-topic-menu summary > :last-child').innerHTML = icon('chevron');
copyPage.addEventListener('click', () => copyText(copyPage, currentTopic.raw));
search.addEventListener('input', () => {
  if (search.value.trim()) topicMenu.open = true;
  renderNavigation();
});
window.addEventListener('hashchange', () => openTopic(true));
openTopic();