@webship.co/workspace 0.0.0-stage → 1.0.0-beta1

package/themes.js

@@ -0,0 +1,381 @@
+/**
+ * The theme system: which palette the dashboard wears.
+ *
+ * A theme is one file — `public/themes/<name>/theme.css` — that sets the tokens every component
+ * asks for, in both halves (light and dark). Nothing else has to know which theme is loaded,
+ * because no component names a colour: they all say `var(--brand-primary)` rather than `#0074e0`.
+ *
+ * `/style.css` is assembled here rather than being a file on disk: the base layer, then every
+ * component, then the chosen theme last so it wins. One request, and a component is a file rather
+ * than another block appended to a 2,800-line stylesheet — which is also why two branches adding
+ * features stop conflicting over the same tail.
+ *
+ * Adopted from the tooling this dashboard grew from (its issue #64).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const yamlLoad = (text) => (typeof yaml.safeLoad === 'function' ? yaml.safeLoad(text) : yaml.load(text));
+
+const PUBLIC_DIR = path.join(__dirname, 'public');
+// Where a theme's YAML overrides live, beside the rest of the config people edit.
+const CONFIG_DIR = process.env.WORKSPACE_CONFIG
+  || path.join(process.env.WORKSPACE_ROOT || path.resolve(__dirname, '..', '..'), 'core', 'config');
+const CSS_DIR = path.join(PUBLIC_DIR, 'css');
+const THEMES_DIR = path.join(PUBLIC_DIR, 'themes');
+
+/**
+ * Every style on this machine: the ones that ship as a directory with a `theme.css`, and the ones
+ * that are nothing but a `core/config/theme.<name>.yml`.
+ *
+ * A YAML-only style is how somebody adds one without writing into the app's own directory — which
+ * is the difference between a style being something a developer creates and a style being something
+ * only a release can add. It works because a theme is a palette: with every token in the YAML there
+ * is nothing left for a stylesheet to say.
+ */
+const THEME_NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+function listThemes() {
+  const names = new Set();
+  try {
+    for (const e of fs.readdirSync(THEMES_DIR, { withFileTypes: true })) {
+      if (e.isDirectory() && fs.existsSync(path.join(THEMES_DIR, e.name, 'theme.css'))) names.add(e.name);
+    }
+  } catch (_) { /* no themes directory */ }
+  try {
+    for (const f of fs.readdirSync(CONFIG_DIR)) {
+      const m = f.match(/^theme\.([a-z][a-z0-9-]*)\.yml$/);
+      // A YAML with no tokens in it is a file somebody started, not a style you can wear.
+      if (m && Object.keys(readThemeOverrides(m[1]).tokens).length) names.add(m[1]);
+    }
+  } catch (_) { /* no config directory */ }
+  return [...names].sort();
+}
+
+/** Does this style exist only as YAML? Then its tokens are all there is. */
+function isYamlOnlyTheme(name) {
+  return Boolean(name) && !fs.existsSync(path.join(THEMES_DIR, name, 'theme.css'));
+}
+
+/**
+ * Was this style made on this machine, or did it come with the workspace?
+ *
+ * Not the same question as `isYamlOnlyTheme`, though the Styles page asked that one for a while and
+ * labelled the answer "made here". Five styles that ship in the repository — Dispatch, UPSUN,
+ * GitHub, GitLab and Drupal — are YAML and nothing else, because a style is a set of tokens and a
+ * stylesheet would be a second place to keep them. They were being credited to whoever opened the
+ * page.
+ *
+ * `createTheme` stamps what it writes, so the marker is on the file rather than inferred from its
+ * shape, and a style that ships needs nothing said about it.
+ */
+function isMadeHere(name) {
+  if (!name) return false;
+  try {
+    const doc = yamlLoad(fs.readFileSync(themeOverridesFile(name), 'utf8'));
+    return Boolean(doc && doc.made_here);
+  } catch (_) {
+    return false;
+  }
+}
+
+// What a theme calls itself, for the settings form. One line at the top of the file, so naming a
+// theme does not need a second file to parse.
+function themeLabel(name) {
+  try {
+    const head = fs.readFileSync(path.join(THEMES_DIR, name, 'theme.css'), 'utf8').slice(0, 600);
+    const m = head.match(/^\s*\*\s*@name\s+(.+)$/m);
+    if (m) return m[1].trim();
+  } catch (_) { /* no CSS: a YAML-only style names itself in its own file */ }
+  try {
+    const doc = yamlLoad(fs.readFileSync(path.join(CONFIG_DIR, `theme.${name}.yml`), 'utf8'));
+    if (doc && typeof doc.name === 'string' && doc.name.trim()) return doc.name.trim();
+  } catch (_) { /* fall through to the file name */ }
+  return name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, ' ');
+}
+
+// A name that is not a theme falls back to the default, so a typo in settings.yml is a dashboard
+// that looks ordinary rather than one with no styling at all.
+function resolveTheme(wanted) {
+  const themes = listThemes();
+  if (wanted && themes.includes(wanted)) return wanted;
+  return themes.includes('default') ? 'default' : themes[0] || null;
+}
+
+// The order components are concatenated in, which is the order they had when they were one file.
+//
+// Not alphabetical: CSS is a cascade, and two rules of equal specificity are decided by which came
+// last. Sorting by name would change which wins. Anything not listed goes last, alphabetically,
+// which is where a newly added component belongs anyway.
+const COMPONENT_ORDER = [
+  'hero',
+  'workspace-cards',
+  'ai-assistant',
+  'deep-chat',
+  'project-rows',
+  'floating-assistant-workspace-pages',
+  'working-indicators',
+  'top-toolbar-logo-breadcrumb',
+  'layout-rhythm-and-spacing-polish',
+  'full-height-left-assistant-sidebar-all-pages',
+  'full-height-right-actions-rail-pages-that-have-actions',
+  // After the sidebar's own rules, because it is what re-sizes and re-places that sidebar.
+  'assistant-views',
+  // After the layout components, since it re-caps the container they lay out.
+  'page-width',
+  'mic-on-any-field-that-wants-typing',
+  'settings-editor-core-config-yml',
+  'responsive-home-and-the-workspace-pages',
+  'running-commands-as-toasts',
+  'short-results-as-a-toast-at-the-top',
+  'reordering-the-workspace-cards',
+  // After the card and row components, since it re-lays out what they draw.
+  'grid-and-list',
+  'test-report-media-one-file-per-row-paged',
+];
+
+function listComponents() {
+  let files = [];
+  try {
+    files = fs.readdirSync(path.join(CSS_DIR, 'components'))
+      .filter((f) => f.endsWith('.css'))
+      .map((f) => f.replace(/\.css$/, ''));
+  } catch (_) {
+    return [];
+  }
+  const known = COMPONENT_ORDER.filter((n) => files.includes(n));
+  const rest = files.filter((n) => !COMPONENT_ORDER.includes(n)).sort();
+  return [...known, ...rest];
+}
+
+const readOrEmpty = (file) => {
+  try { return fs.readFileSync(file, 'utf8'); } catch (_) { return ''; }
+};
+
+
+/* ---------------- tokens as YAML ---------------- */
+
+/**
+ * A theme's tokens, overridable from `core/config/theme.<name>.yml`.
+ *
+ * A theme file is a palette: it declares custom properties and selects nothing. That makes every
+ * value in it a candidate for configuration, and CSS is the wrong place to ask somebody to change
+ * one — it means editing a stylesheet in the app's own directory, which is not where this workspace
+ * keeps anything else people set.
+ *
+ * So the same tokens can be written in YAML, in the config directory with `settings.yml` and the
+ * workspace files, where the dashboard's own settings editor can reach them:
+ *
+ *     # core/config/theme.press.yml
+ *     tokens:
+ *       size-h1: 2.25rem
+ *       brand-primary: "#0074e0"
+ *     dark:
+ *       surface-card: "#1c2136"
+ *
+ * Names are written without the leading `--`; one is added if it is missing, so either spelling
+ * works. `tokens:` applies to both halves; `dark:` applies to the dark half only, exactly like the
+ * `html.dark` block in a theme file.
+ *
+ * The YAML is emitted AFTER the theme's CSS, so it wins — an override is an override. A file that
+ * does not exist, or one that is unreadable, leaves the theme exactly as it shipped: appearance is
+ * configuration, and a typo in configuration should not cost you a styled dashboard.
+ */
+function themeOverridesFile(name) {
+  return path.join(CONFIG_DIR, `theme.${name}.yml`);
+}
+
+function readThemeOverrides(name) {
+  if (!name) return { tokens: {}, dark: {} };
+  let doc;
+  try {
+    doc = yamlLoad(fs.readFileSync(themeOverridesFile(name), 'utf8'));
+  } catch (_) {
+    return { tokens: {}, dark: {} };
+  }
+  const clean = (block) => {
+    const out = {};
+    if (!block || typeof block !== 'object') return out;
+    for (const [rawKey, rawValue] of Object.entries(block)) {
+      // A token name, and nothing that could close the block and start a rule of its own.
+      const key = String(rawKey).trim().replace(/^--/, '');
+      if (!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(key)) continue;
+      if (rawValue === null || rawValue === undefined) continue;
+      const value = String(rawValue).trim();
+      if (!value || /[{};]/.test(value)) continue;
+      out[`--${key}`] = value;
+    }
+    return out;
+  };
+  return { tokens: clean(doc && doc.tokens), dark: clean(doc && doc.dark) };
+}
+
+/** The override blocks as CSS, or '' when a theme has no YAML of its own. */
+function themeOverridesCss(name) {
+  const { tokens, dark } = readThemeOverrides(name);
+  const block = (selector, map) => {
+    const keys = Object.keys(map);
+    if (!keys.length) return '';
+    return `${selector} {\n${keys.map((k) => `  ${k}: ${map[k]};`).join('\n')}\n}\n`;
+  };
+  return [block(':root', tokens), block('html.dark', dark)].filter(Boolean).join('\n');
+}
+
+// Base, then components, then the theme. Each part is labelled, so "which file is this rule in"
+// is answerable from the browser's own view-source rather than by grepping.
+function assembleCss(wanted) {
+  const theme = resolveTheme(wanted);
+  const parts = [`/* base */\n${readOrEmpty(path.join(CSS_DIR, 'base.css'))}`];
+  for (const name of listComponents()) {
+    parts.push(`/* component: ${name} */\n${readOrEmpty(path.join(CSS_DIR, 'components', `${name}.css`))}`);
+  }
+  // What activated plugins add, after the components: a plugin stylesheet may only add rules.
+  for (const f of require('./plugin-loader').pluginCssFiles()) {
+    parts.push(`/* plugin: ${path.basename(f)} */\n${readOrEmpty(f)}`);
+  }
+  // A style that exists only as YAML has no stylesheet to read — its tokens are the whole palette,
+  // and they are appended below like any other override.
+  if (theme && !isYamlOnlyTheme(theme)) {
+    parts.push(`/* theme: ${theme} */\n${readOrEmpty(path.join(THEMES_DIR, theme, 'theme.css'))}`);
+  }
+  // Last, so a token set in YAML beats the same token in the theme file.
+  const overrides = themeOverridesCss(theme);
+  if (overrides) parts.push(`/* theme overrides: core/config/theme.${theme}.yml */\n${overrides}`);
+  return parts.join('\n\n');
+}
+
+
+/**
+ * Create a style from an existing one, as YAML.
+ *
+ * Every token is copied rather than referenced, so the new style is complete on its own and editing
+ * the one it came from cannot change it later. A style that inherited would be a style that moved
+ * under somebody, which is not what "based on" means when you are about to change fifteen values.
+ */
+function createTheme({ name, label, from }) {
+  const clean = String(name || '').trim().toLowerCase();
+  if (!THEME_NAME_RE.test(clean)) {
+    return { ok: false, error: 'A style name is lowercase letters, digits and hyphens, starting with a letter.' };
+  }
+  if (listThemes().includes(clean) || fs.existsSync(path.join(THEMES_DIR, clean))) {
+    return { ok: false, error: `A style called ${clean} already exists.` };
+  }
+  const source = resolveTheme(from);
+  if (!source) return { ok: false, error: 'There is no style to base it on.' };
+
+  // Whatever the source actually renders with: its YAML if it has one, else its stylesheet.
+  const fromYaml = readThemeOverrides(source);
+  let tokens = fromYaml.tokens;
+  let dark = fromYaml.dark;
+  if (!Object.keys(tokens).length) {
+    const css = readOrEmpty(path.join(THEMES_DIR, source, 'theme.css')).replace(/\/\*[\s\S]*?\*\//g, '');
+    const grab = (selector) => {
+      const out = {};
+      const re = new RegExp(`${selector}\\s*\\{([^}]*)\\}`, 'g');
+      let m;
+      while ((m = re.exec(css))) {
+        for (const d of m[1].matchAll(/(--[a-zA-Z0-9-]+)\s*:\s*([^;]+);/g)) out[d[1]] = d[2].trim();
+      }
+      return out;
+    };
+    tokens = grab(':root');
+    dark = grab('html\\.dark');
+  }
+  if (!Object.keys(tokens).length) return { ok: false, error: `${source} has no tokens to copy.` };
+
+  const title = String(label || '').trim() || clean.charAt(0).toUpperCase() + clean.slice(1).replace(/-/g, ' ');
+  // Quoted unless it is plainly safe, so a value with a colon or a hash survives the round trip.
+  const q = (v) => (/^[A-Za-z0-9._/-]+$/.test(v) ? v : `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+  const rows = (map) => Object.entries(map).map(([k, v]) => `  ${k.replace(/^--/, '')}: ${q(v)}`);
+  const lines = [
+    `# ${title} — core/config/theme.${clean}.yml`,
+    '#',
+    `# A style, created from ${source}. Every token was copied, so this file is complete on its own:`,
+    '# editing the style it came from will not change it.',
+    '#',
+    '# Change any value and reload — there is no stylesheet to edit and nothing to restart. Names go',
+    '# without the leading dashes; `tokens:` applies to both halves and `dark:` to the dark half only.',
+    '',
+    `name: ${q(title)}`,
+    '',
+    '# Made on this machine rather than shipped with the workspace. It is what the Styles page reads',
+    '# to tell the two apart — the format cannot, because the styles that ship are YAML too.',
+    'made_here: true',
+    '',
+    'tokens:',
+    ...rows(tokens),
+  ];
+  if (Object.keys(dark).length) lines.push('', '# The dark half.', 'dark:', ...rows(dark));
+
+  const file = themeOverridesFile(clean);
+  fs.writeFileSync(file, `${lines.join('\n')}\n`);
+  return { ok: true, name: clean, label: title, from: source, file, tokens: Object.keys(tokens).length };
+}
+
+
+/**
+ * The handful of values that let a style be RECOGNISED without wearing it.
+ *
+ * Choosing a style from a list of names is guessing. A swatch of its own brand colour, its surface,
+ * its line and its text — painted in those actual values — is the difference between picking one and
+ * finding out what you picked. One level of `var(--x)` is resolved, because a theme's semantic
+ * tokens are usually aliases onto its brand primitives and an unresolved alias swatches as nothing.
+ */
+function themePreview(name) {
+  const theme = resolveTheme(name);
+  if (!theme) return null;
+  const from = readThemeOverrides(theme);
+  let map = new Map(Object.entries(from.tokens));
+  if (!map.size) {
+    const css = readOrEmpty(path.join(THEMES_DIR, theme, 'theme.css')).replace(/\/\*[\s\S]*?\*\//g, '');
+    const m = /:root\s*\{([^}]*)\}/.exec(css);
+    if (m) for (const d of m[1].matchAll(/(--[a-zA-Z0-9-]+)\s*:\s*([^;]+);/g)) map.set(d[1], d[2].trim());
+  }
+  const raw = (k) => map.get(k.startsWith('--') ? k : `--${k}`) || '';
+  const value = (k) => {
+    const v = raw(k);
+    const alias = /^var\(\s*(--[a-zA-Z0-9-]+)\s*\)$/.exec(v);
+    return alias ? (raw(alias[1]) || '') : v;
+  };
+  return {
+    name: theme,
+    label: themeLabel(theme),
+    yamlOnly: isYamlOnlyTheme(theme),
+    madeHere: isMadeHere(theme),
+    tokens: map.size,
+    brand: value('brand-primary'),
+    secondary: value('brand-secondary'),
+    accent: value('brand-accent'),
+    surface: value('surface-card') || value('surface'),
+    line: value('line'),
+    text: value('text-default'),
+    // What its type actually does, so a style with a different scale reads as one in the list.
+    fontPrimary: value('font-primary'),
+    fontSecondary: value('font-secondary'),
+    sizeBody: value('size-body'),
+    sizeH2: value('size-h2'),
+    trackingH2: value('tracking-h2') || 'normal',
+  };
+}
+
+// A cache key that changes when any part does. The browser is told to cache `/style.css`, so
+// editing a component with no version change would show yesterday's stylesheet.
+function cssVersion(wanted) {
+  const files = [path.join(CSS_DIR, 'base.css'),
+    ...listComponents().map((n) => path.join(CSS_DIR, 'components', `${n}.css`)),
+    ...require('./plugin-loader').pluginCssFiles()];
+  const theme = resolveTheme(wanted);
+  if (theme) files.push(path.join(THEMES_DIR, theme, 'theme.css'), themeOverridesFile(theme));
+  let stamp = 0;
+  for (const f of files) {
+    try { stamp = Math.max(stamp, fs.statSync(f).mtimeMs); } catch (_) { /* skip */ }
+  }
+  return `${theme || 'none'}-${Math.round(stamp)}`;
+}
+
+module.exports = {
+  listThemes, themeLabel, resolveTheme, listComponents, assembleCss, cssVersion,
+  themeOverridesFile, readThemeOverrides, themeOverridesCss,
+  isYamlOnlyTheme, isMadeHere, createTheme, themePreview, THEME_NAME_RE,
+};

package/transcripts.js

@@ -0,0 +1,168 @@
+/**
+ * The voiceover script of a video, shown with it.
+ *
+ * A recording's script sits in docs/ beside the write-up, named after the video: `<video>-voiceover-script.md`.
+ * People who watch the video, or cannot hear it, want the words; this finds the script and draws the spoken
+ * lines, section by section, with the section's start time as a button that seeks the player.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('./html');
+
+const SUFFIXES = ['-voiceover-script', '-voiceover', '-transcript', '-script'];
+const HEADING = /^##\s+(\S+)\s+(.+?)\s+\(((?:\d+:)?\d{1,2}:\d{2}(?:\.\d+)?)\s+to\s+((?:\d+:)?\d{1,2}:\d{2}(?:\.\d+)?)\)\s*$/;
+const MAX_BYTES = 200 * 1024;
+
+const memo = new Map();
+
+/** The markdown files at the top of `dir`, remembered for a moment: a list asks once per row. */
+function scriptNames(dir) {
+  const hit = memo.get(dir);
+  if (hit && Date.now() - hit.at < 3000) return hit.names;
+  let names = new Set();
+  try { names = new Set(fs.readdirSync(dir).filter((n) => n.endsWith('.md'))); } catch (_) { /* no such folder */ }
+  memo.set(dir, { at: Date.now(), names });
+  return names;
+}
+
+/**
+ * The script file of a video stem, or null. It is looked for in docs/ first and then in `also`, a
+ * `{ dir, key }` for a second folder (the videos folder, where some scripts were saved beside their video).
+ */
+function findScript(docsDir, stem, also = null) {
+  for (const dir of [docsDir, also && also.dir].filter(Boolean)) {
+    const names = scriptNames(dir);
+    const hit = SUFFIXES.map((s) => `${stem}${s}.md`).find((n) => names.has(n));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Which folder holds a script `findScript` found: `{ dir, key }`, docs/ first. */
+function locateScript(docsDir, name, also = null) {
+  if (also && !scriptNames(docsDir).has(name) && scriptNames(also.dir).has(name)) return { dir: also.dir, key: also.key };
+  return { dir: docsDir, key: 'docs' };
+}
+
+/** Give every recording its script, in the same pass that built the rows. */
+function attachScripts(groups, docsDir, also = null) {
+  for (const [stem, g] of groups) {
+    if (g.video) g.script = findScript(docsDir, stem, also);
+  }
+  return groups;
+}
+
+const seconds = (stamp) => stamp.split(':').reduce((t, part) => t * 60 + parseFloat(part), 0);
+
+function stamp(sec) {
+  const s = Math.max(0, Math.round(sec));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const pad = (n) => String(n).padStart(2, '0');
+  return h ? `${h}:${pad(m)}:${pad(s % 60)}` : `${pad(m)}:${pad(s % 60)}`;
+}
+
+const spoken = (line) => line.replace(/^>\s?/, '').replace(/\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/[*`]/g, '').trim();
+
+/**
+ * The script as people read it. A timed script gives sections with their spoken lines; anything else
+ * gives its paragraphs. On-screen notes, tables and metadata are not words anyone says, so they stay out.
+ */
+function parseTranscript(text) {
+  const lines = String(text).split('\n');
+  const title = ((lines.find((l) => /^#\s+/.test(l)) || '').replace(/^#\s+/, '').trim()) || '';
+  if (lines.some((l) => HEADING.test(l))) {
+    const sections = [];
+    for (const line of lines) {
+      const h = line.match(HEADING);
+      if (h) { sections.push({ id: h[1], title: h[2], start: seconds(h[3]), end: seconds(h[4]), lines: [] }); continue; }
+      if (sections.length && line.startsWith('> ')) {
+        const optional = /\*\(optional\)\*/.test(line);
+        const t = spoken(line.replace(/\*\(optional\)\*\s*/g, ''));
+        if (t) sections[sections.length - 1].lines.push({ text: t, optional });
+      }
+    }
+    return { title, timed: true, sections: sections.filter((s) => s.lines.length) };
+  }
+  const quoted = lines.filter((l) => l.startsWith('> ')).map(spoken).filter(Boolean);
+  const paragraphs = quoted.length ? quoted
+    : String(text).split(/\n\s*\n/).map((b) => b.split('\n').filter((l) => l.trim() && !/^\s*(#|[-*+]\s|\||\d+[.)]\s)/.test(l)).join(' ').trim()).filter(Boolean);
+  return { title, timed: false, paragraphs };
+}
+
+const SOUND_TEXT = ['.txt', '.md', '-transcript.md', '-transcript.txt', '-script.md', '-voiceover-script.md'];
+const RECORD_ORDER = [['kind', 'Made as'], ['engine', 'With'], ['voice', 'Voice'], ['model', 'Model'], ['duration', 'Duration (s)'], ['seconds', 'Length (s)'],
+  ['loop', 'Loop'], ['instrumental', 'Instrumental'], ['created_utc', 'Made']];
+
+/** What belongs to a sound, beside it: the text it was made from, and the record of how. */
+function soundBelongings(dir, stem) {
+  let text = null;
+  for (const suffix of SOUND_TEXT) {
+    try {
+      const f = path.join(dir, stem + suffix);
+      if (fs.statSync(f).size <= MAX_BYTES) { text = { file: stem + suffix, content: fs.readFileSync(f, 'utf8') }; break; }
+    } catch (_) { /* not there */ }
+  }
+  let record = null;
+  try { record = JSON.parse(fs.readFileSync(path.join(dir, `${stem}.json`), 'utf8')); } catch (_) { /* none */ }
+  return { text, record };
+}
+
+function recordHtml(rec) {
+  if (!rec || typeof rec !== 'object') return '';
+  const rows = RECORD_ORDER.filter(([k]) => rec[k] !== undefined && rec[k] !== '' && typeof rec[k] !== 'object')
+    .map(([k, label]) => `<span class="sound-fact"><span class="uk-text-meta">${label}</span> ${esc(typeof rec[k] === 'boolean' ? (rec[k] ? 'yes' : 'no') : String(rec[k]))}</span>`);
+  return rows.length ? `<p class="sound-record">${rows.join('')}</p>` : '';
+}
+
+/** A sound's card: how it was made, and the words. `hrefFor` turns a file beside it into its address. */
+function soundCardHtml(dir, stem, hrefFor) {
+  const { text, record } = soundBelongings(dir, stem);
+  if (!text && !record) return null;
+  const made = record && (record.kind === 'sound' || record.kind === 'music');
+  const body = text ? transcriptHtml(parseTranscript(text.content), { file: text.file, href: hrefFor(text.file) })
+    .replace('<h4 class="uk-margin-small-bottom">Transcript', `<h4 class="uk-margin-small-bottom">${made ? 'Description' : 'Transcript'}`) : '';
+  return `<div class="sound-card">${recordHtml(record)}${body}</div>`;
+}
+
+/** The transcript as markup. `seek` makes each section's time a button the player answers to. */
+function transcriptHtml(parsed, { file, href, seek = false, heading = true } = {}) {
+  const from = file ? `<span class="uk-text-meta">from <a href="${esc(href)}" target="_blank">${esc(file)}</a></span>` : '';
+  let body;
+  if (parsed.timed) {
+    body = parsed.sections.map((s) => {
+      const time = seek
+        ? `<button type="button" class="transcript-seek" data-seek="${s.start}" title="Play from ${stamp(s.start)}">${stamp(s.start)}</button>`
+        : `<span class="transcript-time">${stamp(s.start)}</span>`;
+      return `<section class="transcript-section" data-start="${s.start}" data-end="${s.end}"><h5>${time} ${esc(s.title)}</h5>${s.lines.map((l) => `<p${l.optional ? ' class="is-optional" title="Optional: dropped when the speech runs long"' : ''}>${esc(l.text)}</p>`).join('')}</section>`;
+    }).join('');
+  } else {
+    body = parsed.paragraphs.map((p) => `<p>${esc(p)}</p>`).join('');
+  }
+  const head = heading ? `<h4 class="uk-margin-small-bottom">Transcript ${from}</h4>` : (from ? `<p class="uk-margin-small-bottom">${from}</p>` : '');
+  return `<div class="transcript">${head}<div class="transcript-body">${body || '<p class="uk-text-meta">The script has no spoken lines.</p>'}</div></div>`;
+}
+
+/** The sections of a timed script as chapters: where each starts and ends, and what it is called. */
+function chaptersFor(docsDir, scriptName, also = null) {
+  if (!scriptName) return [];
+  try {
+    const parsed = parseTranscript(fs.readFileSync(path.join(locateScript(docsDir, scriptName, also).dir, scriptName), 'utf8'));
+    return parsed.timed ? parsed.sections.map((s) => ({ start: s.start, end: s.end, title: `${s.id} ${s.title}` })) : [];
+  } catch (_) { return []; }
+}
+
+/** Read and draw a script from docs/, or null when there is none or it cannot be read. */
+function transcriptFor(docsDir, scriptName, { also = null, ...opts } = {}) {
+  if (!scriptName) return null;
+  const home = locateScript(docsDir, scriptName, also);
+  const file = path.join(home.dir, scriptName);
+  try {
+    if (fs.statSync(file).size > MAX_BYTES) return null;
+    return transcriptHtml(parseTranscript(fs.readFileSync(file, 'utf8')), { file: scriptName, href: `/files/${home.key}/${encodeURIComponent(scriptName)}`, ...opts });
+  } catch (_) { return null; }
+}
+
+module.exports = { findScript, locateScript, attachScripts, parseTranscript, transcriptHtml, transcriptFor, chaptersFor, soundBelongings, recordHtml, soundCardHtml, stamp, SUFFIXES };

package/urls.js

@@ -0,0 +1,13 @@
+/**
+ * The hub's URLs, in one place.
+ *
+ * Locally the hub is workspace.ddev.site; `hub_domain` in settings.yml points the whole scheme at a
+ * public domain instead, which is what lets this run as a remote development hub.
+ */
+
+const { hubDomain } = require('./workspaces');
+
+const HOME_URL = () => `https://${hubDomain()}`;
+const wsUrl = (key, sub = '') => `https://${key}.${hubDomain()}${sub}`;
+
+module.exports = { HOME_URL, wsUrl };

package/validate.js

@@ -0,0 +1,18 @@
+/**
+ * What a name is allowed to be.
+ *
+ * Every action that takes a project or a script name checks it against these before touching the
+ * filesystem — so a crafted name is refused at the door rather than resolved and then found to be
+ * outside the tree.
+ */
+
+const NAME_RE = /^[a-zA-Z0-9_\-]+$/;
+// A file item — a doc, a worklog, an agent — is named after its file, and those
+// names carry dots: a version in a report name, a time in a dated worklog. The
+// project rule above refuses them, which made Edit answer 400 on real files. This
+// one allows a dot inside the name while still refusing traversal: nothing may
+// start with a dot, and ".." never appears.
+const ITEM_NAME_RE = /^(?!\.)(?!.*\.\.)[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const SCRIPT_RE = /^cmd-[a-zA-Z0-9_.-]+\.sh$/;
+
+module.exports = { NAME_RE, ITEM_NAME_RE, SCRIPT_RE };

package/version-check.js

@@ -0,0 +1,94 @@
+/**
+ * Is there a newer release than the one this machine runs?
+ *
+ * The version in the top bar answers "what am I on". It cannot answer "and is that current", and a
+ * number with nothing beside it reads as up to date whether it is or not — which is how a team ends up
+ * spread across four releases with nobody aware of it.
+ *
+ * Three rules, all of them about not lying:
+ *
+ *   - **Unknown is not up to date.** This repository is private, and the dashboard's container has no
+ *     GitHub token of its own unless one is put in `.ddev/config.yaml` `web_environment` (the same gap
+ *     the AI-items repo column reports). When the check cannot be made, nothing is shown — never a
+ *     reassuring silence dressed up as a verdict.
+ *   - **Only a number that is really greater is newer.** A tag this cannot parse says nothing.
+ *   - **It never blocks a page.** The answer arrives in a fragment on its own, cached for hours, and a
+ *     page with no network renders exactly as fast as one with.
+ */
+
+const { execFile } = require('child_process');
+
+const NUMERIC = /^[0-9]+(\.[0-9]+)*$/;
+
+/**
+ * Is `candidate` a later release than `current`? Segment by segment, numerically. Anything that is not
+ * a plain dotted number is not comparable, and not comparable means no claim either way.
+ */
+function isNewer(candidate, current) {
+  const a = String(candidate || '').trim();
+  const b = String(current || '').trim();
+  if (!NUMERIC.test(a) || !NUMERIC.test(b)) return false;
+  const as = a.split('.').map(Number);
+  const bs = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(as.length, bs.length); i += 1) {
+    const x = as[i] || 0;
+    const y = bs[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+// Hours, because releases are not frequent and a check on every page load would be a network call per
+// page for an answer that changes a few times a month. A failure is remembered too, briefly: a machine
+// with no token must not shell out on every render to be told so again.
+const TTL = 6 * 60 * 60 * 1000;
+const FAIL_TTL = 10 * 60 * 1000;
+let memo = { at: 0, tag: '', error: '' };
+
+function ghLatest(repo) {
+  return new Promise((resolve) => {
+    execFile('gh', ['api', `repos/${repo}/releases/latest`, '--jq', '.tag_name'],
+      { timeout: 15000 }, (err, stdout) => {
+        const tag = String(stdout || '').trim();
+        if (!err && tag) return resolve({ tag });
+        resolve({ error: 'the repository could not be read' });
+      });
+  });
+}
+
+/**
+ * The newest release of the tooling repository, or why it is not known.
+ *
+ * `gh` first: it carries whatever auth the machine has, and this repository is private. There is no
+ * unauthenticated fallback on purpose — a plain request to a private repository answers 404, which is
+ * indistinguishable from "no releases" and would be reported as one.
+ */
+async function latestRelease(repo, { force = false } = {}) {
+  const now = Date.now();
+  const ttl = memo.error ? FAIL_TTL : TTL;
+  if (!force && memo.at && now - memo.at < ttl) return memo;
+  if (!repo) return { at: now, tag: '', error: 'no repository is configured' };
+  const { tag, error } = await ghLatest(repo);
+  memo = { at: now, tag: tag || '', error: error || '' };
+  return memo;
+}
+
+/** Forget what was read — for a test, and for a machine that has just been given a token. */
+function forget() { memo = { at: 0, tag: '', error: '' }; }
+
+/**
+ * What the top bar should say beside the version: nothing at all unless a newer release really exists.
+ * Not "up to date", not "could not check" — the version is read in passing, and a line of chrome that
+ * says nothing useful on every page of every machine is worse than a blank.
+ */
+async function updateHintHtml({ current, repo, host = 'github.com', esc }) {
+  if (!current) return '';
+  const { tag } = await latestRelease(repo);
+  if (!tag || !isNewer(tag, current)) return '';
+  const href = `https://${host}/${repo}/releases/tag/${encodeURIComponent(tag)}`;
+  return `<a class="version-new" href="${esc(href)}" target="_blank" rel="noopener"
+    title="${esc(`${tag} has been released — this machine runs ${current}. Update with: bash core/workspace-app/scripts/update.sh`)}"
+    ><span uk-icon="icon: arrow-up; ratio: .7"></span>${esc(tag)}</a>`;
+}
+
+module.exports = { isNewer, latestRelease, updateHintHtml, forget, TTL, FAIL_TTL };