@oddessentials/agent-guild 1.28.0 → 1.30.0

package/src/manager/yard-worlds.mjs

@@ -0,0 +1,214 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { promisify } from 'node:util';
+import { EventEmitter } from 'node:events';
+import { WORLDS, CAMERA, SUN, STAGING } from '../../web/yard/model.mjs';
+import { extractArchive, renameRetrying } from './yard-art.mjs';
+
+const gunzip = promisify(zlib.gunzip);
+const MANIFEST = 'world.json';
+const INSTALL = 'install-id';
+const FORMAT = 1;
+const KIND = 'yard-environment';
+const MAX_PACKAGE = 64 * 1024 * 1024;
+const MAX_UNPACKED = 64 * 1024 * 1024;
+const MAX_ENTRY = 16 * 1024 * 1024;
+const MAX_RATIO = 20;
+const RATIO_FROM = 8 * 1024 * 1024;
+const MAX_SIDE = 4096;
+const SKY_HEADER = '#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y 256 +X 512\n';
+const SKY_SIZE = SKY_HEADER.length + 512 * 256 * 4;
+const THEMES = ['light', 'dark'];
+const TILES = ['base-0-0', 'base-1-0', 'detail-0-0', 'detail-1-0', 'close-0-0'];
+const REQUIRED = [...THEMES.flatMap((theme) => TILES.map((tile) => `web/${theme}-${tile}.webp`)), 'web/sky-light.hdr', 'web/sky-dark.hdr'];
+const ALLOWED = new Set([...REQUIRED, 'preview.jpg']);
+const SERVED = new Set(REQUIRED.map((name) => name.slice('web/'.length)));
+
+const sha256 = (data) => crypto.createHash('sha256').update(data).digest('hex');
+const failure = (status, code, message) => Object.assign(new Error(message), { status, code });
+const invalid = (message) => failure(400, 'world_invalid', message);
+
+export function environmentId() {
+  return sha256(JSON.stringify([CAMERA, SUN, STAGING.plaza])).slice(0, 16);
+}
+
+function checkManifest(meta) {
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta)) throw invalid('This world’s details can’t be read.');
+  if (!Number.isInteger(meta.format) || meta.format < 1) throw invalid('This world’s format is missing.');
+  if (meta.format > FORMAT) throw invalid('This world needs a newer Agent Guild.');
+  if (meta.kind !== KIND) throw invalid('This isn’t a Yard environment.');
+  const title = typeof meta.title === 'string' ? meta.title.trim() : '';
+  if (!title || title.length > 128 || /\p{Cc}/u.test(title)) throw invalid('This world’s title is missing or too long.');
+  if (meta.environment !== environmentId()) throw invalid('This world was made for a different Yard layout, so it wouldn’t line up.');
+  if (!meta.files || typeof meta.files !== 'object' || Array.isArray(meta.files)) throw invalid('This world’s list of files is missing.');
+  let total = 0;
+  for (const [name, file] of Object.entries(meta.files)) {
+    if (!ALLOWED.has(name)) throw invalid(`${name} doesn’t belong in a world file.`);
+    if (!Number.isSafeInteger(file?.size) || file.size < 0 || file.size > MAX_ENTRY || !/^[0-9a-f]{64}$/.test(file.sha256)) throw invalid(`${name} has invalid details.`);
+    total += file.size;
+  }
+  if (total > MAX_UNPACKED) throw invalid('This world unpacks to more than a world may.');
+  for (const name of REQUIRED) if (!Object.hasOwn(meta.files, name)) throw invalid(`${name} is missing.`);
+  if (meta.lights !== undefined) {
+    const colour = (value) => Number.isInteger(value) && value >= 0 && value <= 0xffffff;
+    if (!THEMES.every((theme) => colour(meta.lights?.[theme]?.sun) && colour(meta.lights?.[theme]?.hemi))) throw invalid('This world’s light colours aren’t valid.');
+  }
+  return { title, lights: meta.lights ?? null };
+}
+
+function webpSize(b) {
+  const chunk = b.toString('latin1', 12, 16);
+  if (chunk === 'VP8 ' && b.length >= 30) return [b.readUInt16LE(26) & 0x3fff, b.readUInt16LE(28) & 0x3fff];
+  if (chunk === 'VP8L' && b.length >= 25) {
+    const v = b.readUInt32LE(21);
+    return [(v & 0x3fff) + 1, ((v >>> 14) & 0x3fff) + 1];
+  }
+  if (chunk === 'VP8X' && b.length >= 30) return [b.readUIntLE(24, 3) + 1, b.readUIntLE(27, 3) + 1];
+  return [0, 0];
+}
+
+function checkContent(name, b) {
+  if (name.endsWith('.webp')) {
+    if (b.toString('latin1', 0, 4) !== 'RIFF' || b.toString('latin1', 8, 12) !== 'WEBP') throw invalid(`${name} isn’t a WebP image.`);
+    if (webpSize(b).some((side) => side <= 0 || side > MAX_SIDE)) throw invalid(`${name} has an unsafe image size.`);
+  } else if (name.endsWith('.hdr')) {
+    if (b.length !== SKY_SIZE || b.toString('latin1', 0, SKY_HEADER.length) !== SKY_HEADER) throw invalid(`${name} isn’t a sky image.`);
+  } else if (b[0] !== 0xff || b[1] !== 0xd8 || b[2] !== 0xff) throw invalid(`${name} isn’t a JPEG image.`);
+}
+
+async function readPackage(file) {
+  if (typeof file !== 'string' || !path.isAbsolute(file) || file.includes('\0') || !file.toLowerCase().endsWith('.agworld')) throw invalid('Choose an .agworld file.');
+  let raw;
+  try {
+    const stat = await fsp.stat(file);
+    if (!stat.isFile()) throw invalid('Choose an .agworld file.');
+    if (stat.size > MAX_PACKAGE) throw invalid('This file is larger than a world can be.');
+    raw = await fsp.readFile(file);
+  } catch (err) {
+    if (err.status) throw err;
+    throw invalid('This file can’t be read.');
+  }
+  let tar;
+  try { tar = await gunzip(raw, { maxOutputLength: MAX_UNPACKED + 1 }); } catch (err) {
+    throw invalid(err.code === 'ERR_BUFFER_TOO_LARGE' ? 'This world unpacks to more than a world may.' : 'This isn’t a world file.');
+  }
+  if (tar.length > MAX_UNPACKED) throw invalid('This world unpacks to more than a world may.');
+  if (tar.length > RATIO_FROM && tar.length / raw.length > MAX_RATIO) throw invalid('This file expands far more than a world should.');
+  const name = tar.toString('utf8', 0, 100).replace(/\0.*$/s, '');
+  const size = parseInt(tar.toString('latin1', 124, 136).replace(/\0.*$/s, '').trim(), 8);
+  const type = tar[156] === 0 ? '0' : String.fromCharCode(tar[156]);
+  if (name !== MANIFEST || type !== '0' || !Number.isSafeInteger(size) || size > MAX_ENTRY || 512 + size > tar.length) throw invalid('This isn’t a world file.');
+  const bytes = tar.subarray(512, 512 + size);
+  let meta;
+  try { meta = JSON.parse(bytes.toString('utf8')); } catch { throw invalid('This world’s details can’t be read.'); }
+  checkManifest(meta);
+  const files = [{ path: MANIFEST, size, sha256: sha256(bytes) }, ...Object.entries(meta.files).map(([entry, details]) => ({ path: entry, size: details.size, sha256: details.sha256 }))];
+  return { files, meta };
+}
+
+export class YardWorlds extends EventEmitter {
+  constructor({ dir = null, remove = (folder) => fsp.rm(folder, { recursive: true, force: true, maxRetries: 5 }) } = {}) {
+    super();
+    this.dir = dir;
+    this.worlds = {};
+    this.busy = false;
+    this.remove = remove;
+    this.swept = Promise.resolve();
+    if (!dir) return;
+    for (const skin of Object.keys(WORLDS)) this.read(skin);
+    this.swept = this.sweep();
+  }
+
+  snapshot() { return this.worlds; }
+
+  discard(folder) {
+    return this.remove(folder).catch(() => {});
+  }
+
+  async sweep() {
+    const names = await fsp.readdir(this.dir).catch(() => []);
+    await Promise.all(names.filter((name) => name.startsWith('.')).map((name) => this.discard(path.join(this.dir, name))));
+  }
+
+  aside(skin, kind) {
+    return path.join(this.dir, `.${skin}.${crypto.randomUUID()}.${kind}`);
+  }
+
+  file(skin, name) {
+    return this.dir && Object.hasOwn(WORLDS, skin) && SERVED.has(name) ? path.join(this.dir, skin, 'web', name) : null;
+  }
+
+  read(skin) {
+    const folder = path.join(this.dir, skin);
+    if (!fs.existsSync(folder)) { delete this.worlds[skin]; return; }
+    let title;
+    try {
+      const bytes = fs.readFileSync(path.join(folder, MANIFEST));
+      const meta = JSON.parse(bytes.toString('utf8'));
+      const checked = checkManifest(meta);
+      title = checked.title;
+      for (const [name, details] of Object.entries(meta.files)) {
+        let content;
+        try { content = fs.readFileSync(path.join(folder, ...name.split('/'))); } catch { content = null; }
+        if (!content || content.length !== details.size || sha256(content) !== details.sha256) throw invalid(`${title} is damaged: ${name} is missing or changed.`);
+      }
+      const install = fs.readFileSync(path.join(folder, INSTALL));
+      this.worlds[skin] = { title, revision: sha256(Buffer.concat([bytes, install])).slice(0, 16), lights: checked.lights };
+    } catch (err) {
+      this.worlds[skin] = { title: title ?? null, problem: err.status ? err.message : `${title ?? 'This Yard’s world'} is damaged.` };
+    }
+  }
+
+  async exclusive(skin, work) {
+    if (!Object.hasOwn(WORLDS, skin)) throw failure(404, 'unknown_yard', 'There is no such Yard.');
+    if (!this.dir) throw failure(409, 'worlds_unsupported', 'This manager has no data folder to keep worlds in.');
+    if (this.busy) throw failure(409, 'world_busy', 'Another world is being installed. Try again when it finishes.');
+    this.busy = true;
+    const before = JSON.stringify(this.worlds[skin] ?? null);
+    try {
+      await work();
+    } catch (err) {
+      if (err.status) throw err;
+      throw failure(500, 'world_unwritable', `Agent Guild cannot write to its data folder: ${err.message}`);
+    } finally {
+      this.read(skin);
+      this.busy = false;
+      if (JSON.stringify(this.worlds[skin] ?? null) !== before) this.emit('updated', this.snapshot());
+    }
+    return this.snapshot();
+  }
+
+  replace(skin, file) {
+    return this.exclusive(skin, async () => {
+      const { files } = await readPackage(file);
+      const target = path.join(this.dir, skin), staging = this.aside(skin, 'staging'), previous = this.aside(skin, 'old');
+      await fsp.mkdir(this.dir, { recursive: true });
+      try {
+        try { await extractArchive(file, files, staging); } catch (err) {
+          if (['ENOSPC', 'EACCES', 'EPERM', 'EBUSY', 'EROFS'].includes(err.code)) throw err;
+          throw invalid(`This world file is damaged: ${err.message}.`);
+        }
+        for (const { path: name } of files) if (name !== MANIFEST) checkContent(name, await fsp.readFile(path.join(staging, ...name.split('/'))));
+        await fsp.writeFile(path.join(staging, INSTALL), crypto.randomUUID());
+        const had = fs.existsSync(target);
+        if (had) await renameRetrying(target, previous);
+        try { await renameRetrying(staging, target); } catch (err) {
+          if (had) await renameRetrying(previous, target);
+          throw err;
+        }
+      } finally { await this.discard(staging); }
+      await this.sweep();
+    });
+  }
+
+  restore(skin) {
+    return this.exclusive(skin, async () => {
+      const target = path.join(this.dir, skin);
+      if (fs.existsSync(target)) await renameRetrying(target, this.aside(skin, 'old'));
+      await this.sweep();
+    });
+  }
+}

package/web/app.js

@@ -202,7 +202,7 @@ function holdToast(held) {
 const firstClick = (run) => (e) => { if (e.detail < 2) run(); };
 
 /** Buttons that act through the session manager. While it cannot be reached they are unavailable rather than left to fail. */
-const MANAGER_ACTIONS = '.provider :is(.new, .existing, .install, .update), .session-card :is(.resume, .rename, .stop, .remove), .history-resume, #panel-stop, #yard-install';
+const MANAGER_ACTIONS = '.provider :is(.new, .existing, .install, .update), .session-card :is(.resume, .rename, .stop, .remove), .history-resume, #panel-stop, #yard-install, #yard-customize-open, .break-install';
 
 function paintManagerActions(root = document) {
   for (const button of root.querySelectorAll(MANAGER_ACTIONS)) button.disabled = !state.connected;
@@ -595,9 +595,12 @@ function managerGone() {
 function placeMenu(menu, button) {
   if (!menu.matches(':popover-open') || !button) return;
   const box = button.getBoundingClientRect();
-  const top = Math.round(box.bottom + 6);
+  menu.style.maxHeight = '';
+  const height = menu.offsetHeight, below = Math.round(box.bottom + 6), above = Math.round(box.top - 6), room = innerHeight - below - 8;
+  const flip = height > room && above - 8 > room;
+  const top = flip ? Math.max(8, above - height) : below;
   menu.style.top = `${top}px`;
-  menu.style.maxHeight = `${innerHeight - top - 8}px`;
+  menu.style.maxHeight = `${flip ? above - top : room}px`;
   menu.style.left = 'auto';
   menu.style.right = `${Math.max(8, Math.round(innerWidth - box.right))}px`;
   if (menu.getBoundingClientRect().left < 8) {
@@ -1431,13 +1434,20 @@ function recentKeys(field, e) {
 const FOLDER_FIELDS = {
   cwd: { title: 'Choose working folder', input: 'cwd' },
   clone: { title: 'Choose clone folder', input: 'github-parent' },
+  world: { title: 'Choose a world file', input: null },
+  character: { title: 'Choose a character', input: null },
+  companion: { title: 'Choose a companion', input: null },
 };
+const WORLD_FOLDER_KEY = 'agentGuild.worldFolder';
+const PIECE_FOLDER_KEY = 'agentGuild.pieceFolder';
+const PIECE_FIELDS = ['character', 'companion'];
 const folderView = { field: null, listing: null, loading: false, error: null, request: 0, opener: null };
 
-function chooseFolder(field) {
+function chooseFolder(field, skin = null, slot = null) {
   if (!state.connected) return;
   const dialog = $('folder-browser');
-  Object.assign(folderView, { field, listing: null, loading: false, error: null });
+  Object.assign(folderView, { field, skin, slot, listing: null, loading: false, error: null, toWorkshop: PIECE_FIELDS.includes(field) && !load(PIECE_FOLDER_KEY) });
+  $('folder-use').hidden = $('folder-new-open').hidden = field === 'world' || PIECE_FIELDS.includes(field);
   $('folder-title').textContent = FOLDER_FIELDS[field].title;
   $('folder-filter').value = '';
   $('folder-hidden').checked = load(HIDDEN_FOLDERS_KEY) === '1';
@@ -1445,7 +1455,7 @@ function chooseFolder(field) {
     folderView.opener = document.activeElement;
     dialog.showModal();
   }
-  browseTo($(FOLDER_FIELDS[field].input).value.trim());
+  browseTo(field === 'world' ? load(WORLD_FOLDER_KEY) ?? '' : PIECE_FIELDS.includes(field) ? load(PIECE_FOLDER_KEY) ?? '' : $(FOLDER_FIELDS[field].input).value.trim());
 }
 
 function showNewFolder(open) {
@@ -1499,8 +1509,13 @@ async function browseTo(dir) {
   folderView.error = null;
   renderFolderBrowser();
   try {
-    const listing = await api('GET', `/folders?path=${encodeURIComponent(dir)}`);
+    const listing = await api('GET', `/folders?path=${encodeURIComponent(dir)}${folderView.field === 'world' ? '&files=agworld' : PIECE_FIELDS.includes(folderView.field) ? `&pieces=${folderView.field}` : ''}`);
     if (request !== folderView.request) return;
+    if (folderView.toWorkshop && listing.workshop && listing.path !== listing.workshop) {
+      folderView.toWorkshop = false;
+      return browseTo(listing.workshop);
+    }
+    folderView.toWorkshop = false;
     folderView.listing = listing;
     $('folder-filter').value = '';
   } catch (err) {
@@ -1528,6 +1543,8 @@ function renderFolderBrowser() {
   $('folder-roots').replaceChildren(...(listing?.roots ?? []).map((root) => button(root.name, () => browseTo(root.path), 'btn folder-chip')));
   $('folder-up').disabled = loading || !listing?.parent;
   $('folder-home').disabled = loading;
+  $('folder-workshop').hidden = !listing?.workshop;
+  $('folder-workshop').disabled = loading;
   const note = $('folder-note');
   note.hidden = !listing?.note;
   note.textContent = listing?.note ? `${listing.note} was not found, so this shows the nearest folder that exists.` : '';
@@ -1537,12 +1554,25 @@ function renderFolderBrowser() {
     row.classList.toggle('hidden-folder', entry.hidden);
     row.title = entry.path;
     return row;
+  }), ...(listing?.files ?? []).filter((file) => !query || file.name.toLowerCase().includes(query)).map((file) => {
+    const row = button(file.name, () => useWorldFile(file.path), 'folder-row folder-file');
+    row.title = file.path;
+    return row;
+  }), ...(listing?.pieces ?? []).filter((piece) => !query || piece.title.toLowerCase().includes(query) || piece.folder.toLowerCase().includes(query)).map((piece) => {
+    const row = button('', () => { if (!piece.problem) usePiece(piece.path); }, 'folder-row folder-piece');
+    if (piece.problem) row.setAttribute('aria-disabled', 'true');
+    row.append(Object.assign(document.createElement('span'), { className: 'folder-piece-title', textContent: piece.title }),
+      Object.assign(document.createElement('span'), { className: 'folder-piece-sub', textContent: piece.problem ? `${piece.folder} · ${piece.problem}` : `${folderView.field === 'character' ? 'Character' : 'Companion'} · ${piece.folder}` }));
+    row.title = piece.path;
+    return row;
   }));
   const status = $('folder-status');
   status.textContent = loading ? 'Loading folders…'
     : error ? error
       : !listing ? ''
-        : !entries.length ? (listing.entries.length ? 'No folders match.' : 'No folders here.')
+        : listing.files?.length || listing.pieces?.length ? ''
+        : PIECE_FIELDS.includes(folderView.field) ? `No ${folderView.field === 'character' ? 'characters' : 'companions'} here or in the folders inside it. Steam keeps Workshop items in its library under steamapps › workshop › content › 5462970.`
+        : !entries.length ? (folderView.field === 'world' ? 'No world files here.' : listing.entries.length ? 'No folders match.' : 'No folders here.')
           : listing.truncated ? `Showing the first ${listing.entries.length.toLocaleString()} folders.` : '';
   status.classList.toggle('error', Boolean(error));
   $('folder-current').textContent = listing?.path ?? '';
@@ -1551,6 +1581,35 @@ function renderFolderBrowser() {
   $('folder-new-create').disabled = loading || !listing || !$('folder-new-name').value.trim();
 }
 
+async function yardChange(request, row = true) {
+  state.yardBusy = row;
+  notifyViews();
+  try {
+    await request();
+    return true;
+  } catch (err) {
+    if (err instanceof AuthError) showAuth(err.message);
+    else toast(err.message, 8000);
+    return false;
+  } finally {
+    state.yardBusy = false;
+    notifyViews();
+  }
+}
+
+function useWorldFile(file) {
+  const { skin, listing } = folderView;
+  $('folder-browser').close();
+  save(WORLD_FOLDER_KEY, listing.path);
+  return yardChange(() => api('PUT', `/yard-worlds/${skin}`, { path: file }), `${skin}/world`);
+}
+
+async function usePiece(folder) {
+  const { skin, slot, listing } = folderView;
+  $('folder-browser').close();
+  if (await yardChange(() => api('PUT', `/yard-pieces/${skin}/${slot}`, { path: folder }), `${skin}/${slot}`)) save(PIECE_FOLDER_KEY, listing.path);
+}
+
 function folderBrowserClosed() {
   if (!$('folder-browser').open && folderView.opener?.isConnected) folderView.opener.focus();
 }
@@ -2355,6 +2414,85 @@ async function changeMcp(provider, entry, view) {
 
 let dealt = false;
 
+const BREAK_CARD = 'terminal-ai-chat';
+const BREAK_LABEL = 'Need a break?';
+const BREAK_SOURCES = ['yard-play-arena', 'yard-play-more', 'yard-play-solo', 'yard-install', 'yard-play-builders'];
+let breakMenus = 0, breakPointer = '', breakArmed = null;
+
+function paintBreak(root = document) {
+  for (const section of root.querySelectorAll('.break-buttons:not([hidden])')) {
+    section.querySelector('.break-label').textContent = breakArmed ? `${breakArmed}. Tap again to open.` : BREAK_LABEL;
+    for (const link of section.querySelectorAll('.yard-play-chip > .yard-play-link')) {
+      link.closest('.yard-play').classList.toggle('armed', link.getAttribute('aria-label') === breakArmed);
+    }
+  }
+}
+
+function armBreak(name) {
+  breakArmed = name;
+  paintBreak();
+}
+
+// On the window, ahead of the host's link handler on the document.
+window.addEventListener('pointerdown', (e) => {
+  breakPointer = e.pointerType;
+  if (breakArmed && e.target.closest?.('.armed .yard-play-link')?.getAttribute('aria-label') !== breakArmed) armBreak(null);
+}, true);
+window.addEventListener('click', (e) => {
+  const touched = breakPointer === 'touch';
+  breakPointer = '';
+  const name = e.target.closest?.('.break-row .yard-play-chip > .yard-play-link')?.getAttribute('aria-label');
+  if (!name || !touched || breakArmed === name) {
+    if (breakArmed) armBreak(null);
+    return;
+  }
+  e.preventDefault();
+  e.stopPropagation();
+  armBreak(name);
+}, true);
+
+function breakItem(id) {
+  const source = $(id).closest('.yard-play');
+  const item = source.cloneNode(true);
+  item.querySelector('.yard-play-burst').remove();
+  for (const part of item.querySelectorAll('.yard-play-text, .yard-play-chev')) part.remove();
+  for (const part of item.querySelectorAll('[id]')) part.removeAttribute('id');
+  const menu = item.querySelector('.yard-play-menu');
+  if (!menu) return item;
+  item.querySelector('.yard-play-chip > .yard-play-link').remove();
+  const more = item.querySelector('.yard-play-more');
+  menu.id = `break-play-menu-${++breakMenus}`;
+  more.setAttribute('popovertarget', menu.id);
+  onMenu(menu, () => {
+    placeMenu(menu, more);
+    menuItems(menu)[0]?.focus();
+  }, () => returnFocus(menu, more));
+  menu.addEventListener('click', (e) => { if (e.target.closest('a')) closeMenu(menu); });
+  menu.addEventListener('keydown', moveInMenu);
+  return item;
+}
+
+function placeBreakMenus() {
+  for (const menu of document.querySelectorAll('.break-row .yard-play-menu:popover-open')) placeMenu(menu, menu.closest('.yard-play').querySelector('.yard-play-more'));
+}
+
+function mountBreakButtons(card) {
+  const section = card.querySelector('.break-buttons'), row = section.querySelector('.break-row');
+  for (const id of BREAK_SOURCES) {
+    if (id === 'yard-install' && $(id).hidden) continue;
+    const item = breakItem(id);
+    if (id === 'yard-install') {
+      const button = item.querySelector('.yard-play-link');
+      button.hidden = false;
+      button.classList.add('break-install');
+      button.addEventListener('click', installCompanion);
+    }
+    row.append(item);
+  }
+  section.hidden = false;
+  paintBreak(card);
+}
+
 // Both layouts mount these same controls with these same command handlers.
 function buildProvider(provider) {
     const node = $('provider-template').content.firstElementChild.cloneNode(true);
@@ -2367,6 +2505,7 @@ function buildProvider(provider) {
     stateLine.classList.toggle('update-available', provider.updateAvailable || checkFailed || Boolean(installNote(provider)));
     stateLine.title = [provider.resolvedPath, provider.updateCommand && `Update: ${provider.updateCommand}`].filter(Boolean).join('\n');
     node.dataset.id = provider.id;
+    if (provider.id === BREAK_CARD && document.documentElement.dataset.yard !== 'none') mountBreakButtons(node);
     node.classList.toggle('unavailable', !provider.available);
     node.setAttribute('aria-label', `${provider.vendor} ${provider.tool}, ${!provider.available ? 'not installed' : checkFailed ? 'version check failed' : 'ready'}`);
     const start = node.querySelector('.new');
@@ -7797,6 +7936,7 @@ function closeDialogs() {
   closeFlags();
   closeMemory();
   if ($('folder-browser').open) $('folder-browser').close();
+  if ($('yard-customize').open) $('yard-customize').close();
   yardUi?.closePhoto();
   // An open question is answered as cancelled.
   if ($('ask').open) $('ask').close();
@@ -7944,6 +8084,9 @@ function connectEvents() {
       state.folderOpener = msg.folderOpener || null;
       state.platform = msg.platform || null;
       $('yard-install').hidden = !['win32', 'darwin'].includes(state.platform);
+      $('yard-world-get').hidden = state.platform !== 'win32';
+      state.yardWorlds = msg.yardWorlds ?? null;
+      state.yardPieces = msg.yardPieces ?? null;
       state.remoteAccessUI?.setAvailable(msg.remoteAccess);
       state.remoteAccessUI?.signInsUpdated();
       state.glassesLinkUI?.setAvailable(msg.remoteAccess);
@@ -7985,6 +8128,12 @@ function connectEvents() {
     } else if (msg.type === 'yard-art.updated') {
       state.yardArt = msg.yardArt;
       notifyViews();
+    } else if (msg.type === 'yard-worlds.updated') {
+      state.yardWorlds = msg.yardWorlds;
+      notifyViews();
+    } else if (msg.type === 'yard-pieces.updated') {
+      state.yardPieces = msg.yardPieces;
+      notifyViews();
     } else if (msg.type === 'yard.fireworks') {
       yardUi?.celebrate();
     } else if (msg.type === 'news.updated') {
@@ -8605,7 +8754,8 @@ onMenu($('yard-play-menu'), (menu) => {
 $('yard-play-menu').addEventListener('click', (e) => {
   if (e.target.closest('a')) closeMenu(e.currentTarget);
 });
-$('yard-install').addEventListener('click', async (e) => {
+$('yard-install').addEventListener('click', installCompanion);
+async function installCompanion(e) {
   const button = e.currentTarget;
   button.disabled = true;
   try {
@@ -8618,9 +8768,12 @@ $('yard-install').addEventListener('click', async (e) => {
   } finally {
     button.disabled = !state.connected;
   }
-});
+}
 new MutationObserver(() => closeMenu($('yard-play-menu'))).observe(document.documentElement, { attributes: true, attributeFilter: ['data-view', 'data-skin', 'data-layout'] });
-window.addEventListener('scroll', () => placeMenu($('yard-play-menu'), $('yard-play-more')), { passive: true });
+window.addEventListener('scroll', () => {
+  placeMenu($('yard-play-menu'), $('yard-play-more'));
+  placeBreakMenus();
+}, { passive: true });
 for (const menu of [$('manager-menu'), $('panel-sessions'), $('yard-play-menu')]) menu.addEventListener('keydown', moveInMenu);
 // Recorded only on the click that opens the menu: a click that closes it leaves what the open menu showed.
 const sessionMenuFrom = (mode, invoker) => () => {
@@ -8641,6 +8794,7 @@ window.addEventListener('resize', () => {
   placeMenu($('panel-text-size'), $('panel-text-toggle'));
   placeMenu($('cards-menu'), $('cards-open'));
   placeMenu($('yard-play-menu'), $('yard-play-more'));
+  placeBreakMenus();
 });
 onMenu($('cards-menu'), (menu) => {
   placeMenu(menu, $('cards-open'));
@@ -8723,6 +8877,7 @@ $('folder-browser').addEventListener('keydown', folderBrowserKeys);
 $('folder-list').addEventListener('keydown', moveInFolders);
 $('folder-up').addEventListener('click', () => browseTo(folderView.listing.parent));
 $('folder-home').addEventListener('click', () => browseTo('~'));
+$('folder-workshop').addEventListener('click', () => browseTo(folderView.listing.workshop));
 $('folder-filter').addEventListener('input', renderFolderBrowser);
 $('folder-hidden').addEventListener('change', (e) => {
   save(HIDDEN_FOLDERS_KEY, e.target.checked ? '1' : null);
@@ -8812,6 +8967,15 @@ yardUi = initYard({
   openNews,
   selected: dockMakesWayForYard,
   yardArt: () => state.yardArt,
+  yardWorld: (skin) => state.yardWorlds?.[skin] ?? null,
+  canReplaceYard: () => Boolean(state.yardWorlds),
+  replaceYard: (skin) => chooseFolder('world', skin),
+  restoreYard: (skin) => yardChange(() => api('DELETE', `/yard-worlds/${skin}`)),
+  yardPieces: (skin) => state.yardPieces?.[skin] ?? {},
+  yardBusy: () => Boolean(state.yardBusy),
+  yardChecking: () => (typeof state.yardBusy === 'string' ? state.yardBusy : null),
+  replacePiece: (skin, slot) => chooseFolder(slot === 'companion' ? 'companion' : 'character', skin, slot),
+  restorePiece: (skin, slot) => yardChange(() => api('DELETE', `/yard-pieces/${skin}/${slot}`)),
   // The new state arrives as yard-art.updated, ordered with the progress events.
   yardArtAction: (action) => api('POST', `/yard-art/${action}`),
   mountInspector(host, selection) {