synabun 2.0.9 → 2.1.0

package/neural-interface/public/shared/skills/studio/sx-test.js

@@ -0,0 +1,328 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio 2.0: the Test tab, what it decides (P4)
+// ═══════════════════════════════════════════
+//
+// Everything the Test tab decides without a page (sx-test-view.js draws it): whether this workspace can be tested
+// and which version is, the form and its defaults (one press of Run evals runs the train and validation cases once on
+// the first runtime that can, against no skill, within $3 and 30 minutes), the request it sends, the runtime and model
+// choices (the server's runtimes, the Assistant's one model catalog), and what a run shows: the headline per runtime,
+// the case rows, the trigger rows, the suite notes, whether a result is stale, the history and the trial navigation.
+// Strings are the view's (skillsStudio.test.*): this module returns codes and numbers.
+
+import { EVALS_PATH, readSuite } from '../ss-evals.js';
+import { BUDGET_CHOICES, EVAL_DEFAULTS, MINUTE_CHOICES, REPETITION_CHOICES, isActiveEvalRun, runtimeKey, suiteCounts } from '../ss-eval-plan.js';
+import { staleness } from '../ss-eval-grade.js';
+import { optimiserSplits } from '../ss-eval-optimise.js';
+
+export { isActiveEvalRun, BUDGET_CHOICES, MINUTE_CHOICES, REPETITION_CHOICES };
+export const TEST_KIND_CHOICES = Object.freeze(['both', 'task', 'trigger']);
+export const BASELINE_CHOICES = Object.freeze(['no-skill', 'revision', 'off']);
+export const EXPORT_FORMATS = Object.freeze(['native', 'skill-creator', 'agent-skills']);
+export const TEST_FORM_KEY = 'skills-studio-test-form';
+const PROVIDERS = ['claude-code', 'codex', 'opencode'];
+
+
+/** Label an executed runtime and retain a visibly different requested target. */
+export function executionLabel(t, actual, requested, label = r => `${r.provider}${r.model ? `/${r.model}` : ''}`) {
+  const requests = (Array.isArray(requested) ? requested : [requested]).filter(Boolean);
+  const shown = label(actual || requests[0] || {});
+  const different = requests.filter(r => r.provider !== actual?.provider || (r.model || null) !== (actual?.model || null));
+  return different.length && actual ? t('skillsStudio.test.runtimeActual', { actual: shown, requested: different.map(label).join(', ') }) : shown;
+}
+
+/** API errors are codes, never server prose. Unknown failures keep a diagnostic code in the page's language. */
+export function testErrorText(t, error) {
+  const code = error?.code || error?.body?.code;
+  const keys = {
+    WORKER_BROWSER: 'workerBrowser',
+    PAGE_SECRET_REQUIRED: 'pageSession', UI_HEADER_REQUIRED: 'pageSession',
+    GUEST_FORBIDDEN: 'owner', UI_ONLY: 'owner', WORKERS_NOT_PERMITTED: 'owner',
+    ASSISTANT_CREDENTIAL_REQUIRED: 'owner', OWNER_REQUIRED: 'owner',
+    runtime_unavailable: 'unavailable', grader_unavailable: 'unavailable',
+    model_unavailable: 'unavailable', MODEL_UNKNOWN: 'unavailable', MODEL_DISABLED: 'unavailable',
+    codex_not_confirmed: 'codex', not_found: 'missing', revision_not_found: 'missing',
+    queue_full: 'queueFull', evals_unavailable: 'notReady', suite_invalid: 'suite',
+    optimise_unavailable: 'optimise', time_below_estimate: 'time',
+  };
+  if (keys[code]) return t(`skillsStudio.test.errors.${keys[code]}`);
+  return t('skillsStudio.test.errors.request', { code: typeof code === 'string' && /^[a-zA-Z0-9_-]{1,80}$/.test(code) ? code : 'network' });
+}
+
+/**
+ * A problem of the suite the page words in its own language: the skillsStudio.test.head.* string and its values for a
+ * test file a runtime would load by itself (its settings or code, an instruction file at the top of the test folder,
+ * a name another file system reads as another file's), or null (the problem's own words are shown).
+ */
+export function suiteErrorCopy(e) {
+  if (!e || typeof e.file !== 'string' || !e.file) return null;
+  if (e.code === 'file-config') return { key: 'skillsStudio.test.head.fixtureConfig', params: { file: e.file, name: e.name || '' } };
+  if (e.code === 'file-instructions') return { key: 'skillsStudio.test.head.fixtureInstructions', params: { file: e.file, name: e.name || '' } };
+  if (e.code === 'file-alias') return { key: 'skillsStudio.test.head.fixtureAlias', params: { file: e.file } };
+  return null;
+}
+
+/**
+ * Whether a workspace can be tested, and which version: a library skill's latest revision (the draft's unsaved or
+ * unversioned changes are not in it: the tab says so). → { mode, revisionId, draftChanged }
+ *   mode: 'ok' | 'older-server' (no `evals` capability yet) | 'not-library' (a folder of a runtime: add it to the
+ *   library first) | 'no-revision' (a new draft with no version yet) | 'guest'
+ */
+export function testSubject(ws, { caps = new Set(), capsKnown = true, guest = false, changedFiles = () => [] } = {}) {
+  if (guest) return { mode: 'guest', revisionId: null, draftChanged: false };
+  if (capsKnown && !caps.has('evals')) return { mode: 'older-server', revisionId: null, draftChanged: false };
+  const s = ws?.subject || {};
+  if (s.readsFiles !== 'library' || !ws.skill) return { mode: 'not-library', revisionId: null, draftChanged: false, canAdopt: !!s.canAdopt };
+  const revisionId = ws.skill.pointers?.latest || ws.revision?.revisionId || null;
+  if (!revisionId) return { mode: 'no-revision', revisionId: null, draftChanged: false };
+  const draftChanged = !!(ws.draft && ws.revision && changedFiles(ws.revision.manifest?.files || [], ws.draft.files || []).length);
+  return { mode: 'ok', revisionId, draftChanged };
+}
+
+/** Whether the tested version has test prompts (its manifest names evals/evals.json). */
+export const hasSuite = (revision) => !!(revision?.manifest?.files || []).some((f) => f.path === EVALS_PATH);
+
+/** The suite as the page reads it (the same reader as the server): cases, counts, errors, warnings. */
+export function readSuiteText(text, { skillName = '', description = '' } = {}) {
+  const read = readSuite(String(text ?? ''), { skillName, description });
+  return { ok: read.ok, errors: read.errors, warnings: read.warnings, cases: read.cases, counts: suiteCounts(read.cases) };
+}
+
+/** What the suite allows: a final check needs held-out cases; an optimisation a positive and a near-miss to train on and a validation case. */
+export function suiteAllows(cases) {
+  const list = cases || [];
+  const optimise = optimiserSplits(list);
+  return {
+    run: list.some((c) => c.split !== 'test'),
+    final: list.some((c) => c.split === 'test'),
+    optimise: optimise.problems.length === 0,
+    optimiseProblems: optimise.problems,
+    tasks: list.some((c) => c.kind === 'task' && c.split !== 'test'),
+    triggers: list.some((c) => c.kind === 'trigger' && c.split !== 'test'),
+  };
+}
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** A runtime the owner opts into per skill version (Codex: its shell can read files anywhere on the computer). */
+export const isOptInRuntime = (provider, options = null) => provider === 'codex' || !!(options?.runtimes || []).find((r) => r.provider === provider && r.optIn);
+
+/**
+ * The form, from what was kept and what the server can run: the first runtime that can start (Claude Code first; never
+ * an opt-in one such as Codex, which the owner picks each time), its cheap default model, both kinds, no-skill
+ * baseline, once, $3, 30 minutes, blind comparisons where the cases ask.
+ */
+export function defaultForm(options, stored = null) {
+  const runtimes = (options?.runtimes || []).filter((r) => r.available);
+  const first = runtimes.find((r) => !isOptInRuntime(r.provider, options))?.provider || runtimes[0]?.provider || 'claude-code';
+  const s = isObject(stored) ? stored : {};
+  const keepRuntime = (v) => typeof v === 'string' && runtimes.some((r) => r.provider === v.split('|')[0]) && !isOptInRuntime(v.split('|')[0], options);
+  const picks = Array.isArray(s.runtimes) ? s.runtimes.filter(keepRuntime).slice(0, 3) : [];
+  return {
+    kinds: TEST_KIND_CHOICES.includes(s.kinds) ? s.kinds : 'both',
+    runtimes: picks.length ? [...new Set(picks)] : [first],
+    baseline: BASELINE_CHOICES.includes(s.baseline) ? s.baseline : EVAL_DEFAULTS.baseline,
+    baselineRevisionId: typeof s.baselineRevisionId === 'string' ? s.baselineRevisionId : '',
+    taskReps: REPETITION_CHOICES.includes(s.taskReps) ? s.taskReps : EVAL_DEFAULTS.repetitions.task,
+    triggerReps: REPETITION_CHOICES.includes(s.triggerReps) ? s.triggerReps : EVAL_DEFAULTS.repetitions.trigger,
+    grader: typeof s.grader === 'string' && (s.grader === '' || keepRuntime(s.grader)) ? s.grader : '',
+    budgetUsd: BUDGET_CHOICES.includes(s.budgetUsd) ? s.budgetUsd : EVAL_DEFAULTS.budgetUsd,
+    maxMinutes: MINUTE_CHOICES.includes(s.maxMinutes) ? s.maxMinutes : EVAL_DEFAULTS.maxMinutes,
+    judge: s.judge !== false,
+  };
+}
+
+/** What of a form is kept between openings (no revision ids of one skill leak into another's form; Codex is not kept). */
+export const storedForm = (form) => ({ kinds: form.kinds, runtimes: form.runtimes.filter((v) => !isOptInRuntime(String(v).split('|')[0])), baseline: form.baseline === 'revision' ? 'no-skill' : form.baseline, taskReps: form.taskReps, triggerReps: form.triggerReps, grader: isOptInRuntime(String(form.grader || '').split('|')[0]) ? '' : form.grader, budgetUsd: form.budgetUsd, maxMinutes: form.maxMinutes, judge: form.judge });
+
+/** Whether a form puts Codex to work (a runtime row, or the grader). */
+export const formUsesCodex = (form) => (form?.runtimes || []).some((v) => String(v).split('|')[0] === 'codex') || String(form?.grader || '').split('|')[0] === 'codex';
+
+/**
+ * What the Test tab says about Codex for a form and its estimate: null when the form does not use Codex, else
+ * { confirmed, at (when the newest confirmation was made), revisionIds (the versions to confirm: the tested one, and
+ * the earlier one it is compared with on Codex) }. Unknown until the estimate says: not confirmed.
+ */
+export function codexStatus(form, estimate, { revisionId = null } = {}) {
+  if (!formUsesCodex(form)) return null;
+  const c = estimate?.codex;
+  const revisions = Array.isArray(c?.revisions) && c.revisions.length ? c.revisions : [{ revisionId, trusted: false, at: null }];
+  const at = revisions.map((r) => r.at).filter(Boolean).sort().pop() || null;
+  return { confirmed: c ? c.confirmed === true : false, at, revisionIds: revisions.map((r) => r.revisionId).filter(Boolean), pending: revisions.filter((r) => !r.trusted).map((r) => r.revisionId).filter(Boolean) };
+}
+
+/**
+ * The safety lines of the Test tab, per runtime the form uses (codes; the view words them): 'held' for Claude Code
+ * and OpenCode (only the skill under test, the folder, a shell with no network and no home folder), 'codex' for Codex.
+ */
+export function safetyLines(form, options = null) {
+  const used = [...new Set((form?.runtimes || []).map((v) => String(v).split('|')[0]).filter(Boolean))];
+  const known = (options?.runtimes || []).map((r) => r.provider);
+  return used.filter((p) => !known.length || known.includes(p)).map((provider) => ({ provider, code: isOptInRuntime(provider, options) ? 'codex' : 'held', shell: (options?.runtimes || []).find((r) => r.provider === provider)?.shell === true }));
+}
+
+/** A runtime value of the form ("provider" or "provider|model") as the request names it. */
+export function runtimeOf(value) {
+  const [provider, ...rest] = String(value || '').split('|');
+  const model = rest.join('|');
+  return PROVIDERS.includes(provider) ? { provider, ...(model ? { model } : {}) } : null;
+}
+
+/**
+ * The request a press sends. `purpose`: 'evals' (Run evals), 'final' (the held-out check), 'optimise' (the
+ * description: triggers only, three repetitions, one runtime). `caseIds`: a rerun of some cases.
+ */
+export function requestOf(form, { revisionId, purpose = 'evals', caseIds = null } = {}) {
+  const runtimes = form.runtimes.map(runtimeOf).filter(Boolean);
+  const body = { revisionId, purpose, runtimes: purpose === 'optimise' ? runtimes.slice(0, 1) : runtimes, budgetUsd: form.budgetUsd, maxMinutes: form.maxMinutes, judge: form.judge };
+  if (purpose !== 'optimise') {
+    body.kinds = form.kinds === 'both' ? ['task', 'trigger'] : [form.kinds];
+    body.baseline = form.baseline;
+    if (form.baseline === 'revision' && form.baselineRevisionId) body.baselineRevisionId = form.baselineRevisionId;
+    body.repetitions = { task: form.taskReps, trigger: form.triggerReps };
+  } else body.repetitions = { trigger: Math.max(3, form.triggerReps) };
+  if (form.grader) body.grader = runtimeOf(form.grader);
+  if (Array.isArray(caseIds) && caseIds.length) body.caseIds = caseIds;
+  return body;
+}
+
+/**
+ * A runtime dropdown's entries: per provider its default (the server's cheap model) and the catalog's models; a
+ * provider that cannot run here is one greyed line with its reason. `words`: { provider(p), providerDefault(p, model),
+ * providerOff(p, reason) }.
+ */
+export function runtimeEntries({ options, catalog = null, selected = '', words, allowNone = false, noneLabel = '' }) {
+  const entries = allowNone ? [{ value: '', label: noneLabel, selected: !selected }] : [];
+  for (const row of options?.runtimes || []) {
+    const p = row.provider;
+    if (!row.available) { entries.push({ group: words.provider(p), options: [{ value: p, label: words.providerOff(p, row.reason || ''), disabled: true, selected: false }] }); continue; }
+    const options_ = [{ value: p, label: words.providerDefault(p, row.defaultModel || ''), selected: selected === p }];
+    for (const m of (Array.isArray(catalog?.[p]) ? catalog[p] : []).slice(0, 60)) {
+      if (!m?.id || m.status === 'unavailable') continue;
+      const value = `${p}|${m.id}`;
+      options_.push({ value, label: String(m.label || m.id), selected: selected === value });
+    }
+    entries.push({ group: words.provider(p), options: options_ });
+  }
+  if (selected && !entries.some((e) => (e.options || [e]).some((o) => o.value === selected))) {
+    const r = runtimeOf(selected);
+    if (r) entries.push({ value: selected, label: `${words.provider(r.provider)}${r.model ? ` · ${r.model}` : ''}`, selected: true });
+  }
+  return entries;
+}
+
+/** The trials of a run grouped for its live list: per case, its trials in order. */
+export function trialGroups(run) {
+  const groups = new Map();
+  for (const t of run?.trials || []) {
+    const key = `${t.kind}:${t.caseId}`;
+    if (!groups.has(key)) groups.set(key, { kind: t.kind, caseId: t.caseId, split: t.split, trials: [] });
+    groups.get(key).trials.push(t);
+  }
+  return [...groups.values()];
+}
+
+/** The state word of a trial for its dot and its label: running, passed, failed, picked, skipped… */
+export function trialTone(t) {
+  if (t.status === 'running') return 'running';
+  if (t.status === 'pending') return 'pending';
+  if (['skipped', 'cancelled'].includes(t.status)) return 'skipped';
+  if (t.status !== 'completed') return 'error';
+  if (t.kind === 'trigger') {
+    const o = t.trigger?.observed ?? t.observed;
+    if (o === null || o === undefined) return 'error';
+    return o === t.expected || (t.expected === undefined && o) ? 'pass' : 'fail';
+  }
+  const rate = t.grade?.passRate ?? t.passRate;
+  if (rate === null || rate === undefined) return 'neutral';
+  return rate >= 0.999 ? 'pass' : rate > 0 ? 'partial' : 'fail';
+}
+
+/** How long a run has worked so far, in seconds. */
+export function elapsedSeconds(run, now = Date.now()) {
+  const from = Date.parse(run?.startedAt || run?.createdAt || '');
+  if (!Number.isFinite(from)) return 0;
+  const to = run?.finishedAt ? Date.parse(run.finishedAt) : now;
+  return Math.max(0, Math.round((to - from) / 1000));
+}
+export const clockText = (s) => `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
+
+/**
+ * What a finished (or partial) run shows: one headline per runtime, the task case rows, the trigger rows, the notes
+ * about the suite, and why it is stale. Numbers are left as numbers (or null: not measured).
+ */
+export function reportModel(run, { latestRevisionId = null, latestSuiteDigest = null } = {}) {
+  const summary = run?.summary || { runtimes: [], notes: [] };
+  const stale = staleness(run, { latestRevisionId, latestSuiteDigest });
+  return {
+    stale,
+    runtimes: (summary.runtimes || []).map((r) => ({
+      key: r.key, provider: r.provider, model: r.model, requestedRuntimes: r.requestedRuntimes || [],
+      task: r.task ? {
+        candidate: r.task.candidate?.mean ?? null, baseline: r.task.baseline?.mean ?? null, delta: r.task.delta, pairs: r.task.pairs,
+        n: r.task.candidate?.n || 0, sd: r.task.candidate?.sd ?? null,
+        cases: r.task.cases.map((c) => ({ ...c, candidateRate: c.candidate?.mean ?? null, baselineRate: c.baseline?.mean ?? null })),
+      } : null,
+      trigger: r.trigger,
+      preference: r.preference, costUsd: r.costUsd, durationMs: r.durationMs?.mean ?? null, failedRuns: r.failedRuns, skipped: r.skipped,
+    })),
+    notes: summary.notes || [],
+    baseline: run?.request?.baseline || 'no-skill',
+  };
+}
+
+/** A history row: the run, whether it tested the version as it is now, its headline numbers. */
+export function historyRows(list, { latestRevisionId = null, latestSuiteDigest = null } = {}) {
+  return (list || []).map((r) => {
+    const first = r.summary?.runtimes?.[0] || null;
+    return {
+      evalRunId: r.evalRunId, state: r.state, createdAt: r.createdAt, purpose: r.request?.purpose || 'evals',
+      runtimeDetails: r.summary?.runtimes?.length ? r.summary.runtimes : r.request?.runtimes || [],
+      runtimes: (r.summary?.runtimes?.length ? r.summary.runtimes : r.request?.runtimes || []).map(runtimeKey), costUsd: r.spend?.usd ?? null,
+      stale: staleness(r, { latestRevisionId, latestSuiteDigest }), revisionId: r.skill?.revisionId || null,
+      task: first?.task ? { candidate: first.task.candidate?.mean ?? null, baseline: first.task.baseline?.mean ?? null, delta: first.task.delta } : null,
+      trigger: first?.trigger ? { passed: first.trigger.passed, total: first.trigger.queries } : null,
+      optimise: r.optimise || null, queuePosition: r.queuePosition || null, progress: r.progress || null,
+    };
+  });
+}
+
+/** The trial after (dir 1) or before (dir -1) one, among a run's trials that ran, wrapping around. */
+export function trialStep(run, trialId, dir = 1) {
+  const list = (run?.trials || []).filter((t) => !['pending', 'skipped', 'cancelled'].includes(t.status));
+  if (!list.length) return null;
+  const at = list.findIndex((t) => t.trialId === trialId);
+  if (at < 0) return list[0].trialId;
+  return list[(at + dir + list.length) % list.length].trialId;
+}
+
+/**
+ * The same case in the previous finished run of the skill (its answer beside this one's): the newest earlier run with a
+ * trial of the same case, configuration and runtime. → { evalRunId, trialId } or null. `runs` are full views.
+ */
+export function previousTrial(runs, current, trial) {
+  const earlier = (runs || []).filter((r) => r.evalRunId !== current.evalRunId && Date.parse(r.createdAt) < Date.parse(current.createdAt) && Array.isArray(r.trials))
+    .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+  for (const r of earlier) {
+    const t = r.trials.find((x) => x.caseId === trial.caseId && x.configuration === trial.configuration && runtimeKey(x.runtime) === runtimeKey(trial.runtime) && x.status === 'completed');
+    if (t) return { evalRunId: r.evalRunId, trialId: t.trialId };
+  }
+  return null;
+}
+
+/** The cases of a run worth running again: task cases that failed an assertion or did not finish, triggers read wrong or not at all. */
+export function rerunCases(run) {
+  const ids = new Set();
+  for (const t of run?.trials || []) {
+    if (t.configuration !== 'candidate' || t.split === 'test') continue;
+    const tone = trialTone(t);
+    if (['fail', 'partial', 'error'].includes(tone)) ids.add(t.caseId);
+  }
+  return [...ids];
+}
+
+/** A pass rate (0…1) as whole percent text; null as an em dash. */
+export const pct = (x) => (x === null || x === undefined || !Number.isFinite(x) ? '—' : `${Math.round(x * 100)}%`);
+/** A difference of pass rates as signed percentage points. */
+export const pts = (x) => (x === null || x === undefined || !Number.isFinite(x) ? '—' : `${x >= 0 ? '+' : '−'}${Math.round(Math.abs(x) * 100)}`);
+/** Dollars with two decimals (four under a cent). */
+export const money = (x) => (x === null || x === undefined || !Number.isFinite(Number(x)) ? '—' : `$${Number(x) < 0.01 && Number(x) > 0 ? Number(x).toFixed(4) : Number(x).toFixed(2)}`);

package/neural-interface/public/shared/skills/studio/sx-versions-view.js

@@ -0,0 +1,241 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio 2.0: the Versions tab
+// ═══════════════════════════════════════════
+//
+// A library skill's history: its draft (the working copy, with the files changed since its version) and every
+// revision, newest first, each with its labels (latest, candidate, best, approved, from SynaBun, installed where),
+// who made it, from what, and when. Two revisions are compared file by file (the service's diff); the draft is
+// compared with its version here. A revision comes back as a new draft (the draft that is there is saved as a
+// version first, or replaced: the owner says); candidate and best are marked by the owner. Approved moves only
+// through Review, and SynaBun's own versions only through an update of the app.
+
+import { scanText, scanFindingText, scanReasonText } from './sx-scan.js';
+import { studioErrorText } from './sx-errors.js';
+import { dropdownHTML, wireDropdowns } from '../../cc-dropdown.js';
+import { html, raw, setHTML, ICONS, relativeTime, fullTime } from './sx-dom.js';
+import { serviceDiff, changedFiles, lineDiff } from './sx-diff.js';
+import { diffHTML, textDiffModel } from './sx-diff-view.js';
+import { dirtyTabs, resetDocuments, saveVersion } from './sx-docs.js';
+import { shortDigest } from './sx-editor-model.js';
+import { choosePublishRevision } from './sx-plan.js';
+import { adoptNow } from './sx-actions.js';
+
+let _life = null;
+const LABELS = ['latest', 'candidate', 'best', 'approved', 'upstream'];
+
+function authorWords(t, a) {
+  if (!a || a.kind === 'owner') return t('skillsStudio.versions.author.owner');
+  if (a.kind === 'system') return t('skillsStudio.versions.author.system');
+  const who = a.kind === 'assistant' ? t('skillsStudio.versions.author.assistant') : t('skillsStudio.versions.author.agent');
+  return a.model ? `${who} · ${a.model}` : who;
+}
+
+function installedOn(ws, revisionId, t) {
+  return [...new Set((ws.skill?.installations || []).filter((i) => i.sourceRevisionId === revisionId).map((i) => t(`skillsStudio.runtime.${i.runtime}`)))];
+}
+
+function revisionRow(ctx, ws, rev, i, list) {
+  const { t, locale } = ctx;
+  const labels = (rev.labels || []).filter((l) => LABELS.includes(l));
+  const installed = installedOn(ws, rev.revisionId, t);
+  const prev = list.slice(i + 1).find((r) => r.integrity !== 'damaged') || null;
+  const damaged = rev.integrity === 'damaged';
+  const owner = !damaged && !ctx.guest && ws.subject.mode === 'library';
+  return html`<li class="sx-version" data-rev="${rev.revisionId}">
+    <div class="sx-version-main">
+      <span class="sx-version-id" title="${rev.revisionId}">${t('skillsStudio.versions.rev', { id: shortDigest(rev.contentDigest) })}</span>
+      ${labels.map((l) => html`<span class="sx-label sx-label--${l}">${t(`skillsStudio.versions.label.${l}`)}</span>`)}
+      ${installed.length ? html`<span class="sx-label sx-label--installed" title="${installed.join(', ')}">${t('skillsStudio.versions.label.installed', { where: installed.join(', ') })}</span>` : ''}
+      <span class="sx-spacer"></span>
+      <time class="sx-dim" datetime="${rev.createdAt}" title="${fullTime(rev.createdAt, locale)}">${relativeTime(rev.createdAt, locale)}</time>
+    </div>
+    <p class="sx-version-meta">${authorWords(t, rev.author)} · ${t(`skillsStudio.versions.source.${['bundled', 'adopted', 'draft', 'assistant', 'import', 'restore', 'customize', 'local', 'github'].includes(rev.source?.kind) ? rev.source.kind : 'local'}`)}${rev.source?.appVersion ? ` ${rev.source.appVersion}` : ''} · ${ctx.tp('skillsStudio.versions.files', rev.files || 0)}${rev.note && rev.noteCode !== 'bundled' ? html` · <span class="sx-version-note">${rev.note}</span>` : ''}</p>
+    ${damaged ? html`<p class="sx-note sx-note--warn" role="status">${t('skillsStudio.errors.revisionDamaged')}</p>` : ''}
+    <button type="button" class="sx-btn sx-btn--sm" ${damaged ? raw('disabled') : ''} data-ver="scan" aria-controls="sx-ver-scan" data-rev="${rev.revisionId}">${scanText(t, rev.scan, rev.contentDigest)}</button>
+    <div class="sx-version-actions">
+      ${prev && !damaged && prev.integrity !== 'damaged' ? html`<button type="button" class="sx-btn sx-btn--sm" data-ver="diff-prev" data-rev="${rev.revisionId}" data-prev="${prev.revisionId}">${t('skillsStudio.versions.diffPrev')}</button>` : ''}
+      ${owner ? html`<button type="button" class="sx-btn sx-btn--sm" data-ver="restore" data-rev="${rev.revisionId}">${t('skillsStudio.versions.restore')}</button>
+        ${labels.includes('candidate') ? '' : html`<button type="button" class="sx-btn sx-btn--sm sx-btn--ghost" data-ver="candidate" data-rev="${rev.revisionId}">${t('skillsStudio.versions.markCandidate')}</button>`}
+        ${labels.includes('best') ? '' : html`<button type="button" class="sx-btn sx-btn--sm sx-btn--ghost" data-ver="best" data-rev="${rev.revisionId}">${t('skillsStudio.versions.markBest')}</button>`}` : ''}
+      ${ws.subject.canPublish && !damaged ? html`<button type="button" class="sx-btn sx-btn--sm" data-ver="publish" data-rev="${rev.revisionId}">${t('skillsStudio.versions.publishThis')}</button>` : ''}
+    </div>
+  </li>`;
+}
+
+/** Draw the Versions tab. */
+export function renderVersionsTab(panel, ctx, ws) {
+  const { t } = ctx;
+  _life?.abort();
+  _life = new AbortController();
+  const signal = _life.signal;
+  if (ws.subject.mode !== 'library' && !(ws.subject.mode === 'readonly' && ws.skill)) {
+    const why = ws.subject.mode === 'adopt' ? 'adopt' : ws.subject.mode === 'inplace' ? 'inplace' : 'readonly';
+    setHTML(panel, html`<div class="sx-empty"><span class="sx-placeholder-icon" aria-hidden="true">${ICONS.history}</span>
+      <h4 class="sx-empty-title">${t('skillsStudio.versions.noneTitle')}</h4><p>${t(`skillsStudio.versions.none.${why}`)}</p>
+      ${why === 'adopt' && !ctx.guest ? html`<button type="button" class="sx-btn sx-btn--primary" data-ver="adopt">${t('skillsStudio.ws.adoptNow')}</button>` : ''}</div>`);
+    panel.querySelector('[data-ver="adopt"]')?.addEventListener('click', () => adoptNow(ctx, ws), { signal });
+    return;
+  }
+  setHTML(panel, html`<div class="sx-versions"><p class="sx-help" role="status">${t('skillsStudio.versions.loading')}</p></div>`);
+  const gen = ctx.gen();
+  ctx.api.fetchSkillRevisions(ws.skill.skillId).then((res) => {
+    if (!ctx.alive(gen) || !ws.shown || ws.tab !== 'versions') return;
+    ws.revisions = (res.revisions || []).slice().sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+    draw(panel, ctx, ws, signal);
+  }).catch((err) => {
+    if (!ctx.alive(gen) || ws.tab !== 'versions') return;
+    setHTML(panel, html`<div class="sx-empty" role="alert"><p>${t('skillsStudio.versions.loadFailed', { error: studioErrorText(ctx.t, err) })}</p></div>`);
+  });
+}
+
+function draw(panel, ctx, ws, signal) {
+  const { t } = ctx;
+  const list = ws.revisions || [];
+  const comparable = list.filter((r) => r.integrity !== 'damaged');
+  const draftChanges = ws.draft && ws.revision ? changedFiles(ws.revision.manifest?.files || [], ws.draft.files || []) : [];
+  const pick = (id, label, selected) => raw(dropdownHTML(id, comparable.map((r, i) => ({ value: r.revisionId, label: `${t('skillsStudio.versions.rev', { id: shortDigest(r.contentDigest) })}${r.labels?.length ? ` · ${r.labels.filter((l) => LABELS.includes(l)).map((l) => t(`skillsStudio.versions.label.${l}`)).join(', ')}` : ''}`, selected: selected ? r.revisionId === selected : i === 0 })), { label }));
+  setHTML(panel, html`<div class="sx-versions">
+    <div class="sx-versions-head">
+      <h4 class="sx-section-title">${ctx.tp('skillsStudio.versions.title', list.length)}</h4>
+      <span class="sx-spacer"></span>
+      ${comparable.length > 1 ? html`<div class="sx-compare-pick"><span class="sx-filter-key">${t('skillsStudio.versions.from')}</span>${pick('sx-ver-from', t('skillsStudio.versions.from'), comparable[1]?.revisionId)}
+        <span class="sx-filter-key">${t('skillsStudio.versions.to')}</span>${pick('sx-ver-to', t('skillsStudio.versions.to'), comparable[0]?.revisionId)}
+        <button type="button" class="sx-btn sx-btn--sm" data-ver="diff-pick">${t('skillsStudio.versions.compare')}</button></div>` : ''}
+    </div>
+    <ol class="sx-timeline">
+      ${ws.draft ? html`<li class="sx-version sx-version--draft">
+        <div class="sx-version-main"><span class="sx-version-id">${t('skillsStudio.versions.draft')}</span><span class="sx-label sx-label--draft">${t('skillsStudio.versions.label.draft')}</span><span class="sx-spacer"></span>
+          ${ws.draft.updatedAt ? html`<time class="sx-dim" datetime="${ws.draft.updatedAt}" title="${fullTime(ws.draft.updatedAt, ctx.locale)}">${relativeTime(ws.draft.updatedAt, ctx.locale)}</time>` : ''}</div>
+        <p class="sx-version-meta">${draftChanges.length ? ctx.tp('skillsStudio.versions.draftChanged', draftChanges.length) : t('skillsStudio.versions.draftSame')}</p>
+        <div class="sx-version-actions">
+          ${draftChanges.length ? html`<button type="button" class="sx-btn sx-btn--sm" data-ver="diff-draft">${t('skillsStudio.versions.diffDraft')}</button>` : ''}
+          ${draftChanges.length && !ctx.guest ? html`<button type="button" class="sx-btn sx-btn--sm sx-btn--primary" data-ver="snapshot">${t('skillsStudio.ws.saveVersion')}</button>` : ''}
+        </div></li>` : ''}
+      ${list.map((rev, i) => revisionRow(ctx, ws, rev, i, list))}
+    </ol>
+    ${list.length ? '' : html`<p class="sx-help">${t('skillsStudio.versions.noRevisions')}</p>`}
+    <section class="sx-diff-box" id="sx-ver-scan" aria-live="polite"></section>
+    <section class="sx-diff-box" id="sx-ver-diff" aria-live="polite"></section>
+  </div>`);
+  wireDropdowns(panel, { signal });
+  panel.addEventListener('click', (e) => {
+    const btn = e.target.closest?.('[data-ver]');
+    if (!btn || btn.disabled) return;
+    onAction(btn.dataset.ver, btn, panel, ctx, ws, signal);
+  }, { signal });
+}
+
+async function showDiff(panel, ctx, from, to) {
+  const { t } = ctx;
+  const box = panel.querySelector('#sx-ver-diff');
+  if (!box) return;
+  setHTML(box, html`<p class="sx-help">${t('skillsStudio.versions.comparing')}</p>`);
+  const gen = ctx.gen();
+  try {
+    const res = await ctx.api.fetchSkillsDiff(from, to);
+    if (!ctx.alive(gen) || !box.isConnected) return;
+    setHTML(box, html`<h4 class="sx-section-title">${t('skillsStudio.versions.diffTitle')}</h4>${diffHTML(t, serviceDiff(res.diff))}`);
+  } catch (err) { if (box.isConnected) setHTML(box, html`<p class="sx-note sx-note--warn" role="alert">${t('skillsStudio.versions.diffFailed', { error: studioErrorText(ctx.t, err) })}</p>`); }
+}
+
+async function showDraftDiff(panel, ctx, ws) {
+  const { t } = ctx;
+  const box = panel.querySelector('#sx-ver-diff');
+  if (!box || !ws.draft || !ws.revision) return;
+  setHTML(box, html`<p class="sx-help">${t('skillsStudio.versions.comparing')}</p>`);
+  const gen = ctx.gen();
+  const changes = changedFiles(ws.revision.manifest?.files || [], ws.draft.files || []);
+  const files = [];
+  for (const c of changes.slice(0, 30)) {
+    const binary = (ws.revision.manifest?.files || []).find((f) => f.path === c.path)?.encoding === 'binary';
+    if (binary) { files.push({ path: c.path, status: c.status, hunks: [], added: 0, removed: 0, note: 'binary' }); continue; }
+    try {
+      const before = c.status === 'added' ? '' : ((await ctx.api.fetchSkillsRevisionFile(ws.revision.revisionId, c.path)).content ?? '');
+      const afterRes = c.status === 'removed' ? { content: '' } : await ctx.api.fetchSkillsDraftFile(ws.draft.draftId, c.path);
+      if (typeof afterRes.contentBase64 === 'string') { files.push({ path: c.path, status: c.status, hunks: [], added: 0, removed: 0, note: 'binary' }); continue; }
+      const d = lineDiff(before, afterRes.content ?? '');
+      files.push({ ...textDiffModel(c.path, d).files[0] || { path: c.path, hunks: [], added: 0, removed: 0 }, status: c.status });
+    } catch { files.push({ path: c.path, status: c.status, hunks: [], added: 0, removed: 0, note: 'too large to compare line by line' }); }
+  }
+  if (!ctx.alive(gen) || !box.isConnected) return;
+  setHTML(box, html`<h4 class="sx-section-title">${t('skillsStudio.versions.diffDraftTitle')}</h4>${diffHTML(t, { files })}`);
+}
+
+async function onAction(act, btn, panel, ctx, ws, signal) {
+  const { t, tp } = ctx;
+  if (act === 'scan') {
+    const box = panel.querySelector('#sx-ver-scan');
+    const gen = ctx.gen();
+    setHTML(box, html`<p role="status">${t('skillsStudio.scan.loading')}</p>`);
+    ws.scanRequest = btn.dataset.rev;
+    try {
+      const { revision } = await ctx.api.fetchSkillsRevision(btn.dataset.rev);
+      if (!ctx.alive(gen) || signal.aborted || !box.isConnected || ws.scanRequest !== btn.dataset.rev) return;
+      setHTML(box, html`<h4 class="sx-section-title">${t('skillsStudio.scan.title', { id: shortDigest(revision.contentDigest) })}</h4>
+        <p>${scanText(t, revision.scan, revision.contentDigest)}</p>
+        <ul class="sx-plain-list">${(revision.scan?.findings || []).map((f) => html`<li>${t(`skillsStudio.scan.severity.${f.severity}`)} · ${f.ruleId} · ${f.file || ''}${f.line ? `:${f.line}` : ''} — ${scanFindingText(t, f)}</li>`)}</ul>
+        <ul class="sx-plain-list">${(revision.scan?.coverage?.skipped || []).map((f) => html`<li>${f.path} · ${scanReasonText(t, f.reason)}</li>`)}</ul>`);
+      box.scrollIntoView({ block: 'nearest' });
+    } catch (err) { if (ctx.alive(gen) && !signal.aborted && box.isConnected && ws.scanRequest === btn.dataset.rev) setHTML(box, html`<p role="alert">${studioErrorText(ctx.t, err)}</p>`); }
+    return;
+  }
+  if (act === 'diff-prev') { showDiff(panel, ctx, btn.dataset.prev, btn.dataset.rev); return; }
+  if (act === 'diff-pick') {
+    const from = panel.querySelector('#sx-ver-from')?.value; const to = panel.querySelector('#sx-ver-to')?.value;
+    if (from && to && from !== to) showDiff(panel, ctx, from, to); else ctx.toast(t('skillsStudio.versions.pickTwo'), 'error');
+    return;
+  }
+  if (act === 'diff-draft') { showDraftDiff(panel, ctx, ws); return; }
+  // Publish that version: what was planned for another one is dropped there (a plan installs only what it was asked).
+  if (act === 'publish') { choosePublishRevision(ws, btn.dataset.rev, { reviews: ctx.data?.reviews || [] }); ws.tab = 'publish'; ctx.render(); return; }
+  if (act === 'snapshot') {
+    if (dirtyTabs(ws).length) { ctx.toast(t('skillsStudio.toast.saveFirst'), 'error'); return; }
+    const gen = ctx.gen();
+    try { const out = await saveVersion(ws, ctx.api, { key: ctx.key }); if (!ctx.alive(gen)) return; ctx.toast(out.unchanged ? t('skillsStudio.toast.versionUnchanged') : t('skillsStudio.toast.versionSaved')); await ctx.reload(); }
+    catch (err) { if (ctx.alive(gen)) ctx.toast(t('skillsStudio.toast.versionFailed', { error: studioErrorText(ctx.t, err) }), 'error'); }
+    return;
+  }
+  if (act === 'candidate' || act === 'best') {
+    const gen = ctx.gen();
+    try {
+      const skill = (await ctx.api.fetchSkill(ws.skill.skillId)).skill;
+      await ctx.api.moveSkillPointer(ws.skill.skillId, { pointer: act, revisionId: btn.dataset.rev, expectedEtag: skill.etag, reason: 'marked in Skills Studio' });
+      if (!ctx.alive(gen)) return;
+      ctx.toast(t(`skillsStudio.versions.marked.${act}`));
+      ws.skill = (await ctx.api.fetchSkill(ws.skill.skillId)).skill;
+      if (ws.shown && ws.tab === 'versions') renderVersionsTab(panel, ctx, ws);
+    } catch (err) { if (ctx.alive(gen)) ctx.toast(t('skillsStudio.versions.markFailed', { error: studioErrorText(ctx.t, err) }), 'error'); }
+    return;
+  }
+  if (act === 'restore') {
+    // Unsaved text in an open document belongs to the draft being replaced: saved or given up first.
+    const dirty = dirtyTabs(ws);
+    if (dirty.length) {
+      await ctx.ask({ title: t('skillsStudio.versions.restoreBlockedTitle'), lines: [tp('skillsStudio.versions.restoreBlocked', dirty.length)], buttons: [{ id: 'ok', label: t('skillsStudio.dialog.ok'), kind: 'primary' }], cancelId: 'ok' });
+      return;
+    }
+    const changes = ws.draft && ws.revision ? changedFiles(ws.revision.manifest?.files || [], ws.draft.files || []) : [];
+    let first = 'replace';
+    if (changes.length) {
+      first = await ctx.ask({
+        title: t('skillsStudio.versions.restoreTitle'),
+        lines: [tp('skillsStudio.versions.restoreDraftChanged', changes.length), t('skillsStudio.versions.restoreExplain')],
+        buttons: [{ id: 'cancel', label: t('skillsStudio.dialog.cancel') }, { id: 'replace', label: t('skillsStudio.versions.restoreReplace'), kind: 'danger' }, { id: 'save', label: t('skillsStudio.versions.restoreSaveFirst'), kind: 'primary' }],
+        focus: 'cancel',
+      });
+      if (first !== 'replace' && first !== 'save') return;
+    }
+    const gen = ctx.gen();
+    try {
+      if (first === 'save') await saveVersion(ws, ctx.api, { key: ctx.key, note: 'kept before a restore' });
+      await ctx.api.createSkillsDraft({ skillId: ws.skill.skillId, baseRevisionId: btn.dataset.rev }, { idempotencyKey: ctx.key('restore') });
+      if (!ctx.alive(gen)) return;
+      resetDocuments(ws);
+      ws.tab = 'edit';
+      ctx.toast(t('skillsStudio.versions.restored', { id: shortDigest(ws.revisions.find((r) => r.revisionId === btn.dataset.rev)?.contentDigest) }));
+      await ctx.reload();
+      if (ws.shown) ctx.render();
+    } catch (err) { if (ctx.alive(gen)) ctx.toast(t('skillsStudio.versions.restoreFailed', { error: studioErrorText(ctx.t, err) }), 'error'); }
+  }
+  void signal;
+}