meshpad 0.0.0 → 0.1.0

package/src/hud.js

@@ -0,0 +1,198 @@
+let hudId = 0;
+
+const icon = (paths) => `<svg viewBox="0 0 24 24" aria-hidden="true"><g class="meshpad-icon-outline">${paths}</g>${paths}</svg>`;
+const heart = icon('<path d="M12 21 3.4 12.6a5.5 5.5 0 0 1 7.8-7.8l.8.8.8-.8a5.5 5.5 0 0 1 7.8 7.8Z"/>');
+const difficultyLabels = { normal: 'Normal', hard: 'Hard', 'very-hard': 'Very hard', 'ultra-hard': 'Ultra hard' };
+
+export function createHUD(root, levels, actions) {
+  const titleId = `meshpad-result-title-${++hudId}`;
+  const layer = document.createElement('div');
+  layer.className = 'meshpad-hud';
+  layer.innerHTML = `
+    <header class="meshpad-top">
+      <nav aria-label="Level navigation">
+        <h1 aria-live="polite" aria-atomic="true"><button type="button" class="meshpad-level-chooser" data-action="levels" aria-haspopup="dialog" aria-expanded="false"><span class="meshpad-level-label"></span>${icon('<path d="m6 9 6 6 6-6"/>')}</button></h1>
+        <div class="meshpad-resource" hidden></div>
+        <div class="meshpad-hud-actions">
+          <button type="button" data-action="restart" aria-label="Restart level">
+            ${icon('<path d="M4 10a8 8 0 1 1 1.8 7M4 4v6h6"/>')}
+          </button>
+        </div>
+      </nav>
+    </header>
+    <section class="meshpad-overlay" hidden>
+      <div class="meshpad-panel" role="dialog" aria-modal="true" aria-labelledby="${titleId}" tabindex="-1">
+        <div class="meshpad-panel-heading">
+          <h2 id="${titleId}"></h2>
+          <button type="button" class="meshpad-close" aria-label="Close levels list" hidden>${icon('<path d="m6 6 12 12M18 6 6 18"/>')}</button>
+        </div>
+        <p class="meshpad-result-detail" hidden></p>
+        <div class="meshpad-levels" hidden></div>
+        <button type="button" class="meshpad-primary"><span class="meshpad-button-label"></span></button>
+        <button type="button" class="meshpad-secondary" hidden><span class="meshpad-button-label">Retry</span></button>
+      </div>
+    </section>`;
+  root.append(layer);
+  const find = (selector) => layer.querySelector(selector);
+  const top = find('.meshpad-top');
+  const levelLabel = find('.meshpad-level-label');
+  const levelsButton = find('[data-action="levels"]');
+  const restart = find('[data-action="restart"]');
+  const resource = find('.meshpad-resource');
+  const overlay = find('.meshpad-overlay');
+  const panel = find('.meshpad-panel');
+  const title = find('h2');
+  const closeButton = find('.meshpad-close');
+  const detail = find('.meshpad-result-detail');
+  const levelList = find('.meshpad-levels');
+  levelList.id = `meshpad-levels-${hudId}`;
+  levelsButton.setAttribute('aria-controls', levelList.id);
+  const primary = find('.meshpad-primary');
+  const secondary = find('.meshpad-secondary');
+  const primaryLabel = find('.meshpad-button-label');
+  const listeners = new AbortController();
+  const listen = (element, event, callback) => element.addEventListener(event, callback, { signal: listeners.signal });
+  let index = 0;
+  let returnFocus;
+  let showingLevels = false;
+  let resultAction = actions.restart;
+  let resourceKey;
+  const hideResult = () => {
+    const restoreFocus = panel.contains(document.activeElement);
+    overlay.hidden = true;
+    levelsButton.setAttribute('aria-expanded', 'false');
+    top.inert = false;
+    if (restoreFocus) {
+      const target = top.contains(returnFocus) && !returnFocus.disabled ? returnFocus : restart;
+      target.focus({ preventScroll: true });
+    }
+  };
+  const show = (focusTarget = primary) => {
+    if (overlay.hidden) returnFocus = document.activeElement;
+    top.inert = true;
+    overlay.hidden = false;
+    focusTarget.focus({ preventScroll: true });
+  };
+  const closeLevels = () => {
+    showingLevels = false;
+    hideResult();
+    actions.closeLevels();
+  };
+  listen(restart, 'click', actions.restart);
+  listen(primary, 'click', () => resultAction());
+  listen(secondary, 'click', actions.restart);
+  listen(closeButton, 'click', closeLevels);
+  listen(levelsButton, 'click', () => {
+    actions.openLevels();
+    showingLevels = true;
+    panel.dataset.view = 'levels';
+    overlay.dataset.view = 'levels';
+    levelsButton.setAttribute('aria-expanded', 'true');
+    title.textContent = 'Levels';
+    detail.hidden = true;
+    levelList.hidden = false;
+    secondary.hidden = true;
+    primary.hidden = true;
+    closeButton.hidden = false;
+    show(closeButton);
+    const selected = levelList.querySelector('[aria-current]');
+    selected?.focus({ preventScroll: true });
+    selected?.scrollIntoView({ block: 'nearest' });
+  });
+  levels.forEach((level, levelIndex) => {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.setAttribute('aria-label', `Level ${levelIndex + 1}${level.name ? `: ${level.name}` : ''}`);
+    const info = document.createElement('span');
+    info.className = 'meshpad-level-info';
+    const number = document.createElement('span');
+    number.className = 'meshpad-level-number';
+    number.textContent = `Level ${levelIndex + 1}`;
+    info.append(number);
+    if (level.name) {
+      const name = document.createElement('span');
+      name.className = 'meshpad-level-name';
+      name.textContent = level.name;
+      name.title = level.name;
+      info.append(name);
+    }
+    const difficulty = document.createElement('span');
+    difficulty.id = `meshpad-difficulty-${hudId}-${levelIndex}`;
+    difficulty.className = 'meshpad-difficulty';
+    difficulty.dataset.difficulty = level.difficulty ?? 'normal';
+    difficulty.textContent = difficultyLabels[difficulty.dataset.difficulty];
+    button.setAttribute('aria-describedby', difficulty.id);
+    button.append(info, difficulty);
+    listen(button, 'click', () => actions.loadLevel(levelIndex));
+    levelList.append(button);
+  });
+  listen(panel, 'keydown', (event) => {
+    if (event.key === 'Escape' && showingLevels) { event.preventDefault(); closeLevels(); }
+    if (event.key === 'Tab') {
+      const buttons = [...panel.querySelectorAll('button')].filter((button) => button.offsetParent !== null && !button.disabled);
+      const first = buttons[0];
+      const last = buttons.at(-1);
+      if (event.shiftKey && (document.activeElement === first || document.activeElement === panel)) {
+        event.preventDefault(); last.focus();
+      } else if (!event.shiftKey && (document.activeElement === last || document.activeElement === panel)) {
+        event.preventDefault(); first.focus();
+      }
+    }
+  });
+  const updateResource = (failure) => {
+    const { type, remaining, initial } = failure;
+    resource.hidden = type === 'default';
+    top.dataset.mode = type;
+    if (type === 'default') { resourceKey = undefined; return; }
+    const seconds = Math.ceil(Math.max(0, remaining - 1e-9));
+    const display = type === 'time' ? `${String(Math.floor(seconds / 60)).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}` : String(remaining);
+    const key = `${type}:${initial}:${display}`;
+    if (resourceKey === key) return;
+    resourceKey = key;
+    resource.className = `meshpad-resource meshpad-resource-${type}`;
+    resource.dataset.low = String(type === 'hearts' ? remaining <= 1 : remaining <= (type === 'time' ? 10 : 3));
+    resource.setAttribute('role', type === 'time' ? 'timer' : 'img');
+    resource.setAttribute('aria-label', type === 'hearts' ? `${remaining} of ${initial} hearts` : type === 'time' ? `${display} remaining` : `${remaining} moves remaining`);
+    if (type === 'hearts') {
+      resource.innerHTML = Array.from({ length: initial }, (_, i) => `<span class="meshpad-heart${i >= remaining ? ' meshpad-heart-empty' : ''}" aria-hidden="true">${heart}</span>`).join('');
+    } else {
+      resource.innerHTML = `<span class="meshpad-resource-label">${type === 'time' ? 'Time' : 'Moves'}</span><span class="meshpad-resource-value">${display}</span>`;
+    }
+  };
+  return {
+    hideResult,
+    resource: updateResource,
+    reset(nextIndex, failure) {
+      index = nextIndex;
+      showingLevels = false;
+      levelLabel.textContent = `Level ${index + 1}`;
+      levelsButton.setAttribute('aria-label', `Level ${index + 1}, choose level`);
+      [...levelList.children].forEach((button, i) => {
+        if (i === index) button.setAttribute('aria-current', 'true');
+        else button.removeAttribute('aria-current');
+      });
+      updateResource(failure);
+      hideResult();
+    },
+    result(status, failure) {
+      showingLevels = false;
+      panel.dataset.view = 'result';
+      overlay.dataset.view = 'result';
+      primary.hidden = false;
+      closeButton.hidden = true;
+      levelsButton.setAttribute('aria-expanded', 'false');
+      levelList.hidden = true;
+      const won = status === 'won';
+      const hasNext = won && index < levels.length - 1;
+      const canPlayOn = status === 'failed' && failure && failure.type !== 'default';
+      title.textContent = won ? 'Level complete!' : status === 'error' ? 'Something went wrong' : failure?.remaining === 0 ? ({ hearts: 'Out of hearts!', time: 'Time’s up!', moves: 'Out of moves!' }[failure.type]) : 'Try again!';
+      detail.hidden = !canPlayOn;
+      if (canPlayOn) detail.textContent = failure.type === 'hearts' ? 'Refill your hearts and keep going.' : `Keep going with +${failure.playOnAmount} ${failure.type === 'time' ? 'seconds' : 'moves'}.`;
+      primaryLabel.textContent = canPlayOn ? 'Play on' : hasNext ? 'Next level' : won ? 'Play again' : 'Retry';
+      secondary.hidden = !canPlayOn;
+      resultAction = canPlayOn ? actions.playOn : hasNext ? actions.next : actions.restart;
+      show();
+    },
+    dispose() { listeners.abort(); layer.remove(); },
+  };
+}

package/src/styles.css

@@ -0,0 +1,208 @@
+@import url('https://fonts.googleapis.com/css2?family=Baloo+2:wght@600;700;800&display=swap');
+
+:root {
+  font-family: "Baloo 2", "Arial Rounded MT Bold", ui-rounded, system-ui, sans-serif;
+  color: #fff4e5;
+  background: #19163a;
+  color-scheme: dark;
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+  -webkit-tap-highlight-color: transparent;
+}
+html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; overscroll-behavior: none; }
+body { position: fixed; inset: 0; }
+.meshpad-root, .meshpad-root * { box-sizing: border-box; }
+.meshpad-root {
+  --meshpad-accent: #f9c94b;
+  --meshpad-text-outline: #362668;
+  --meshpad-text-shadow: #120f2c;
+  font-family: "Baloo 2", "Arial Rounded MT Bold", ui-rounded, system-ui, sans-serif;
+  color: #fff4e5;
+  position: relative;
+  width: 100%; height: 100dvh;
+  overflow: hidden; isolation: isolate;
+  touch-action: none; overscroll-behavior: none;
+  user-select: none; -webkit-user-select: none; -webkit-touch-callout: none;
+}
+.meshpad-stage {
+  position: absolute; top: 50%; left: 50%;
+  width: 100%; height: 100%; max-width: 540px;
+  transform: translate(-50%, -50%);
+  overflow: hidden; background: #221e4e;
+  container-type: inline-size;
+}
+.meshpad-canvas { position: absolute; inset: 0; display: block; width: 100%; height: 100%; outline: none; touch-action: none; }
+.meshpad-hud { position: absolute; inset: 0; pointer-events: none; }
+.meshpad-top {
+  position: absolute; top: 0; left: 0; right: 0;
+  padding: max(16px, env(safe-area-inset-top)) max(12px, env(safe-area-inset-left), env(safe-area-inset-right)) 12px;
+}
+.meshpad-top nav {
+  display: grid; grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr); align-items: center; gap: 8px;
+  pointer-events: auto;
+  padding: 8px; border: 1px solid #7770b34d; border-radius: 20px;
+  background: #302a60f2; box-shadow: 0 3px 0 #17133266;
+}
+.meshpad-top h1 {
+  grid-column: 1; justify-self: start; margin: 0; min-width: 0; white-space: nowrap;
+  font-size: 18px; font-weight: 800; line-height: 1.2;
+  text-align: left; font-variant-numeric: tabular-nums;
+}
+.meshpad-hud-actions { grid-column: 3; justify-self: end; display: flex; align-items: center; gap: 6px; }
+.meshpad-root button {
+  display: grid; place-items: center;
+  min-width: 44px; min-height: 44px; padding: 10px;
+  border: 1px solid #ffffff1f; border-radius: 12px;
+  font: inherit; font-weight: 800; line-height: 1.2; color: #fff4e5;
+  background: #514795; box-shadow: 0 3px 0 #211c49;
+  appearance: none; -webkit-appearance: none;
+  touch-action: manipulation; cursor: pointer;
+}
+.meshpad-top button { flex: 0 0 44px; pointer-events: auto; }
+.meshpad-top .meshpad-level-chooser {
+  display: flex; align-items: center; gap: 8px; padding: 6px 10px; white-space: nowrap;
+  font-size: inherit;
+}
+.meshpad-level-label { line-height: 1.2; word-spacing: 2px; }
+.meshpad-level-label, .meshpad-resource-label, .meshpad-resource-value,
+.meshpad-panel h2, .meshpad-result-detail, .meshpad-button-label,
+.meshpad-level-number, .meshpad-level-name, .meshpad-difficulty {
+  -webkit-text-stroke: 2px var(--meshpad-text-outline);
+  paint-order: stroke fill;
+  text-shadow: 0 2px 0 var(--meshpad-text-shadow);
+}
+.meshpad-level-label, .meshpad-resource-value, .meshpad-panel h2, .meshpad-button-label, .meshpad-level-number {
+  -webkit-text-stroke-width: 3px;
+  text-shadow: 0 3px 0 var(--meshpad-text-shadow);
+}
+.meshpad-resource-label, .meshpad-level-name, .meshpad-difficulty {
+  -webkit-text-stroke-width: 1px;
+  text-shadow: 0 1px 0 var(--meshpad-text-shadow);
+}
+.meshpad-top .meshpad-level-chooser svg { width: 12px; height: 12px; flex-shrink: 0; stroke-width: 3; }
+.meshpad-level-chooser[aria-expanded="true"] svg { transform: rotate(180deg); }
+.meshpad-top button svg, .meshpad-close svg {
+  display: block; width: 22px; height: 22px;
+  fill: none; stroke: currentColor; stroke-width: 3.5; stroke-linecap: round; stroke-linejoin: round;
+  filter: drop-shadow(0 3px 0 var(--meshpad-text-shadow));
+}
+.meshpad-icon-outline { stroke: var(--meshpad-text-outline); stroke-width: 6.5; }
+.meshpad-resource {
+  grid-column: 2; display: flex; align-items: center; justify-content: center;
+  min-width: 66px; height: 44px; padding: 3px 10px;
+  border: 1px solid #8c82c04d; border-radius: 11px; background: #211c49;
+  font-variant-numeric: tabular-nums;
+}
+.meshpad-resource-time, .meshpad-resource-moves { flex-direction: column; gap: 2px; }
+.meshpad-resource-label { font-size: 11px; line-height: 1; font-weight: 700; color: #c8bfeb; }
+.meshpad-resource-value { font-size: 20px; line-height: 1.1; font-weight: 800; }
+.meshpad-resource-hearts { gap: 3px; padding: 3px 8px; }
+.meshpad-heart { display: flex; width: 18px; color: #ff7d94; }
+.meshpad-heart svg { width: 100%; height: 20px; fill: currentColor; stroke: #ffffff33; stroke-width: 1; filter: drop-shadow(0 1px 0 var(--meshpad-text-shadow)); }
+.meshpad-heart .meshpad-icon-outline { stroke-width: 3px; }
+.meshpad-heart-empty { color: #50466f; }
+.meshpad-resource[data-low="true"] .meshpad-resource-value { color: #ff9bad; }
+.meshpad-root button:active:not(:disabled) { transform: translateY(2px); box-shadow: 0 1px 0 #211c49; }
+.meshpad-root button:disabled { opacity: .3; cursor: default; }
+.meshpad-root button:focus-visible { outline: 3px solid var(--meshpad-accent); outline-offset: 3px; }
+.meshpad-overlay { position: absolute; inset: 0; display: grid; place-items: center; padding: 20px; background: #19163acb; pointer-events: auto; }
+.meshpad-panel {
+  width: 100%; max-width: 300px; max-height: 100%; overflow-y: auto; padding: 26px 20px 22px;
+  border: 1px solid #8c82c0; border-radius: 24px; background: #302a60;
+  box-shadow: 0 5px 0 #120f2c66;
+  text-align: center; outline: none; overscroll-behavior: contain; touch-action: pan-y;
+}
+.meshpad-panel h2 { margin: 0 0 20px; font-size: 28px; font-weight: 800; line-height: 1.15; }
+.meshpad-result-detail { margin: -6px 0 20px; color: #d2c9ed; font-size: 16px; line-height: 1.4; }
+.meshpad-panel .meshpad-primary {
+  --meshpad-text-outline: #956000;
+  --meshpad-text-shadow: #6d4100;
+  width: 100%; font-size: 20px; color: #fff4db; background: var(--meshpad-accent);
+  border-color: #ffe49b; box-shadow: 0 3px 0 #aa792a;
+}
+.meshpad-panel .meshpad-primary:active { box-shadow: 0 1px 0 #aa792a; }
+.meshpad-panel .meshpad-secondary { width: 100%; margin-top: 12px; font-size: 17px; }
+.meshpad-overlay[data-view="levels"] { padding: 0; background: #302a60; }
+.meshpad-panel[data-view="levels"] {
+  display: flex; flex-direction: column; gap: 16px;
+  width: 100%; height: 100%; max-width: none; overflow: hidden;
+  padding: max(16px, env(safe-area-inset-top)) max(16px, env(safe-area-inset-left), env(safe-area-inset-right)) max(16px, env(safe-area-inset-bottom));
+  border: 0; border-radius: 0; box-shadow: none;
+}
+.meshpad-panel[data-view="levels"] .meshpad-panel-heading {
+  flex: 0 0 auto; display: grid; grid-template-columns: 44px minmax(0, 1fr) 44px; align-items: center; gap: 12px;
+}
+.meshpad-panel[data-view="levels"] h2 { grid-column: 2; margin: 0; text-align: center; }
+.meshpad-panel[data-view="levels"] .meshpad-close { grid-column: 3; }
+.meshpad-close { flex: 0 0 44px; }
+.meshpad-levels {
+  flex: 1; min-height: 0; display: flex; flex-direction: column; gap: 8px; margin: 0 -4px; padding: 4px;
+  overflow-y: auto; overscroll-behavior: contain; touch-action: pan-y;
+  scrollbar-width: thin; scrollbar-color: #8c82c0 #211c49;
+}
+.meshpad-levels button {
+  flex: 0 0 auto; width: 100%; display: flex; align-items: center; justify-content: space-between;
+  gap: 12px; min-height: 64px; padding: 12px 14px; text-align: left;
+}
+.meshpad-levels button:first-child { margin-top: auto; }
+.meshpad-levels button:last-child { margin-bottom: auto; }
+.meshpad-level-info { display: flex; flex-direction: column; gap: 4px; min-width: 0; }
+.meshpad-level-number { font-size: 19px; line-height: 1.2; word-spacing: 2px; }
+.meshpad-level-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 13px; font-weight: 600; color: #d2c9ed; }
+.meshpad-difficulty { flex-shrink: 0; padding: 5px 8px; border-radius: 8px; font-size: 12px; line-height: 1.2; color: #b6efcf; background: #233e3a; }
+.meshpad-difficulty[data-difficulty="hard"] { color: #ffe6a0; background: #59451d; }
+.meshpad-difficulty[data-difficulty="very-hard"] { color: #ffd1a8; background: #653a27; }
+.meshpad-difficulty[data-difficulty="ultra-hard"] { color: #ffc1d8; background: #602b4c; }
+.meshpad-levels [aria-current] { border-color: var(--meshpad-accent); background: #65538f; }
+.meshpad-root [hidden] { display: none !important; }
+@supports not (paint-order: stroke fill) {
+  .meshpad-level-label, .meshpad-resource-label, .meshpad-resource-value,
+  .meshpad-panel h2, .meshpad-result-detail, .meshpad-button-label,
+  .meshpad-level-number, .meshpad-level-name, .meshpad-difficulty {
+    -webkit-text-stroke: 0;
+    text-shadow: -1px -1px 0 var(--meshpad-text-outline), 1px -1px 0 var(--meshpad-text-outline), -1px 1px 0 var(--meshpad-text-outline), 1px 1px 0 var(--meshpad-text-outline), 0 3px 0 var(--meshpad-text-shadow);
+  }
+}
+/* Viewport fallback also supports browsers without container queries. */
+@media (max-width: 340px) {
+  .meshpad-top { padding-inline: 8px; }
+  .meshpad-top nav { gap: 6px; padding: 6px; }
+  .meshpad-top h1 { font-size: 16px; }
+  .meshpad-top .meshpad-level-chooser { gap: 6px; padding-inline: 8px; }
+  .meshpad-resource-hearts { gap: 2px; padding-inline: 6px; }
+  .meshpad-heart { width: 14px; }
+}
+@media (max-height: 500px) {
+  .meshpad-top { padding: max(8px, env(safe-area-inset-top)) max(4px, env(safe-area-inset-left), env(safe-area-inset-right)) 8px; }
+  .meshpad-top nav { gap: 3px; padding: 4px 2px; border-radius: 16px; }
+  .meshpad-top h1 { font-size: 13px; }
+  .meshpad-top .meshpad-level-chooser { gap: 4px; padding-inline: 3px; }
+  .meshpad-level-label { word-spacing: 1px; }
+  .meshpad-top .meshpad-level-chooser svg { width: 10px; height: 10px; }
+  .meshpad-resource { min-width: 54px; padding-inline: 5px; }
+  .meshpad-resource-hearts { gap: 1px; padding-inline: 3px; }
+  .meshpad-heart { width: 8px; }
+  .meshpad-resource-value { font-size: 17px; }
+  .meshpad-hud-actions { gap: 3px; }
+}
+@container (max-width: 300px) {
+  .meshpad-top { padding-inline: 4px; }
+  .meshpad-top nav { gap: 3px; padding: 4px 2px; border-radius: 16px; }
+  .meshpad-top h1 { font-size: 13px; }
+  .meshpad-top .meshpad-level-chooser { gap: 4px; padding-inline: 3px; }
+  .meshpad-level-label { word-spacing: 1px; }
+  .meshpad-top .meshpad-level-chooser svg { width: 10px; height: 10px; }
+  .meshpad-resource { min-width: 54px; padding-inline: 5px; }
+  .meshpad-resource-hearts { gap: 1px; padding-inline: 3px; }
+  .meshpad-heart { width: 8px; }
+  .meshpad-resource-value { font-size: 17px; }
+  .meshpad-hud-actions { gap: 3px; }
+}
+@media (max-height: 460px), (max-width: 260px) {
+  .meshpad-top button { flex-basis: 32px; min-width: 32px; min-height: 36px; padding: 6px; }
+  .meshpad-top button svg { width: 18px; height: 18px; }
+}
+@container (max-width: 260px) {
+  .meshpad-top button { flex-basis: 32px; min-width: 32px; min-height: 36px; padding: 6px; }
+  .meshpad-top button svg { width: 18px; height: 18px; }
+}

package/src/three.js

@@ -0,0 +1 @@
+export * from 'three';

package/src/tooling.js

@@ -0,0 +1,128 @@
+import { readFile, access, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer, build, preview } from 'vite';
+import { checkProject, resolveProject, watchProject } from './typecheck.js';
+
+export const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+export const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+const escapeHTML = (text) => text.replace(/[&<>"']/g, (character) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[character]);
+
+export function shell(entry, title = 'Meshpad') {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover" />
+    <meta name="theme-color" content="#221e4e" />
+    <meta name="format-detection" content="telephone=no, date=no, address=no, email=no" />
+    <meta name="mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+    <link rel="icon" href="data:," />
+    <title>${escapeHTML(title)}</title>
+  </head>
+  <body><script type="module" src="${escapeHTML(entry)}"></script></body>
+</html>`;
+}
+
+export async function projectConfig(entry = 'game.ts', options = {}) {
+  // Vite canonicalizes roots; the virtual HTML entry must use the same path.
+  const { root, source } = await resolveProject(entry, options);
+  const index = resolve(root, 'index.html');
+  const html = shell(`/@fs/${source.replaceAll('\\', '/')}`, options.title);
+  const outDir = resolve(root, options.outDir ?? 'dist');
+  const outPath = relative(root, outDir);
+  const sourceInOutput = relative(outDir, source);
+  if (!outPath || outPath.startsWith('..') || isAbsolute(outPath) || ['public', 'node_modules', '.git'].includes(outPath.split(/[\\/]/)[0]) || (!sourceInOutput.startsWith('..') && !isAbsolute(sourceInOutput))) {
+    throw new Error('Output must be a separate directory inside the project, away from the game source, public, node_modules, and .git.');
+  }
+  return {
+    root, configFile: false, base: './', publicDir: resolve(root, 'public'), logLevel: options.logLevel ?? 'info',
+    appType: 'spa',
+    resolve: {
+      // Also supports working on Meshpad's own example without installing itself.
+      alias: [
+        { find: /^meshpad$/, replacement: resolve(packageRoot, 'index.js') },
+        { find: /^meshpad\/three$/, replacement: resolve(packageRoot, 'src/three.js') },
+        { find: /^meshpad\/addons$/, replacement: resolve(packageRoot, 'src/addons.js') },
+      ],
+      dedupe: ['three'],
+    },
+    plugins: [{
+      name: 'meshpad-shell', enforce: 'pre',
+      resolveId(id) { if (id === index) return index; },
+      load(id) { if (id === index) return html; },
+      configureServer(server) {
+        server.middlewares.use(async (req, res, next) => {
+          const pathname = req.url?.split('?')[0];
+          if (pathname !== '/' && pathname !== '/index.html') return next();
+          try {
+            const result = await server.transformIndexHtml(req.url, html);
+            res.statusCode = 200; res.setHeader('Content-Type', 'text/html'); res.end(result);
+          } catch (error) { next(error); }
+        });
+      },
+    }],
+    optimizeDeps: { entries: [source] },
+    server: {
+      host: options.host ?? '127.0.0.1', port: options.port ?? 5173,
+      fs: { allow: [root, packageRoot, dirname(source)] },
+    },
+    preview: { host: options.host ?? '127.0.0.1', port: options.port ?? 4173 },
+    build: {
+      outDir, emptyOutDir: true,
+      target: ['es2022', 'safari15', 'chrome96'],
+      rolldownOptions: { input: index },
+      chunkSizeWarningLimit: 650,
+    },
+  };
+}
+
+export async function startDev(entry, options = {}) {
+  const config = await projectConfig(entry, options);
+  const { source } = await checkProject(entry, { root: config.root });
+  const server = await createServer(config);
+  watchProject(server, source, config.root);
+  try { await server.listen(); } catch (error) { await server.close(); throw error; }
+  return server;
+}
+
+export async function buildProject(entry, options = {}) {
+  const config = await projectConfig(entry, options);
+  await checkProject(entry, { root: config.root });
+  return build(config);
+}
+
+export async function previewProject(options = {}) {
+  const root = resolve(options.root ?? process.cwd());
+  const outDir = resolve(root, options.outDir ?? 'dist');
+  try { await access(resolve(outDir, 'index.html')); } catch { throw new Error('No built game found. Run "meshpad build" first.'); }
+  return preview({ root, configFile: false, build: { outDir }, preview: { host: options.host ?? '127.0.0.1', port: options.port ?? 4173 } });
+}
+
+export async function initProject(directory = '.', version = manifest.version) {
+  const root = resolve(directory);
+  const files = {
+    'package.json': JSON.stringify({
+      name: root.split(/[\\/]/).at(-1).toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'meshpad-game',
+      version: '0.0.0', private: true, type: 'module',
+      scripts: { dev: 'meshpad dev', build: 'meshpad build', preview: 'meshpad preview', render: 'meshpad render', typecheck: 'meshpad typecheck' },
+      engines: { node: '>=22.12.0' },
+      dependencies: { meshpad: `^${version}` },
+    }, null, 2) + '\n',
+    'game.ts': await readFile(new URL('../templates/game.ts', import.meta.url), 'utf8'),
+    'tsconfig.json': JSON.stringify({ extends: 'meshpad/tsconfig', include: ['**/*.ts'], exclude: ['node_modules', 'dist', 'renders'] }, null, 2) + '\n',
+    'vercel.json': JSON.stringify({ $schema: 'https://openapi.vercel.sh/vercel.json', framework: null, buildCommand: 'npm run build', outputDirectory: 'dist' }, null, 2) + '\n',
+    '.gitignore': 'node_modules/\ndist/\nrenders/\n.vercel/\n.DS_Store\n',
+  };
+  for (const name of Object.keys(files)) {
+    let exists = false;
+    try { await access(resolve(root, name)); exists = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (exists) throw new Error(`Refusing to overwrite ${resolve(root, name)}. Choose an empty directory.`);
+  }
+  await mkdir(root, { recursive: true });
+  for (const [name, content] of Object.entries(files)) await writeFile(resolve(root, name), content, { flag: 'wx' });
+  return root;
+}

package/src/typecheck.js

@@ -0,0 +1,88 @@
+import { realpath, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { stripVTControlCharacters } from 'node:util';
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const baseConfig = resolve(packageRoot, 'tsconfig.json');
+const formatHost = {
+  getCurrentDirectory: () => process.cwd(),
+  getCanonicalFileName: (file) => file,
+  getNewLine: () => '\n',
+};
+
+export async function resolveProject(entry = 'game.ts', options = {}) {
+  const root = await realpath(resolve(options.root ?? process.cwd()));
+  const source = resolve(root, entry);
+  if (!source.endsWith('.ts') || source.endsWith('.d.ts')) {
+    throw new Error('Meshpad requires a TypeScript entry file (.ts). Rename your game to game.ts.');
+  }
+  let info;
+  try { info = await stat(source); } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    throw new Error(`Game file not found: ${source}. Run "meshpad init" to create game.ts.`);
+  }
+  if (!info.isFile()) throw new Error(`Game entry must be a TypeScript file: ${source}.`);
+  return { root, source };
+}
+
+/** Check without emitting; Vite owns transpilation and bundling. */
+export async function checkProject(entry, options = {}) {
+  const { root, source } = await resolveProject(entry, options);
+  const configPath = resolve(root, 'tsconfig.json');
+  const hasConfig = ts.sys.fileExists(configPath);
+  const config = ts.readConfigFile(hasConfig ? configPath : baseConfig, ts.sys.readFile);
+  if (config.error) throw new Error(ts.formatDiagnosticsWithColorAndContext([config.error], formatHost));
+  const raw = { ...config.config };
+  // Resolve our preset even when using the CLI from npx, outside an installed project.
+  const preset = (value) => value === 'meshpad/tsconfig' ? baseConfig : value;
+  if (raw.extends) raw.extends = Array.isArray(raw.extends) ? raw.extends.map(preset) : preset(raw.extends);
+  const parsed = ts.parseJsonConfigFileContent(raw, ts.sys, root, undefined, configPath);
+  if (parsed.errors.length) throw new Error(ts.formatDiagnosticsWithColorAndContext(parsed.errors, formatHost));
+  const compilerOptions = {
+    ...parsed.options,
+    noEmit: true, noCheck: false, allowJs: false,
+    paths: {
+      ...parsed.options.paths,
+      meshpad: [resolve(packageRoot, 'index.d.ts')],
+      'meshpad/three': [resolve(packageRoot, 'three.d.ts')],
+      'meshpad/addons': [resolve(packageRoot, 'addons.d.ts')],
+    },
+  };
+  const program = ts.createProgram({ rootNames: [...new Set([...parsed.fileNames, source])], options: compilerOptions });
+  const diagnostics = ts.getPreEmitDiagnostics(program);
+  if (diagnostics.length) throw new Error(`TypeScript check failed.\n${ts.formatDiagnosticsWithColorAndContext(diagnostics, formatHost)}`);
+  return { root, source };
+}
+
+export function watchProject(server, source, root) {
+  let timer;
+  let closed = false;
+  let hadError = false;
+  const changed = (path) => {
+    if (!path.endsWith('.ts') && !path.endsWith('.json')) return;
+    clearTimeout(timer);
+    timer = setTimeout(async () => {
+      try {
+        await checkProject(source, { root });
+        if (closed) return;
+        // Clear a previous error overlay, including errors in files not imported by Vite.
+        if (hadError) server.ws.send({ type: 'full-reload' });
+        hadError = false;
+      } catch (error) {
+        if (closed) return;
+        hadError = true;
+        server.config.logger.error(error.message);
+        server.ws.send({ type: 'error', err: { message: stripVTControlCharacters(error.message), stack: '', plugin: 'meshpad-typecheck' } });
+      }
+    }, 100);
+  };
+  const events = ['change', 'add', 'unlink'];
+  for (const event of events) server.watcher.on(event, changed);
+  server.httpServer.once('close', () => {
+    closed = true;
+    clearTimeout(timer);
+    for (const event of events) server.watcher.off(event, changed);
+  });
+}