synabun 2.0.9 → 2.1.0

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

@@ -0,0 +1,308 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio 2.0: the inspector beside the document
+// ═══════════════════════════════════════════
+//
+// Form | YAML over the same document, never a copy of it (P0's lossless frontmatter: ss-frontmatter.js parses,
+// ss-form.js says what each field shows, a change of a field patches that one key of the text). Keys the form has
+// no field for are listed under Advanced, "kept as written", with the lines they are on. The description helper
+// counts each runtime's budget and says whether the description tells what the skill does and when to use it.
+// Problems come from the same checks as the server (ss-lint.js) and, for a skill, each runtime's profile
+// (ss-profiles.js); a problem jumps to its line. Snippets go in at the caret (body) or as keys (frontmatter).
+// While another file of the skill is showing, the form only shows: it changes SKILL.md, and Save saves the file
+// on screen. Every string is a `skillsStudio.*` key; values from the document reach the markup as text only.
+
+import { dropdownHTML } from '../../cc-dropdown.js';
+import { formView, fieldPatchValue, KNOWN_TOOLS, KNOWN_MODELS } from '../ss-form.js';
+import { lintArtifact } from '../ss-lint.js';
+import { lintForProfile } from '../ss-profiles.js';
+import { revealHidden } from '../ss-unicode.js';
+import { readStoredPresets } from '../ss-presets.js';
+import { html, raw, setHTML, ICONS } from './sx-dom.js';
+import { descriptionHelp, keptKeys, frontmatterText } from './sx-editor-model.js';
+import { snippetsFor, applySnippet, snippetMatches, SNIPPET_GROUPS } from './sx-snippets.js';
+
+const OTHER_PROFILES = ['portable-six-field', 'codex-native', 'opencode-native'];
+let _life = null;
+
+/** The checks of a head document: the Studio's (gutter and list) and, for a skill, each other runtime's. */
+export function headProblems({ type, parsed, folderName, knownNames = [], files = [] }) {
+  const studio = lintArtifact({ type, parsed, folderName, knownNames });
+  const others = type === 'skill' ? OTHER_PROFILES.map((id) => {
+    try {
+      const lint = lintForProfile(id, { parsed, folderName, files });
+      return { id, problems: lint.all.filter((d) => d.severity === 'error' || d.severity === 'warning') };
+    } catch { return { id, problems: [] }; }
+  }).filter((p) => p.problems.length) : [];
+  return { studio, others };
+}
+
+const fieldLabel = (t, type, key) => t(`skillsStudio.form.field.${key}`);
+
+export function fieldHTML(t, f, { locked, type, folderName }) {
+  const id = `sx-f-${f.key}`;
+  const dis = locked || !f.writable;
+  const note = f.note ? html`<p class="sx-field-note">${noteWords(t, f.note)}</p>` : '';
+  const label = html`<label class="sx-field-label" for="${id}" id="${id}-label">${fieldLabel(t, type, f.key)}</label>`;
+  switch (f.control) {
+    case 'textarea': return html`<div class="sx-field">${label}<textarea class="sx-input sx-textarea" id="${id}" data-fm="${f.key}" rows="4"${dis ? ' disabled' : ''}>${f.value}</textarea>${note}</div>`;
+    case 'number': return html`<div class="sx-field">${label}<input class="sx-input" type="number" min="0" step="1" id="${id}" data-fm="${f.key}" value="${f.value}" placeholder="${t('skillsStudio.form.unlimited')}"${dis ? ' disabled' : ''}>${note}</div>`;
+    case 'checkbox':
+      if (f.key === 'disable-model-invocation') {
+        const name = folderName ? `/${folderName}` : '/name';
+        return html`<fieldset class="sx-field sx-choices"${dis ? ' disabled' : ''}><legend class="sx-field-label">${t('skillsStudio.form.invocation')}</legend>
+          <label class="sx-choice"><input type="radio" name="sx-inv" data-fm-radio="disable-model-invocation" value="false"${f.value ? '' : ' checked'}> ${t('skillsStudio.form.invocationAuto', { name })}</label>
+          <label class="sx-choice"><input type="radio" name="sx-inv" data-fm-radio="disable-model-invocation" value="true"${f.value ? ' checked' : ''}> ${t('skillsStudio.form.invocationManual', { name })}</label>${note}</fieldset>`;
+      }
+      return html`<div class="sx-field sx-field--check"><label class="sx-choice"><input type="checkbox" id="${id}" data-fm="${f.key}"${f.value ? ' checked' : ''}${dis ? ' disabled' : ''}> ${fieldLabel(t, type, f.key)}</label>${note}</div>`;
+    case 'model': {
+      const entries = [{ value: '', label: t('skillsStudio.form.modelInherit'), selected: !f.value }, ...KNOWN_MODELS.map((m) => ({ value: m, label: m, selected: f.value === m }))];
+      if (f.value && !KNOWN_MODELS.includes(f.value)) entries.push({ value: f.value, label: f.value, selected: true });
+      return html`<div class="sx-field"><span class="sx-field-label" id="${id}-label">${fieldLabel(t, type, f.key)}</span>${raw(dropdownHTML(id, entries, { labelledBy: `${id}-label`, disabled: dis, inputAttrs: `data-fm="${f.key}"` }))}${note}</div>`;
+    }
+    case 'tools':
+      if (Array.isArray(f.value)) {
+        const entries = [{ value: '', label: t('skillsStudio.form.addTool'), selected: true, disabled: true }, ...KNOWN_TOOLS.filter((x) => !f.value.includes(x)).map((x) => ({ value: x, label: x }))];
+        return html`<div class="sx-field"><span class="sx-field-label" id="${id}-label">${t('skillsStudio.form.field.allowed-tools')} <span class="sx-count">${f.value.length}</span></span>
+          <p class="sx-help">${t('skillsStudio.form.toolsHelp')}</p>
+          <div class="sx-chips" role="list">${f.value.map((tool) => html`<span class="sx-chip" role="listitem">${tool}${dis ? '' : html`<button type="button" class="sx-chip-x" data-tool-remove="${tool}" aria-label="${t('skillsStudio.form.removeTool', { tool })}">${ICONS.close}</button>`}</span>`)}</div>
+          ${dis ? '' : html`<div class="sx-tools-add">${raw(dropdownHTML('sx-f-tool-add', entries, { label: t('skillsStudio.form.addTool') }))}
+            <label class="sx-sr" for="sx-f-tool-pattern">${t('skillsStudio.form.toolPattern')}</label>
+            <input class="sx-input sx-input--sm" id="sx-f-tool-pattern" placeholder="${t('skillsStudio.form.toolPatternPlaceholder')}" autocomplete="off" spellcheck="false">
+            <button type="button" class="sx-btn" data-tool-add-pattern="1">${t('skillsStudio.form.add')}</button></div>`}${note}</div>`;
+      }
+      return html`<div class="sx-field">${label}<input class="sx-input" id="${id}" data-fm="${f.key}" value="${f.value}"${dis ? ' disabled' : ''}>${note}</div>`;
+    default:
+      return html`<div class="sx-field">${label}<input class="sx-input" id="${id}" data-fm="${f.key}" value="${f.value}" autocomplete="off" spellcheck="false"${dis ? ' disabled' : ''}>${f.key === 'name' ? html`<p class="sx-field-note" id="sx-name-check"></p>` : ''}${note}</div>`;
+  }
+}
+
+/** The form's notes come from ss-form.js in English: each is said in the page's language. */
+function noteWords(t, note) {
+  if (/^Not text/.test(note)) return t('skillsStudio.form.note.notText');
+  if (/^Not a list of tool names/.test(note)) return t('skillsStudio.form.note.notTools');
+  if (/^Not true or false/.test(note)) return t('skillsStudio.form.note.notBoolean');
+  if (/^Not a whole number/.test(note)) return t('skillsStudio.form.note.notNumber');
+  if (/^An alias/.test(note)) return t('skillsStudio.form.note.alias');
+  return note;
+}
+
+function reasonWords(t, view) {
+  if (!view.reason) return '';
+  return /errors/.test(view.reason) ? t('skillsStudio.form.reason.errors') : t('skillsStudio.form.reason.unsupported');
+}
+
+export function helperHTML(t, data) {
+  const help = descriptionHelp(data);
+  return html`<div class="sx-helper" aria-live="polite">
+    <ul class="sx-budgets">${help.budgets.map((b) => html`<li class="sx-budget${b.over ? ' is-over' : ''}">
+      <span class="sx-budget-name">${t(`skillsStudio.form.budget.${b.runtime}`)}</span>
+      <span class="sx-meter" aria-hidden="true"><i style="width:${Math.round(b.ratio * 100)}%"></i></span>
+      <span class="sx-budget-count">${t('skillsStudio.form.budgetCount', { used: b.used, limit: b.limit })}</span></li>`)}</ul>
+    <ul class="sx-checks">
+      <li class="${help.what ? 'is-ok' : 'is-warn'}">${help.what ? ICONS.ok : ICONS.warn}<span>${t(help.what ? 'skillsStudio.form.saysWhat' : 'skillsStudio.form.missingWhat')}</span></li>
+      <li class="${help.when ? 'is-ok' : 'is-warn'}">${help.when ? ICONS.ok : ICONS.warn}<span>${t(help.when ? 'skillsStudio.form.saysWhen' : 'skillsStudio.form.missingWhen')}</span></li>
+    </ul>
+    <p class="sx-help">${t(`skillsStudio.form.advice.${help.advice}`)}</p>
+  </div>`;
+}
+
+export function nameCheck(t, value, folderName) {
+  if (!value) return { ok: false, text: t('skillsStudio.form.nameMissing') };
+  if (folderName && value !== folderName) return { ok: false, text: t('skillsStudio.form.nameFolder', { folder: folderName }) };
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)) return { ok: false, text: t('skillsStudio.form.nameFormat') };
+  return { ok: true, text: folderName ? t('skillsStudio.form.nameMatches') : t('skillsStudio.form.nameOk') };
+}
+
+export function problemsHTML(t, problems) {
+  const shown = problems.studio.all.filter((d) => d.severity !== 'info');
+  const item = (d, profile = null) => html`<li><button type="button" class="sx-problem sx-problem--${d.severity}" data-line="${Number(d.line) || ''}">
+    ${d.severity === 'error' ? ICONS.err : ICONS.warn}<span class="sx-problem-text">${d.line ? html`<span class="sx-problem-line">${t('skillsStudio.edit.line', { line: d.line })}</span> ` : ''}${d.message}</span>${profile ? html`<span class="sx-problem-tag">${t(`skillsStudio.form.budget.${profile}`)}</span>` : ''}</button></li>`;
+  const others = problems.others.flatMap((p) => p.problems.slice(0, 6).map((d) => item(d, p.id === 'portable-six-field' ? 'portable' : p.id.replace('-native', ''))));
+  return html`<section class="sx-insp-section" aria-labelledby="sx-problems-h">
+    <h4 class="sx-insp-h" id="sx-problems-h">${t('skillsStudio.edit.problems')} <span class="sx-count">${shown.length}</span></h4>
+    ${shown.length ? html`<ul class="sx-problems">${shown.map((d) => item(d))}</ul>` : html`<p class="sx-help sx-ok-text">${ICONS.ok} ${t('skillsStudio.edit.noProblems')}</p>`}
+    ${others.length ? html`<details class="sx-details"><summary>${t('skillsStudio.edit.otherRuntimes', { count: others.length })}</summary><ul class="sx-problems">${others}</ul></details>` : ''}
+  </section>`;
+}
+
+export function snippetsHTML(t, list, query) {
+  const words = (s) => (s.custom ? `${s.name} ${s.description}` : `${t(`skillsStudio.snippets.${s.id}.name`)} ${t(`skillsStudio.snippets.${s.id}.desc`)}`);
+  const shown = list.filter((s) => snippetMatches(s, query, words));
+  const groups = SNIPPET_GROUPS.map((g) => ({ g, items: shown.filter((s) => s.group === g) })).filter((x) => x.items.length);
+  return html`<section class="sx-insp-section" aria-labelledby="sx-snip-h">
+    <h4 class="sx-insp-h" id="sx-snip-h">${t('skillsStudio.snippets.title')}</h4>
+    <label class="sx-sr" for="sx-snip-search">${t('skillsStudio.snippets.search')}</label>
+    <input type="search" class="sx-input sx-input--sm" id="sx-snip-search" placeholder="${t('skillsStudio.snippets.search')}" value="${query}" autocomplete="off">
+    <div id="sx-snip-list">${groups.map(({ g, items }) => html`<p class="sx-snip-group">${t(`skillsStudio.snippets.group.${g}`)}</p>
+      <ul class="sx-snippets">${items.map((s) => html`<li class="sx-snippet" draggable="true" data-snippet="${s.id}">
+        <span class="sx-snippet-text"><span class="sx-snippet-name">${s.custom ? s.name : t(`skillsStudio.snippets.${s.id}.name`)}</span>
+        <span class="sx-snippet-where">${s.kind === 'frontmatter' ? t('skillsStudio.snippets.whereKeys', { keys: Object.keys(s.patch || {}).join(', ') }) : (s.custom ? (s.description || t('skillsStudio.snippets.whereCaret')) : t(`skillsStudio.snippets.${s.id}.desc`))}</span></span>
+        <button type="button" class="sx-btn sx-btn--sm" data-insert="${s.id}" aria-label="${t('skillsStudio.snippets.insertNamed', { name: s.custom ? s.name : t(`skillsStudio.snippets.${s.id}.name`) })}">${t('skillsStudio.snippets.insert')}</button></li>`)}</ul>`)}
+      ${shown.length ? '' : html`<p class="sx-help">${t('skillsStudio.snippets.none')}</p>`}</div>
+  </section>`;
+}
+
+/**
+ * Draw the inspector for a workspace.
+ * @param {HTMLElement} host
+ * @param {object} o
+ * @param {object} o.ctx @param {object} o.ws
+ * @param {object|null} o.fm ss-frontmatter.js (null while it loads)
+ * @param {object|null} o.head the head document (SKILL.md, or the agent's / command's file)
+ * @param {boolean} o.headShowing the head document is the one on screen
+ * @param {(next: string, o?: object) => void} o.replaceHead change the head document's text (one undo step)
+ * @param {(line: number) => void} o.reveal show a line of the head document
+ * @param {() => void} o.openHead show the head document
+ * @param {() => number|null} o.caret where the caret is in the showing document
+ * @param {(snippet) => void} o.insertSnippet
+ */
+export function renderInspector(host, o) {
+  const { ctx, ws, fm, head } = o;
+  const { t } = ctx;
+  _life?.abort();
+  _life = new AbortController();
+  const signal = _life.signal;
+  const mode = ws.inspectorMode || 'form';
+  const type = ws.kind;
+  const folderName = ws.kind === 'skill' ? (ws.row.folderName || ws.label) : '';
+  let body;
+  if (!head) body = html`<p class="sx-help">${t('skillsStudio.edit.noHead')}</p>`;
+  else if (head.binary) body = html`<p class="sx-note sx-note--warn" role="note">${t('skillsStudio.form.binaryHead')}</p>`;
+  else if (!fm) body = html`<p class="sx-help" role="status">${t('skillsStudio.form.loading')}</p>`;
+  else {
+    let parsed = null;
+    try { parsed = fm.parse(head.content); } catch { parsed = null; }
+    if (!parsed) body = html`<p class="sx-note" role="note">${t('skillsStudio.form.cannotRead')}</p>`;
+    else {
+      const view = formView(type, parsed);
+      const locked = !ws.subject.editable || head.readOnly || !view.editable || !o.headShowing;
+      const kept = keptKeys(type, parsed, head.content);
+      const problems = headProblems({ type, parsed, folderName, knownNames: o.knownNames || [], files: (ws.files || []).filter((f) => f.path).map((f) => ({ path: f.path, size: f.size || 0 })) });
+      ws.lastProblems = problems;
+      const notShowing = !o.headShowing && ws.subject.editable;
+      const formPart = mode === 'yaml'
+        ? html`<div class="sx-yaml"><pre class="sx-pre" tabindex="0" aria-label="${t('skillsStudio.form.yamlLabel')}">${frontmatterText(head.content) || t('skillsStudio.form.noFrontmatter')}</pre>
+            <button type="button" class="sx-btn" data-insp="yaml-edit">${t('skillsStudio.form.editInDocument')}</button>
+            <p class="sx-help">${t('skillsStudio.form.yamlHelp')}</p></div>`
+        : html`${view.reason && ws.subject.editable ? html`<p class="sx-note" role="note">${reasonWords(t, view)}</p>` : ''}
+            ${notShowing ? html`<p class="sx-note" role="note">${t('skillsStudio.form.notShowing', { file: head.label })} <button type="button" class="sx-link" data-insp="open-head">${t('skillsStudio.form.openIt')}</button></p>` : ''}
+            <div class="sx-form" role="group" aria-label="${t('skillsStudio.form.label')}">${view.fields.map((f) => fieldHTML(t, f, { locked, type, folderName }))}</div>
+            ${type === 'skill' ? helperHTML(t, parsed.data || {}) : ''}`;
+      const keptPart = kept.length ? html`<details class="sx-details sx-advanced"${ws.advancedOpen ? ' open' : ''} data-insp-details="advanced">
+          <summary>${ctx.tp('skillsStudio.form.advanced', kept.length)}</summary>
+          <p class="sx-help">${t('skillsStudio.form.advancedHelp')}</p>
+          <ul class="sx-kept">${kept.map((k) => html`<li><button type="button" class="sx-link" data-line="${k.line}">${k.key}</button><pre class="sx-pre sx-pre--sm">${k.text}</pre></li>`)}</ul>
+        </details>` : html`<p class="sx-help">${t('skillsStudio.form.advancedNone')}</p>`;
+      const custom = readStoredPresets(ctx.storage.getItem('neural-skills-custom-presets')).presets;
+      body = html`
+        <div class="sx-seg" role="group" aria-label="${t('skillsStudio.form.viewLabel')}">
+          <button type="button" data-insp="mode-form" aria-pressed="${mode === 'form' ? 'true' : 'false'}">${t('skillsStudio.form.form')}</button>
+          <button type="button" data-insp="mode-yaml" aria-pressed="${mode === 'yaml' ? 'true' : 'false'}">${t('skillsStudio.form.yaml')}</button>
+        </div>
+        ${formPart}
+        ${keptPart}
+        ${problemsHTML(t, problems)}
+        ${ws.subject.editable ? snippetsHTML(t, snippetsFor(type, custom), ws.snippetQuery || '') : ''}`;
+    }
+  }
+  setHTML(host, html`<div class="sx-inspector">${body}</div>`);
+  if (!head || !fm || head.binary) return;
+  // (its dropdowns are served by the Edit panel's delegated listeners, which hold this pane: wiring them here too
+  // would open and close them with the same click)
+  const nameInput = host.querySelector('#sx-f-name');
+  const showName = () => {
+    const out = host.querySelector('#sx-name-check');
+    if (!out || !nameInput) return;
+    const check = nameCheck(t, nameInput.value.trim(), folderName && ws.kind === 'skill' ? folderName : '');
+    out.textContent = `${check.ok ? '✓' : '✕'} ${check.text}`;
+    out.className = `sx-field-note ${check.ok ? 'sx-ok-text' : 'sx-warn-text'}`;
+  };
+  showName();
+  const apply = (key, input) => {
+    const parsed = fm.parse(head.content);
+    const view = formView(type, parsed);
+    const field = view.fields.find((f) => f.key === key);
+    if (!view.editable || !field?.writable || head.readOnly || !o.headShowing) return;
+    const savedKeys = new Set((fm.parse(head.saved.raw).keys || []).map((k) => k.key));
+    const next = fieldPatchValue({ field, input, current: parsed.data?.[key], savedHasKey: savedKeys.has(key) });
+    const el = host.querySelector(`#sx-f-${CSS.escape(key)}`);
+    if (next.invalid) { if (el) { el.setAttribute('aria-invalid', 'true'); el.title = t('skillsStudio.form.invalidNumber'); } return; }
+    if (el) { el.removeAttribute('aria-invalid'); el.removeAttribute('title'); }
+    const result = fm.patch(head.content, { [key]: next.value });
+    if (!result.ok) { ctx.toast(t('skillsStudio.form.patchFailed', { field: fieldLabel(t, type, key) }), 'error'); return; }
+    if (result.changed) o.replaceHead(result.text);
+  };
+  host.addEventListener('input', (e) => {
+    const el = e.target;
+    if (el.dataset?.fm && el.type !== 'checkbox' && el.type !== 'hidden') { apply(el.dataset.fm, el.value); if (el.dataset.fm === 'name') showName(); }
+    if (el.id === 'sx-snip-search') { ws.snippetQuery = el.value; redrawSnippets(host, ctx, ws, type); }
+  }, { signal });
+  host.addEventListener('change', (e) => {
+    const el = e.target;
+    if (el.type === 'checkbox' && el.dataset?.fm) apply(el.dataset.fm, el.checked);
+    else if (el.type === 'hidden' && el.dataset?.fm) apply(el.dataset.fm, el.value);
+    else if (el.dataset?.fmRadio) apply(el.dataset.fmRadio, el.value === 'true');
+    else if (el.id === 'sx-f-tool-add' && el.value) {
+      const parsed = fm.parse(head.content);
+      const tools = Array.isArray(parsed.data?.['allowed-tools']) ? parsed.data['allowed-tools'] : [];
+      apply('allowed-tools', [...tools, el.value]);
+    }
+  }, { signal });
+  host.addEventListener('toggle', (e) => { if (e.target.dataset?.inspDetails === 'advanced') ws.advancedOpen = e.target.open; }, { signal, capture: true });
+  host.addEventListener('click', (e) => {
+    const btn = e.target.closest?.('button');
+    if (!btn || !host.contains(btn)) return;
+    if (btn.dataset.insp === 'mode-form' || btn.dataset.insp === 'mode-yaml') { ws.inspectorMode = btn.dataset.insp === 'mode-yaml' ? 'yaml' : 'form'; renderInspector(host, o); host.querySelector(`[data-insp="${btn.dataset.insp}"]`)?.focus(); return; }
+    if (btn.dataset.insp === 'open-head') { o.openHead(); return; }
+    if (btn.dataset.insp === 'yaml-edit') { o.openHead(); o.reveal(2); return; }
+    if (btn.dataset.line) { const line = Number(btn.dataset.line); if (line) { o.openHead(); o.reveal(line); } return; }
+    if (btn.dataset.toolRemove) {
+      const parsed = fm.parse(head.content);
+      const tools = Array.isArray(parsed.data?.['allowed-tools']) ? parsed.data['allowed-tools'] : [];
+      apply('allowed-tools', tools.filter((x) => x !== btn.dataset.toolRemove));
+      return;
+    }
+    if (btn.dataset.toolAddPattern) {
+      const input = host.querySelector('#sx-f-tool-pattern');
+      const value = input?.value.trim();
+      if (!value) return;
+      const parsed = fm.parse(head.content);
+      const tools = Array.isArray(parsed.data?.['allowed-tools']) ? parsed.data['allowed-tools'] : [];
+      if (!tools.includes(value)) apply('allowed-tools', [...tools, value]);
+      return;
+    }
+    if (btn.dataset.insert) {
+      const custom = readStoredPresets(ctx.storage.getItem('neural-skills-custom-presets')).presets;
+      const snippet = snippetsFor(type, custom).find((s) => s.id === btn.dataset.insert);
+      if (snippet) o.insertSnippet(snippet);
+    }
+  }, { signal });
+  host.addEventListener('dragstart', (e) => {
+    const item = e.target.closest?.('[data-snippet]');
+    if (!item) return;
+    const custom = readStoredPresets(ctx.storage.getItem('neural-skills-custom-presets')).presets;
+    const snippet = snippetsFor(type, custom).find((s) => s.id === item.dataset.snippet);
+    if (!snippet || snippet.kind !== 'body') { e.preventDefault(); return; }
+    e.dataTransfer.setData('text/plain', snippet.text);
+    e.dataTransfer.effectAllowed = 'copy';
+  }, { signal });
+}
+
+function redrawSnippets(host, ctx, ws, type) {
+  const custom = readStoredPresets(ctx.storage.getItem('neural-skills-custom-presets')).presets;
+  const list = snippetsFor(type, custom);
+  const box = host.querySelector('#sx-snip-list');
+  if (!box) return;
+  const tmp = document.createElement('div');
+  setHTML(tmp, snippetsHTML(ctx.t, list, ws.snippetQuery || ''));
+  const fresh = tmp.querySelector('#sx-snip-list');
+  if (fresh) box.replaceWith(fresh);
+}
+
+/** Insert a snippet into a text (the view hands the result to the editor). */
+export function snippetResult(text, snippet, { caret, fm }) {
+  return applySnippet(text, snippet, { caret, fm });
+}
+
+/** A hidden-character-safe label of a document (a name may hold characters nobody can see). */
+export const shownName = (name) => revealHidden(String(name ?? ''));

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

@@ -0,0 +1,279 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio 2.0: install in one go
+// ═══════════════════════════════════════════
+//
+// The one flow behind every Install of the Studio (the Publish tab's button, Review's "Approve & install", the
+// workspace banner): the service plans the install (POST /v2/installations/plan), the owner is asked one question
+// only when the plan asks one (a folder SynaBun did not install or that changed since, the scan's findings: what
+// lib/skills/deploy.js needs confirmed), and the install sends exactly that plan (its digest, the decisions per
+// target). A plan that changed under it is planned again, once, and asked again. The outcome comes back as data
+// (sx-install.js installOutcome) with its words. Every protection of the service is kept: nothing is written
+// without a plan, nothing replaced without its digest, nothing blocked is sent.
+
+import { scanFindingText } from './sx-scan.js';
+import { studioErrorText } from './sx-errors.js';
+import { html, setHTML } from './sx-dom.js';
+import { BLOCK_CODES, planModel, resultModel } from './sx-plan.js';
+import { installTargets, wholeTarget } from './sx-subject.js';
+import { confirmations, installOutcome, parseTargetKey, reviewDestinations, assistantsOf, installedRuntimesOf, alsoInstallTargets, alsoInstallRevision } from './sx-install.js';
+
+// ── One install at a time per skill ──
+// Every surface that installs (the Publish tab's button, Review's card, the workspace banner) takes this lock for
+// the skill before it approves or plans, and lets it go when the flow ends, however it ends. While it is held every
+// surface shows the install as on its way and refuses a second one (a click, or Enter on a button it disables).
+const _busy = new Map();        // skillId → since
+const _watchers = new Set();    // told when a lock is taken or let go
+
+/** Whether an install of this skill is on its way, from any surface. */
+export const installBusy = (skillId) => !!skillId && _busy.has(skillId);
+
+/**
+ * Take the lock for a skill: what lets it go, or null when it is held already (the caller refuses).
+ * @param {string} skillId
+ * @returns {(() => void)|null}
+ */
+export function acquireInstall(skillId) {
+  if (!skillId || _busy.has(skillId)) return null;
+  _busy.set(skillId, Date.now());
+  tell(skillId, true);
+  let done = false;
+  return () => { if (done) return; done = true; _busy.delete(skillId); tell(skillId, false); };
+}
+
+/** Be told when a lock is taken or let go (the surfaces draw the install as on its way, or not). */
+export function onInstallBusy(fn) { _watchers.add(fn); return () => _watchers.delete(fn); }
+function tell(skillId, busy) { for (const fn of _watchers) { try { fn({ skillId, busy }); } catch { /* a watcher's own trouble */ } } }
+
+/** The words of a target: "Claude Code · all projects", "Codex · project Repo", "Claude Code · account work". */
+export function targetWords(ctx, tg) {
+  const { t } = ctx;
+  const runtime = t(`skillsStudio.runtime.${['claude', 'codex', 'opencode', 'agents'].includes(tg?.runtime) ? tg.runtime : 'claude'}`);
+  if (tg?.scope === 'project') return t('skillsStudio.publish.targetProject', { runtime, project: tg.projectLabel || ctx.projects?.find((p) => p.path === tg.projectPath)?.label || tg.projectPath || '' });
+  if (tg?.accountId && tg.accountId !== 'default') return t('skillsStudio.publish.targetAccount', { runtime, account: tg.accountId });
+  return t('skillsStudio.publish.targetUser', { runtime });
+}
+
+/** The words of a target key (an install's result names targets by key). */
+export const keyWords = (ctx, key) => targetWords(ctx, parseTargetKey(key));
+
+/** A folder path, short: the home folder as ~ (the full path stays in the element's title). */
+export function shortPath(path) {
+  return String(path || '').replace(/^\/Users\/[^/]+(?=\/)/, '~').replace(/^\/home\/[^/]+(?=\/)/, '~').replace(/^[A-Za-z]:\\Users\\[^\\]+(?=\\)/, '~');
+}
+
+/** The owner's assistants in effect (read with the Library: GET /v2/status `assistants`), or null on an older server. */
+export function assistantsNow(ctx) { return assistantsOf(ctx.data?.status || null); }
+
+/** The runtimes the resolver found on this computer (GET /v2/status `assistants.installed`), or null when not known. */
+export function installedNow(ctx) { return installedRuntimesOf(ctx.data?.status || null); }
+
+/**
+ * "Also install for Codex · OpenCode": the assistants in effect that a skill installed somewhere does not reach yet
+ * (sx-install.js alsoInstallTargets), with their words. Empty when there is nothing to add.
+ */
+export function alsoInstall(ctx, { skill, row }) {
+  const targets = alsoInstallTargets({ skill, row, targets: targetsNow(ctx), assistants: assistantsNow(ctx), installed: installedNow(ctx) });
+  return { targets: targets.map(wholeTarget), words: targets.map((t) => ctx.t(`skillsStudio.runtime.${t.runtime}`)).join(' · ') };
+}
+
+/**
+ * One press: the version that is installed already (sx-install.js alsoInstallRevision) goes to the assistants that lack it, through the one flow (the plan, one question only when it asks one,
+ * then exactly that plan). The outcome's words come back for a toast or a banner; null when nothing was to add.
+ */
+export async function alsoInstallNow(ctx, { skill, row }) {
+  const { t } = ctx;
+  const { targets } = alsoInstall(ctx, { skill, row });
+  if (!targets.length || ctx.guest) return null;
+  const revisionId = alsoInstallRevision(skill);
+  if (!revisionId) return { kind: 'error', line: t('skillsStudio.publish.noVersion'), lines: [] };
+  const release = acquireInstall(skill.skillId);
+  if (!release) return { kind: 'error', line: t('skillsStudio.publish.busyElsewhere'), lines: [] };
+  let out;
+  try { out = await installFlow(ctx, { revisionId, targets }); } catch (err) { out = { status: 'failed', error: studioErrorText(ctx.t, err) }; } finally { release(); }
+  return flowWords(ctx, out);
+}
+
+/** The targets a skill can be installed into now, with the shared folder as Settings has it (read with the Library). */
+export function targetsNow(ctx, { projects = [] } = {}) {
+  const config = ctx.data?.config || { sharedAgentsRoot: false };
+  return installTargets({ roots: ctx.data?.catalog?.roots || [], config, projects: ctx.projects.filter((p) => projects.includes(p.path)) });
+}
+
+/**
+ * Where a review's install goes (sx-install.js reviewDestinations), from the same targets every surface uses: the
+ * label a button shows and the targets its click sends are one computation. `targets` as requests name them;
+ * `words` each destination in words; `missing` what the submission named that is not available here, with why.
+ */
+export function reviewTargets(ctx, { review, skill, row }) {
+  const projects = [...new Set((review?.targets || []).filter((x) => x?.scope === 'project' && x.projectPath && ctx.projects.some((p) => p.path === x.projectPath)).map((x) => x.projectPath))];
+  const all = targetsNow(ctx, { projects });
+  const d = reviewDestinations({ review, targets: all, skill, row, assistants: assistantsNow(ctx) });
+  return {
+    targets: d.targets.map(wholeTarget), all, keys: d.keys, named: d.named, fallback: d.fallback,
+    words: all.filter((t) => d.keys.has(t.key)).map((t) => targetWords(ctx, t)),
+    missing: d.missing.map((m) => ({ ...m, words: targetWords(ctx, m.target), why: ctx.t(`skillsStudio.publish.unavailable.${m.reason}`) })),
+  };
+}
+
+/**
+ * The workspaces of a skill read it again (its installations, pointers) after an install from another surface, so
+ * their header pill, banners and Publish say what the Library row says. `resetPublish` starts their Publish over.
+ */
+export async function refreshSkillWorkspaces(ctx, skillId, { resetPublish = false } = {}) {
+  if (!skillId) return;
+  let fresh = null;
+  try { fresh = (await ctx.api.fetchSkill(skillId)).skill; } catch { return; }
+  for (const ws of ctx.workspaces.values()) {
+    if (ws.skill?.skillId !== skillId) continue;
+    ws.skill = fresh;
+    if (resetPublish) { ws.pub = null; ws.publishReviewId = null; ws.publishRevisionId = null; }
+  }
+}
+
+/**
+ * The refresh hints of an outcome, worded (one per runtime that needs something). A runtime the resolver did not
+ * find on this computer is said as such: the copy waits in its folder, and nothing lists it until it is installed.
+ */
+export function refreshWords(ctx, outcome) {
+  const installed = installedNow(ctx);
+  return (outcome?.refresh || []).map((x) => {
+    const kind = Array.isArray(installed) && ['claude', 'codex', 'opencode'].includes(x.runtime) && !installed.includes(x.runtime) ? 'not-installed' : x.kind;
+    return ctx.t(`skillsStudio.publish.refresh.${kind}`, { runtime: ctx.t(`skillsStudio.runtime.${x.runtime}`) });
+  });
+}
+
+/** Why a runtime's settings turn the skill off, in words (sx-plan.js eligibility reason). */
+export function eligibilityWords(ctx, runtime, reason) {
+  const { t } = ctx;
+  const name = t(`skillsStudio.runtime.${['claude', 'codex', 'opencode', 'agents'].includes(runtime) ? runtime : 'claude'}`);
+  const file = shortPath(reason?.file || '');
+  const kind = ['codex-config', 'claude-override', 'claude-deny', 'opencode-permission', 'unreadable', 'invalid-json'].includes(reason?.kind) ? reason.kind : 'other';
+  return t(`skillsStudio.publish.eligibility.reason.${kind}`, { runtime: name, file, pattern: reason?.pattern || '*', rule: reason?.rule || reason?.key || '' });
+}
+
+/**
+ * The owner pressed "Enable for <runtime>" on a plan line: the runtime setting that turns the skill off is changed by
+ * the server over a backup (POST /v2/eligibility/enable); the words of what happened come back for a toast. A plan
+ * is made again by the caller: this changes no file of the skill.
+ * @returns {Promise<{ ok: boolean, line: string }>}
+ */
+export async function enableFor(ctx, { runtime, line }) {
+  const { t } = ctx;
+  const name = t(`skillsStudio.runtime.${runtime}`);
+  const target = parseTargetKey(line.targetKey);
+  const sep = line.destination && line.destination.includes('\\') && !line.destination.includes('/') ? '\\' : '/';
+  const body = { runtime, name: line.destination ? line.destination.split(/[\\/]/).pop() : '', skillMd: `${line.destination}${sep}SKILL.md`, accountId: target.accountId, projectPath: target.projectPath };
+  const said = (out) => (out.changed === false ? { ok: true, line: t('skillsStudio.publish.enableNothing', { runtime: name }) } : { ok: out.ok !== false, line: t('skillsStudio.publish.enabled', { runtime: name, file: shortPath(out.file || ''), backup: shortPath(out.backup || '') }) });
+  try {
+    return said(await ctx.api.enableSkillsEligibility(body));
+  } catch (err) {
+    // OpenCode's rules deny every skill: loosened only after the owner's word (the server refuses first).
+    if (err?.code === 'deny_all' && runtime === 'opencode' && typeof ctx.ask === 'function') {
+      const answer = await ctx.ask({
+        title: t('skillsStudio.publish.enableDenyAllTitle', { runtime: name }),
+        lines: [t('skillsStudio.publish.enableDenyAllBody', { file: shortPath(err.body?.file || err.file || '') })],
+        buttons: [{ id: 'cancel', label: t('skillsStudio.dialog.cancel') }, { id: 'go', label: t('skillsStudio.publish.enableDenyAllGo'), kind: 'danger' }],
+        focus: 'cancel',
+      });
+      if (answer !== 'go') return { ok: false, line: t('skillsStudio.publish.enableFailed', { runtime: name, error: studioErrorText(ctx.t, err) }) };
+      try { return said(await ctx.api.enableSkillsEligibility({ ...body, confirmDenyAll: true })); } catch (e2) { return { ok: false, line: t('skillsStudio.publish.enableFailed', { runtime: name, error: studioErrorText(ctx.t, e2) }) }; }
+    }
+    return { ok: false, line: t('skillsStudio.publish.enableFailed', { runtime: name, error: studioErrorText(ctx.t, err) }) };
+  }
+}
+
+/** An outcome in words: the line, the hints for open sessions, what failed. */
+export function outcomeWords(ctx, outcome) {
+  const { t } = ctx;
+  const where = outcome.ok.map((k) => keyWords(ctx, k)).join(', ');
+  const failed = outcome.failed.map((f) => keyWords(ctx, f.targetKey)).join(', ');
+  const reason = (f) => f?.code && BLOCK_CODES.includes(f.code) ? t(`skillsStudio.publish.blocked.${f.code}`) : f?.code || f?.reason ? studioErrorText(t, f) : f ? t(`skillsStudio.publish.result.${f.status}`) : failed;
+  const line = outcome.ok.length && !outcome.failed.length ? t('skillsStudio.publish.doneFor', { where })
+    : outcome.ok.length ? t('skillsStudio.publish.doneSome', { where, failed })
+      : t('skillsStudio.publish.doneNone', { reason: reason(outcome.failed[0]) });
+  return { line, refresh: refreshWords(ctx, outcome), failed: outcome.failed.map((f) => `${keyWords(ctx, f.targetKey)}: ${reason(f)}`) };
+}
+
+/** What blocks a plan's targets, in words (one line per target). */
+export function blockedWords(ctx, rows) {
+  const { t } = ctx;
+  return (rows || []).map((r) => t('skillsStudio.publish.blockedFor', { target: keyWords(ctx, r.targetKey), reason: r.blocked.map((b) => t(`skillsStudio.publish.blocked.${b.code}`)).join(' ') }));
+}
+
+/**
+ * Ask what the plan asks, in one question, or nothing when it asks nothing.
+ * @returns {Promise<object|null>} the decisions to send (empty when nothing was asked), null when the owner said no
+ */
+export async function askConfirmations(ctx, model) {
+  const { t } = ctx;
+  const c = confirmations(model);
+  if (!c.replace.length && !c.scan.length) return c.decisions;
+  const box = document.createElement('div');
+  box.className = 'sx-confirm-list';
+  setHTML(box, html`${c.replace.map((r) => html`<p class="sx-confirm-item"><strong>${keyWords(ctx, r.targetKey)}</strong>: <span class="sx-mono">${shortPath(r.destination)}</span> ${t(`skillsStudio.publish.confirmWhy.${r.replace.state === 'modified' ? 'modified' : 'unowned'}`)} ${t('skillsStudio.publish.confirmReplaced')}</p>`)}
+    ${c.scan.map((r) => html`<div class="sx-confirm-item"><p><strong>${keyWords(ctx, r.targetKey)}</strong>: ${t('skillsStudio.publish.confirmScanLine')}</p>
+      <ul class="sx-findings">${r.scanAck.findings.map((f) => html`<li class="sx-finding sx-finding--${f.severity}"><span class="sx-finding-sev">${t(`skillsStudio.review.severity.${['critical', 'high', 'medium', 'low'].includes(f.severity) ? f.severity : 'low'}`)}</span> ${scanFindingText(t, f)}${f.file ? html` <span class="sx-mono sx-dim">${f.file}${f.line ? `:${f.line}` : ''}</span>` : ''}</li>`)}</ul></div>`)}`);
+  const answer = await ctx.ask({
+    title: t('skillsStudio.publish.confirmTitle'),
+    lines: [t(c.replace.length ? 'skillsStudio.publish.confirmBodyReplace' : 'skillsStudio.publish.confirmBodyScan')],
+    extra: box,
+    buttons: [{ id: 'cancel', label: t('skillsStudio.dialog.cancel') }, { id: 'go', label: t(c.replace.length ? 'skillsStudio.publish.confirmGo' : 'skillsStudio.publish.confirmGoScan'), kind: c.replace.length ? 'danger' : 'primary' }],
+    focus: 'cancel',
+    wide: c.scan.length > 0,
+  });
+  return answer === 'go' ? c.decisions : null;
+}
+
+/**
+ * Plan, ask only what must be asked, install exactly that plan.
+ * @param {object} ctx the Studio's context
+ * @param {{ revisionId: string, targets: object[], reviewId?: string|null, plan?: object|null, onPlanned?: (model: object) => void }} o
+ *   plan: a plan already made for exactly this ask (sx-plan.js planModel): used instead of asking for one
+ * @returns {Promise<{ status: 'done'|'blocked'|'cancelled'|'plan-failed'|'failed'|'gone', plan?: object, results?: object[], outcome?: object, blocked?: object[], error?: string }>}
+ */
+export async function installFlow(ctx, { revisionId, targets, reviewId = null, plan = null, onPlanned = null }) {
+  const gen = ctx.gen();
+  let model = plan;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    if (!model) {
+      try { model = planModel((await ctx.api.planSkillsInstall(revisionId, targets)).plan); } catch (err) { return { status: 'plan-failed', error: studioErrorText(ctx.t, err) }; }
+      if (!ctx.alive(gen)) return { status: 'gone' };
+      onPlanned?.(model);
+    }
+    const c = confirmations(model);
+    if (!c.ready.length) return { status: 'blocked', plan: model, blocked: c.blocked };
+    const decisions = await askConfirmations(ctx, model);
+    if (!ctx.alive(gen)) return { status: 'gone' };
+    if (decisions === null) return { status: 'cancelled', plan: model };
+    let result = null;
+    try {
+      result = await ctx.api.installSkillsRevision({ revisionId, targets, planDigest: model.planDigest, decisions, ...(reviewId ? { reviewId } : {}) });
+    } catch (err) {
+      if (!ctx.alive(gen)) return { status: 'gone' };
+      if (err?.status === 207 && err.body) result = err.body;
+      else if (err?.code === 'plan_changed' && err.body?.plan) { model = planModel(err.body.plan); onPlanned?.(model); continue; }   // what is there changed meanwhile: planned again, asked again
+      else return { status: 'failed', error: studioErrorText(ctx.t, err), plan: model };
+    }
+    if (!ctx.alive(gen)) return { status: 'gone' };
+    const results = resultModel(result);
+    return { status: 'done', plan: model, results, outcome: installOutcome(results), blocked: c.blocked };
+  }
+  return { status: 'failed', error: ctx.t('skillsStudio.publish.planChanged'), plan: model };
+}
+
+/**
+ * The words a finished flow gets, for a toast and a notice: null when nothing is to be said (gone, cancelled).
+ * @returns {{ kind: 'info'|'error', line: string, lines: string[] }|null}
+ */
+export function flowWords(ctx, out) {
+  const { t } = ctx;
+  if (!out || out.status === 'gone' || out.status === 'cancelled') return null;
+  if (out.status === 'done') {
+    const w = outcomeWords(ctx, out.outcome);
+    const extra = [...w.refresh, ...w.failed, ...blockedWords(ctx, out.blocked)];
+    return { kind: out.outcome.all ? 'info' : 'error', line: w.line, lines: extra };
+  }
+  if (out.status === 'blocked') return { kind: 'error', line: t('skillsStudio.publish.notInstalledBlocked'), lines: blockedWords(ctx, out.blocked) };
+  if (out.status === 'plan-failed') return { kind: 'error', line: t('skillsStudio.publish.planFailed', { error: out.error }), lines: [] };
+  return { kind: 'error', line: t('skillsStudio.publish.installFailed', { error: out.error || '' }), lines: [] };
+}