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

package/navigation-page.js

@@ -0,0 +1,264 @@
+/**
+ * Commands → Rail: the actions rail, arranged.
+ *
+ * One page per scope — the global rail, then each workspace — showing the groups that scope has actually
+ * drawn, with their entries. Drag an entry to another group, or into Hidden; drag a group to move the
+ * whole group; add a link or a button of your own. It is the same shape as Commands → Buttons, because it
+ * is the same question asked about a different strip of the screen.
+ *
+ * What it can list is what the rail has SEEN (rail-layout.js): the rail differs per page — a files
+ * workspace has Sync, a project workspace has Screens and Run — so the entries offered for a scope are
+ * the ones its pages have rendered. Open a workspace once and its rail is arrangeable.
+ */
+
+const { esc } = require('./html');
+const { loadWorkspaces } = require('./workspaces');
+const rail = require('./navigation');
+const cc = require('./commands');
+
+const icon = (name, ratio = 0.7) => `<span uk-icon="icon: ${name}; ratio: ${ratio}"></span>`;
+
+/** The scope picker: global first, then every workspace, each saying whether it has anything of its own. */
+function scopeTabsHtml(scope) {
+  const raw = rail.loadLayout().raw || {};
+  const has = (s) => {
+    const l = rail.scopeLayout(raw, s);
+    return l.hidden.length || l.groups.length || l.items.length || Object.keys(l.order).length;
+  };
+  const tab = (s, label) => `<a class="uk-button uk-button-${scope === s ? 'primary' : 'default'} uk-button-small settings-tab"
+       href="/settings/navigation?scope=${encodeURIComponent(s)}"${scope === s ? ' aria-current="page"' : ''}
+       title="${esc(s === 'global' ? 'The rail on every page' : `The rail on the ${label} pages, applied after the global one`)}">${esc(label)}${has(s) ? ' •' : ''}</a>`;
+  const workspaces = Object.values(loadWorkspaces());
+  return `<p class="settings-tabs nav-scopes">
+    ${tab('global', 'Every page')}
+    ${workspaces.map((w) => tab(w.key, w.label)).join('')}
+  </p>`;
+}
+
+/** One entry, as a card that can be dragged between groups. */
+function entryCard(id, label, group, custom, shownAs) {
+  return `<li class="nav-entry" data-id="${esc(id)}">
+    <input type="hidden" name="item" value="${esc(`${group}:${id}`)}">
+    <span class="nav-handle" title="Drag to move it, or into Hidden">${icon('table')}</span>
+    <span class="nav-entry-label">${esc(label)}</span>
+    <!-- How much of the entry is shown, in whichever place it sits: that is about how much room the
+         entry is worth, not about which strip of the screen it is on. Both halves stay in the markup
+         whichever is picked, so a screen reader still reads the name — this is presentation only. -->
+    <select class="nav-entry-show" name="show" title="How much of ${esc(label)} is shown"
+            aria-label="How much of ${esc(label)} is shown">
+      <option value="${esc(id)}:both"${shownAs === 'both' ? ' selected' : ''}>icon + text</option>
+      <option value="${esc(id)}:icon"${shownAs === 'icon' ? ' selected' : ''}>icon only</option>
+      <option value="${esc(id)}:text"${shownAs === 'text' ? ' selected' : ''}>text only</option>
+    </select>
+    ${custom ? `<span class="uk-label nav-yours" title="An entry you added">yours</span>
+      <button type="button" class="uk-button uk-button-link nav-remove arm-step" title="Remove ${esc(label)}"
+              hx-post="/actions/nav-remove" hx-vals='${esc(JSON.stringify({ id, scope: custom.scope }))}'
+              hx-include="#nav-form" hx-target="#nav-editor" hx-swap="outerHTML"
+              hx-on::before:request="window.navSyncGroups && window.navSyncGroups()"
+              hx-trigger="confirmed-remove">${icon('trash')}</button>` : ''}
+  </li>`;
+}
+
+/**
+ * The editor for one scope. Everything is in one form: dragging is not saved until Save, and the two
+ * add forms post the arrangement with them, so a drag is never lost by adding something.
+ */
+function navEditorHtml(scope, message) {
+  const { raw, mtime } = rail.loadLayout();
+  const own = rail.scopeLayout(raw, scope);
+  const seen = rail.seenFor(scope);
+  const hidden = new Set(own.hidden);
+  const customById = new Map(own.items.map((it) => [it.id, it]));
+
+  // The groups this scope has drawn, in the order it has them, then anything the layout names that the
+  // rail has not drawn lately — kept, so a hidden entry survives a page that has not been opened yet.
+  // What each region holds: what the layout put there, then what the navigation has actually DRAWN
+  // there. Without the second half a placement the dashboard ships — the assistant, the version, the
+  // screens count — is invisible here, so saving wrote it into a sidebar group and the default it was
+  // sitting on stopped applying. The editor has to be able to see what it is arranging.
+  const regionIds = Object.fromEntries(rail.REGIONS.map((r) => {
+    const drawn = Object.keys(((seen[`topbar-${r}`]) || {}).items || {});
+    return [r, [...new Set([...own.topbar[r], ...drawn])].filter((id) => !hidden.has(id))];
+  }));
+  const inTopbar = new Set(rail.REGIONS.flatMap((r) => regionIds[r]));
+  // The sidebar's own groups. The topbar regions are recorded in the same registry so their entries keep
+  // their labels, but they are drawn as their own lists below, not as sidebar groups.
+  const groupIds = [...new Set([...own.groups, ...Object.keys(seen)])]
+    .filter((g) => !rail.TOPBAR_GROUPS.includes(g))
+    .filter((g) => seen[g] || own.order[g]);
+  const groups = groupIds.map((g) => {
+    const label = (seen[g] && seen[g].label) || g;
+    const ids = [...new Set([...(own.order[g] || []), ...Object.keys((seen[g] || {}).items || {})])]
+      .filter((id) => !hidden.has(id) && !inTopbar.has(id));
+    return { id: g, label, ids };
+  });
+  // An entry you added shows in the group it joins, the same rule the rail applies — without this it
+  // renders on the rail but not here, so it could be neither moved nor removed.
+  const byId = new Map(groups.map((g) => [g.id, g]));
+  for (const item of own.items) {
+    if (hidden.has(item.id) || inTopbar.has(item.id)) continue;
+    const asked = rail.regionOf(item.group);
+    if (asked) { regionIds[asked].push(item.id); inTopbar.add(item.id); continue; }
+    const wanted = rail.isId(item.group) ? item.group : 'yours';
+    const g = byId.get(wanted);
+    if (g) { if (!g.ids.includes(item.id)) g.ids.push(item.id); continue; }
+    const made = { id: wanted, label: wanted === 'yours' ? 'Yours' : item.group, ids: [item.id] };
+    groups.push(made);
+    byId.set(wanted, made);
+  }
+
+  const seenItem = (id) => {
+    for (const g of Object.values(seen)) if (g.items && g.items[id] !== undefined) return g.items[id];
+    return undefined;
+  };
+  const labelOf = (id) => {
+    const v = seenItem(id);
+    if (v !== undefined) return rail.seenLabel(v);
+    const c = customById.get(id);
+    return c ? c.label : id;
+  };
+  // What this entry ships as, so the control can offer to put back what the dashboard left out.
+  const shipsAs = (id) => rail.seenShips(seenItem(id));
+
+  // What it is right now: the layout's answer if there is one, otherwise the way the entry ships.
+  const shownAs = (id) => {
+    const asked = own.show[id];
+    if (asked) return asked === 'both' ? 'both' : asked;
+    return shipsAs(id) || 'both';
+  };
+  const hiddenCards = own.hidden.map((id) => entryCard(id, labelOf(id), 'hidden',
+    customById.has(id) ? { scope } : null, shownAs(id))).join('');
+
+  const commands = cc.loadCatalog().commands
+    .filter((c) => c.on === 'workspace' || c.on === 'project')
+    .map((c) => `<option value="${esc(c.id)}">${esc(c.label)} — ${esc(cc.ON[c.on] || c.on)}</option>`).join('');
+
+  return `<div id="nav-editor">
+    ${message || ''}
+    ${scopeTabsHtml(scope)}
+    <p class="uk-text-meta">${scope === 'global'
+      ? 'The navigation on every page. A workspace can add to this, or hide something from it, on its own tab.'
+      : `The navigation on the ${esc((loadWorkspaces()[scope] || {}).label || scope)} pages. Applied after the global one.`}
+      Drag an entry between the sidebar groups, up into a region of the top bar, or into Hidden; drag a
+      group by its handle to move the whole group. Each entry says how much of itself is shown — the icon,
+      the text, or both — wherever it sits. Hiding is presentation only: what an entry opened still answers.</p>
+
+    <!-- The group each entry posts is rewritten from the list it sits in, just before the request:
+         dragging moves the element, not the value it was rendered with. -->
+    <form id="nav-form" hx-post="/actions/nav-save" hx-target="#nav-editor" hx-swap="outerHTML"
+          hx-on::before:request="window.navSyncGroups && window.navSyncGroups()">
+      <input type="hidden" name="scope" value="${esc(scope)}">
+      <input type="hidden" name="mtime" value="${mtime}">
+      <section class="nav-place nav-place-topbar">
+        <header class="nav-place-head"><strong>Navigation topbar</strong>
+          <span class="uk-text-meta">· across the top of every page, in three regions</span></header>
+        <div class="nav-regions">
+          ${rail.REGIONS.map((r) => `<div class="nav-region" data-region="${r}">
+            <span class="nav-region-label">${esc(rail.TOPBAR_LABELS[r].replace('Topbar ', ''))}</span>
+            <ol class="nav-entries" data-group="topbar-${r}" uk-sortable="group: nav-entries; handle: .nav-handle">
+              ${regionIds[r]
+                .map((id) => entryCard(id, labelOf(id), `topbar-${r}`, customById.has(id) ? { scope } : null, shownAs(id))).join('')}
+            </ol>
+          </div>`).join('')}
+        </div>
+      </section>
+
+      <header class="nav-place-head"><strong>Navigation sidebar</strong>
+        <span class="uk-text-meta">· the rail down the right of every page</span></header>
+      <ol class="nav-groups" uk-sortable="handle: .nav-handle-group">
+        ${groups.map((g) => `<li class="nav-group" data-group="${esc(g.id)}">
+          <input type="hidden" name="group" value="${esc(g.id)}">
+          <header class="nav-group-head">
+            <span class="nav-handle nav-handle-group" title="Drag to move this group">${icon('table')}</span>
+            <strong>${esc(g.label)}</strong>
+          </header>
+          <ol class="nav-entries" data-group="${esc(g.id)}" uk-sortable="group: nav-entries; handle: .nav-handle">
+            ${g.ids.map((id) => entryCard(id, labelOf(id), g.id, customById.has(id) ? { scope } : null, shownAs(id))).join('')}
+          </ol>
+        </li>`).join('')}
+      </ol>
+
+      <section class="nav-group nav-group-hidden">
+        <header class="nav-group-head"><strong>Hidden</strong> <span class="uk-text-meta">· not shown on these pages</span></header>
+        <ol class="nav-entries" data-group="hidden" uk-sortable="group: nav-entries; handle: .nav-handle">${hiddenCards}</ol>
+      </section>
+
+      <p class="nav-save">
+        <button class="uk-button uk-button-primary" type="submit">${icon('check')} Save the navigation</button>
+        <!-- Adding opens in the editor modal, like every other form on a long page here: the add card
+             sat under a list of groups that can run past the fold, so the way to put something IN the
+             navigation was the one thing you had to scroll to find. The form still posts the whole
+             arrangement with it (hx-include), so a drag that has not been saved is not lost by adding. -->
+        <button class="uk-button uk-button-default" type="button" title="Add a link or a command button"
+                hx-get="/fragments/nav-add?scope=${encodeURIComponent(scope)}"
+                hx-target="#editor-modal-body" hx-swap="innerHTML"
+                hx-on::after:request="event.stopPropagation()">${icon('plus')} Add to this navigation</button>
+        <button class="uk-button uk-button-default arm-step" type="button" title="Reset this scope"
+                hx-post="/actions/nav-reset" hx-vals='${esc(JSON.stringify({ scope }))}'
+                hx-target="#nav-editor" hx-swap="outerHTML" hx-trigger="confirmed-remove">${icon('refresh')} Reset</button>
+      </p>
+    </form>
+
+  </div>`;
+}
+
+
+/**
+ * The Add form, drawn into the editor modal.
+ *
+ * It posts the whole arrangement with it (`hx-include="#nav-form"`, which is still on the page behind
+ * the modal), so a drag that has not been saved yet is not lost by adding something. The answer is the
+ * editor, which is what the modal is covering — so the modal closes on the way out, success or not: a
+ * refusal comes back as the editor with the reason at the top of it.
+ */
+function navAddFormHtml(scope) {
+  const { raw } = rail.loadLayout();
+  const seen = rail.seenFor(scope);
+  const own = rail.scopeLayout(raw, scope);
+  const groups = [...new Set([...own.groups, ...Object.keys(seen)])]
+    .filter((g) => !rail.TOPBAR_GROUPS.includes(g))
+    .map((g) => ({ id: g, label: (seen[g] && seen[g].label) || g }));
+  const commands = cc.loadCatalog().commands
+    .filter((c) => c.on === 'workspace' || c.on === 'project')
+    .map((c) => `<option value="${esc(c.id)}">${esc(c.label)} — ${esc(cc.ON[c.on] || c.on)}</option>`).join('');
+
+  return `<div class="editor-card nav-add">
+    <h3 class="uk-margin-small-bottom">Add to this navigation</h3>
+    <p class="uk-text-meta">A link goes somewhere; a button runs a command from the catalog, with the same
+      confirm dialog and the same history a row action has. An address outside this dashboard opens in a new tab.</p>
+    <form class="nav-add-form" hx-post="/actions/nav-add" hx-include="#nav-form"
+          hx-target="#nav-editor" hx-swap="outerHTML"
+          hx-on::before:request="window.navSyncGroups && window.navSyncGroups()"
+          hx-on::after:request="window.UIkit && UIkit.modal('#editor-modal').hide()">
+      <div class="uk-grid-small uk-child-width-1-2@s" uk-grid>
+        <div><label class="uk-form-label" for="nav-add-label">Label</label>
+          <input class="uk-input uk-form-small" id="nav-add-label" name="new_label" required placeholder="Jira" maxlength="40"></div>
+        <div><label class="uk-form-label" for="nav-add-icon">Icon</label>
+          <input class="uk-input uk-form-small" id="nav-add-icon" name="new_icon" placeholder="link" maxlength="40"
+                 title="A UIKit icon name, or tabler:<name>"></div>
+        <div><label class="uk-form-label" for="nav-add-group">Where it goes</label>
+          <select class="uk-select uk-form-small" id="nav-add-group" name="new_group">
+            <optgroup label="The navigation topbar">
+              ${rail.REGIONS.map((r) => `<option value="topbar-${r}">${esc(rail.TOPBAR_LABELS[r])}</option>`).join('')}
+            </optgroup>
+            <optgroup label="The navigation sidebar">
+              <option value="yours" selected>Yours — a group of its own, at the end</option>
+              ${groups.map((g) => `<option value="${esc(g.id)}">${esc(g.label)}</option>`).join('')}
+            </optgroup>
+          </select></div>
+        <div><label class="uk-form-label" for="nav-add-href">The address it opens</label>
+          <input class="uk-input uk-form-small" id="nav-add-href" name="new_href" placeholder="https://CHANGE_ME.atlassian.net"></div>
+        <div><label class="uk-form-label" for="nav-add-use">…or the command it runs</label>
+          <select class="uk-select uk-form-small" id="nav-add-use" name="new_use">
+            <option value="">— a link, not a command —</option>
+            ${commands}
+          </select></div>
+        <div><label class="uk-form-label uk-margin-small-top">
+          <input class="uk-checkbox" type="checkbox" name="new_confirm" value="1"> Ask before it runs</label></div>
+      </div>
+      <p><button class="uk-button uk-button-primary" type="submit">${icon('plus')} Add it</button></p>
+    </form>
+  </div>`;
+}
+
+module.exports = { navEditorHtml, navAddFormHtml, scopeTabsHtml };

package/navigation.js

@@ -0,0 +1,394 @@
+/**
+ * The navigation, as a layout: which of its entries are shown, WHERE, in what order, and what you added.
+ *
+ * There are two places an entry can be. The **navigation sidebar** is the rail down the right of every
+ * page, grouped by concern. The **navigation topbar** is the bar across the top, in three regions —
+ * start (beside the wordmark), center, end (before the theme toggle) — which is where the few things
+ * someone reaches for on every page belong, and where a bare icon reads as a tool rather than a link.
+ * An entry moves between them by being dragged, and an entry added can be put straight into either.
+ *
+ * The rail is on every page and it is built in code — a group per concern (Create, Sync, Screens, Run,
+ * Archives, Go) with the page's own actions first and the navigation last. That is a good default and a
+ * bad fixed set: a machine that never deploys does not want Upsun in it, a team lives in Jira and would
+ * put it there, and which of nineteen workspaces you actually open differs per person.
+ *
+ * So it is arranged the way the project rows are (row-layout.js), with the same shape and the same
+ * rules — one file for this machine, holding only what someone changed:
+ *
+ *   core/config/navigation.yml
+ *     global:                      applies on every page
+ *       hidden:  [ids…]            entries not shown
+ *       groups:  [group ids…]      the order of the sidebar groups; anything unlisted keeps its place after them
+ *       order:   { <group>: [ids…] }   the order inside one group
+ *       topbar:  { start: [ids…], center: [ids…], end: [ids…] }   entries moved up to the top bar
+ *       show:    { <id>: icon | text }  entries shown as the icon alone, or as the label alone —
+ *                                  absent means both, which is what every entry is until someone says
+ *       items:   [item…]           entries you added
+ *     workspaces:
+ *       dev: { the same four keys }    applied after global, on that workspace's pages
+ *
+ * An added entry is a link or a button:
+ *
+ *   id, label, icon, group, description
+ *   href:    where it goes (a link) — external URLs open in a new tab
+ *   use:     <command id> — runs that command of the catalog instead, like a row action does
+ *   confirm: true → asks in the dialog first
+ *
+ * The defaults live in the code that builds the rail, so an entry added to the dashboard later appears
+ * in its own group until someone moves it, and deleting the file is a full reset. `sync-tooling.sh`
+ * copies only `workspace.*.settings.yml` into `core/config`, so a `--pull` never touches this.
+ *
+ * **What the editor can offer is what has been SEEN.** The rail differs per page — a files workspace has
+ * Sync, a project workspace has Screens and Run — so nothing here can enumerate the entries from first
+ * principles without rendering every page. Each render records what it drew into
+ * `core/config/rail.seen.json`, per scope, and the editor lists that. An id that is no longer drawn stays
+ * in the file and does nothing, which is what makes a hidden entry survive a dashboard that renamed it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const { esc } = require('./html');
+const { CONFIG_DIR } = require('./workspaces');
+
+// Overridable so a test can arrange a navigation without touching the machine's own, the way
+// row-layout.js is. Read through the functions, never captured at require time.
+const layoutFile = () => process.env.NAVIGATION_FILE || path.join(CONFIG_DIR, 'navigation.yml');
+const seenFile = () => process.env.NAVIGATION_SEEN_FILE || path.join(CONFIG_DIR, 'navigation.seen.json');
+
+// An id is a slug: it names an entry in a YAML file a person edits, and it ends up in a CSS selector
+// and a query string. Anything else is refused rather than escaped into unreadability.
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+const isId = (v) => ID_RE.test(String(v || ''));
+
+// Where an entry can go besides a sidebar group. These are group ids in the editor — a list you drag
+// into — so the whole arrangement stays one form and one drag, rather than a placement dropdown per
+// entry. `hidden` is the fourth of them: not shown anywhere.
+const REGIONS = ['start', 'center', 'end'];
+const TOPBAR_GROUPS = REGIONS.map((r) => `topbar-${r}`);
+const RESERVED = new Set([...TOPBAR_GROUPS, 'hidden']);
+/** 'topbar-center' → 'center'; anything else → null. */
+const regionOf = (group) => (TOPBAR_GROUPS.includes(String(group)) ? String(group).slice('topbar-'.length) : null);
+const emptyTopbar = () => Object.fromEntries(REGIONS.map((r) => [r, []]));
+const TOPBAR_LABELS = { start: 'Topbar start', center: 'Topbar center', end: 'Topbar end' };
+
+/**
+ * The id of a rail entry, derived from its label. Counts are stripped — "Backups (2)" and "Run a tool
+ * (13)" change with the tree, and a layout keyed on them would forget itself the moment a backup was
+ * taken. A caller with a better id passes one.
+ */
+function slugId(label) {
+  return String(label)
+    .replace(/\s*\([^)]*\)\s*$/, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'item';
+}
+
+/** Which layout applies on a page: a workspace's own, or the global one. */
+function scopeFor(context) {
+  const m = String(context || '').match(/^(?:workspace|backups):([a-z0-9_-]+)$/);
+  return m ? m[1] : 'global';
+}
+
+const EMPTY = { hidden: [], groups: [], order: {}, topbar: emptyTopbar(), show: {}, items: [] };
+
+function readYaml() {
+  try {
+    return yaml.load(fs.readFileSync(layoutFile(), 'utf8')) || {};
+  } catch (_) {
+    return {};
+  }
+}
+
+/** One scope's settings, with every key present so callers never test for undefined. */
+function scopeLayout(raw, scope) {
+  const src = (scope === 'global' ? raw.global : ((raw.workspaces || {})[scope])) || {};
+  return {
+    hidden: (Array.isArray(src.hidden) ? src.hidden : []).filter(isId),
+    groups: (Array.isArray(src.groups) ? src.groups : []).filter(isId),
+    order: Object.fromEntries(Object.entries(src.order || {})
+      .filter(([g, list]) => isId(g) && Array.isArray(list))
+      .map(([g, list]) => [g, list.filter(isId)])),
+    topbar: Object.fromEntries(REGIONS.map((r) => {
+      const list = ((src.topbar || {})[r]);
+      return [r, (Array.isArray(list) ? list : []).filter(isId)];
+    })),
+    show: Object.fromEntries(Object.entries(src.show || {})
+      .filter(([id, how]) => isId(id) && (how === 'icon' || how === 'text' || how === 'both'))),
+    items: (Array.isArray(src.items) ? src.items : []).filter((it) => it && isId(it.id) && it.label),
+  };
+}
+
+let memo = { at: 0, mtime: 0, raw: null };
+
+function loadLayout() {
+  const now = Date.now();
+  let mtime = 0;
+  try { mtime = fs.statSync(layoutFile()).mtimeMs; } catch (_) { mtime = 0; }
+  // Re-read when the file moved, and at most every 2s otherwise: this is on the critical path of every
+  // page, and workspaces.js memoises its own config the same way.
+  if (!memo.raw || mtime !== memo.mtime || now - memo.at > 2000) {
+    memo = { at: now, mtime, raw: readYaml() };
+  }
+  return { raw: memo.raw, mtime: memo.mtime };
+}
+
+/** The two layouts that apply on a page, global first. A workspace's own settings are applied after it. */
+function layoutsFor(scope) {
+  const { raw } = loadLayout();
+  const global = scopeLayout(raw, 'global');
+  return scope === 'global' ? [global] : [global, scopeLayout(raw, scope)];
+}
+
+/** Every scope the editor offers: the global one, then each workspace, in the order the cards are in. */
+function navScopes(workspaceKeys) {
+  return ['global', ...workspaceKeys];
+}
+
+/* ------------------------------------------------------------------ *
+ * What the rail has drawn, so the editor can offer it
+ * ------------------------------------------------------------------ */
+
+function readSeen() {
+  try {
+    const seen = JSON.parse(fs.readFileSync(seenFile(), 'utf8'));
+    return seen && typeof seen === 'object' ? seen : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+let seenMemo = null;
+
+/**
+ * Record what one page's rail drew. Written only when something is new, because this runs on every page
+ * render and a file written per request would be a write per page view for no gain.
+ */
+function recordSeen(scope, arranged) {
+  const seen = seenMemo || (seenMemo = readSeen());
+  const bucket = seen[scope] || (seen[scope] = {});
+  let changed = false;
+  // The top bar is recorded the same way, under its region: an entry moved up there is in no sidebar
+  // group any more, and the editor reads its label out of this file.
+  const groups = [
+    ...arranged.groups,
+    ...REGIONS.map((r) => ({ id: `topbar-${r}`, label: TOPBAR_LABELS[r], items: arranged.topbar[r] })),
+  ];
+  for (const g of groups) {
+    const entry = bucket[g.id] || (bucket[g.id] = { label: g.label, items: {} });
+    if (entry.label !== g.label) { entry.label = g.label; changed = true; }
+    // Rebuilt in the order this page DREW them, with anything seen before appended after — so a hidden
+    // entry, or one only another page draws, survives, and the editor lists them in the order they
+    // actually appear. Kept as insertion order rather than a list because that is what this file has
+    // always been. Only what the dashboard itself builds is recorded: an entry someone added is already
+    // in the layout, and recording it too leaves a ghost behind once it is removed.
+    // An entry that SHIPS one way — the assistant is its mark and nothing else — records that here, so
+    // the editor knows what "both" would be overriding and can offer to put the label back. A plain
+    // string is the common case and stays one; only an entry with a default of its own grows an object.
+    const items = {};
+    for (const it of g.items) if (!it.custom) items[it.id] = it.ships ? { label: it.label, show: it.ships } : it.label;
+    for (const [id, was] of Object.entries(entry.items)) if (!(id in items)) items[id] = was;
+    if (JSON.stringify(items) !== JSON.stringify(entry.items)) { entry.items = items; changed = true; }
+  }
+  if (!changed) return;
+  try {
+    fs.mkdirSync(path.dirname(seenFile()), { recursive: true });
+    fs.writeFileSync(seenFile(), JSON.stringify(seen, null, 2));
+  } catch (_) { /* a rail that cannot record itself still renders */ }
+}
+
+/** A seen item is a label, or a label with the way that entry ships. */
+const seenLabel = (v) => (v && typeof v === 'object' ? v.label : v);
+const seenShips = (v) => (v && typeof v === 'object' ? (v.show || '') : '');
+
+/** What the editor lists for one scope: every group and entry that scope has actually drawn. */
+function seenFor(scope) {
+  const seen = seenMemo || (seenMemo = readSeen());
+  return seen[scope] || {};
+}
+
+/* ------------------------------------------------------------------ *
+ * Applying a layout to the groups the page built
+ * ------------------------------------------------------------------ */
+
+/**
+ * An entry someone added, as the rail's own markup. A link goes where it points; a `use:` runs a command
+ * of the catalog through the same endpoint a row action does, so there is one runner and one history.
+ */
+function customItemHtml(item) {
+  const icon = isId(item.icon) || /^tabler:[a-z0-9-]+$/.test(String(item.icon || '')) ? item.icon : 'link';
+  const label = `<span uk-icon="icon: ${esc(String(icon).replace(/^tabler:/, ''))}; ratio: .8"></span>`
+    + `<span class="action-label">${esc(item.label)}</span>`;
+  const title = esc(item.description || item.label);
+  if (item.use) {
+    // The same route, the same confirm dialog and the same history as a row action's `use:` step.
+    const vals = esc(JSON.stringify({ id: `rail:${item.id}`, use: item.use }));
+    return `<button class="uk-button uk-button-default action-btn${item.confirm ? ' arm-step' : ''}" type="button"`
+      + ` title="${title}" hx-post="/actions/nav-run" hx-vals='${vals}'`
+      + ` hx-target="#webship-workspace-output" hx-swap="innerHTML"`
+      + `${item.confirm ? ' hx-trigger="confirmed-remove"' : ''}>${label}</button>`;
+  }
+  const href = String(item.href || '');
+  // An address off this dashboard opens in a new tab: the rail is navigation within the workspace, and
+  // replacing the page you are working on with an external site is not what a rail entry should do.
+  const external = /^https?:\/\//i.test(href) && !href.includes('.ddev.site');
+  return `<a class="uk-button uk-button-default action-btn" href="${esc(href)}" title="${title}"`
+    + `${external ? ' target="_blank" rel="noopener"' : ''}>${label}</a>`;
+}
+
+/**
+ * Hide, reorder and add — global first, then the workspace's own.
+ *
+ * Everything here is presentation: a hidden entry's route still answers exactly as it did, and an entry
+ * the dashboard no longer draws simply does not appear, rather than leaving a hole or an error.
+ */
+function arrange(groups, scope) {
+  const layouts = layoutsFor(scope);
+  const hidden = new Set(layouts.flatMap((l) => l.hidden));
+  const groupOrder = layouts.map((l) => l.groups).filter((g) => g.length).pop() || [];
+  const itemOrder = Object.assign({}, ...layouts.map((l) => l.order));
+  const added = layouts.flatMap((l) => l.items);
+
+  // Which entries were moved to the top bar, and to which region. A later scope wins outright: a
+  // workspace that puts something in the topbar means that page, not "as well as wherever global had it".
+  const region = new Map();
+  for (const l of layouts) {
+    for (const r of REGIONS) for (const id of l.topbar[r]) region.set(id, r);
+  }
+  // Every id the layout has an opinion about. An entry the dashboard SHIPS in the top bar (an entry with
+  // its own `topbar:`) stays there until someone says otherwise — and naming it anywhere, even by
+  // dragging it into a sidebar group, is saying otherwise.
+  const named = new Set([
+    ...hidden,
+    ...region.keys(),
+    ...layouts.flatMap((l) => Object.values(l.order).flat()),
+  ]);
+  const topbar = emptyTopbar();
+  // The icon alone, the label alone, or both — in whichever place the entry sits, because that is about
+  // how much room the entry is worth, not about which strip of the screen it is on. Both is what every
+  // entry is until someone says otherwise, and an entry that ships one way (the assistant is its mark
+  // and nothing else) keeps it until the layout names it.
+  const show = Object.assign({}, ...layouts.map((l) => l.show));
+  // `ships` is what the dashboard built the entry as; `show` is what it ends up as. An explicit `both`
+  // in the layout is what turns a shipped default back off, which is why both is written down when it
+  // overrides something and left out when it does not.
+  const shownAs = (it) => {
+    const asked = show[it.id];
+    if (asked) return asked === 'both' ? '' : asked;
+    return it.show || '';
+  };
+
+  let out = groups.map((g) => ({
+    ...g,
+    items: g.items.filter((it) => !hidden.has(it.id))
+      .map((it) => ({ ...it, ships: it.show || '', show: shownAs(it) })),
+  }));
+
+  // An added entry joins the group it names, or makes one of its own at the end — a group that exists
+  // only on some pages (Sync, Screens) must not swallow an entry on the pages that lack it. Naming a
+  // topbar region instead puts it up there.
+  for (const item of added) {
+    if (hidden.has(item.id)) continue;
+    const entry = { id: item.id, label: item.label, html: customItemHtml(item), custom: true };
+    entry.show = shownAs(entry);
+    const asked = regionOf(item.group);
+    if (asked && !region.has(item.id)) region.set(item.id, asked);
+    if (region.has(item.id)) { topbar[region.get(item.id)].push(entry); continue; }
+    const wanted = isId(item.group) ? item.group : 'yours';
+    const target = out.find((g) => g.id === wanted);
+    if (target) target.items.push(entry);
+    else out.push({ id: wanted, label: item.group_label || (wanted === 'yours' ? 'Yours' : item.group), items: [entry] });
+  }
+
+  // Anything else the layout moved up leaves the group it was built in. The sidebar and the topbar are
+  // one arrangement, so an entry is in exactly one of them.
+  const placeOf = (it) => region.get(it.id)
+    || (!named.has(it.id) && REGIONS.includes(it.topbar) ? it.topbar : null);
+  for (const g of out) {
+    const moved = g.items.filter((it) => placeOf(it) && !it.custom);
+    if (!moved.length) continue;
+    g.items = g.items.filter((it) => !placeOf(it) || it.custom);
+    for (const it of moved) topbar[placeOf(it)].push(it);
+  }
+
+  for (const g of out) {
+    const order = itemOrder[g.id];
+    if (!order || !order.length) continue;
+    const rank = new Map(order.map((id, i) => [id, i]));
+    // Anything unlisted keeps its place AFTER what was ordered, in the order the page built it: a new
+    // entry in the dashboard must not disappear into the middle of somebody's arrangement.
+    g.items = [...g.items].sort((a, b) =>
+      (rank.has(a.id) ? rank.get(a.id) : order.length + 1) - (rank.has(b.id) ? rank.get(b.id) : order.length + 1));
+  }
+
+  // Each region is ordered by the list that put the entries there, newest scope last.
+  const wanted = emptyTopbar();
+  for (const l of layouts) for (const r of REGIONS) for (const id of l.topbar[r]) if (!wanted[r].includes(id)) wanted[r].push(id);
+  for (const r of REGIONS) {
+    const rank = new Map(wanted[r].map((id, i) => [id, i]));
+    topbar[r].sort((a, b) =>
+      (rank.has(a.id) ? rank.get(a.id) : wanted[r].length + 1) - (rank.has(b.id) ? rank.get(b.id) : wanted[r].length + 1));
+  }
+
+  if (groupOrder.length) {
+    const rank = new Map(groupOrder.map((id, i) => [id, i]));
+    out = [...out].sort((a, b) =>
+      (rank.has(a.id) ? rank.get(a.id) : groupOrder.length + 1) - (rank.has(b.id) ? rank.get(b.id) : groupOrder.length + 1));
+  }
+
+  return { groups: out.filter((g) => g.items.length && !hidden.has(g.id)), topbar };
+}
+
+/* ------------------------------------------------------------------ *
+ * Writing
+ * ------------------------------------------------------------------ */
+
+function saveLayout(raw) {
+  const body = '# The navigation: what the sidebar and the top bar show, in what order, and what you added.\n'
+    + '# Written by Commands → Navigation. Only what you changed is here; deleting this file is a full reset.\n'
+    + '# Never synced: sync-tooling.sh copies only workspace.*.settings.yml into core/config.\n'
+    + yaml.dump(raw, { lineWidth: 100 });
+  fs.mkdirSync(path.dirname(layoutFile()), { recursive: true });
+  fs.writeFileSync(layoutFile(), body);
+  memo = { at: 0, mtime: 0, raw: null };
+  return fs.statSync(layoutFile()).mtimeMs;
+}
+
+/** The whole file, for a writer that is about to change one scope in it. */
+function rawLayout() {
+  const { raw, mtime } = loadLayout();
+  return { raw: JSON.parse(JSON.stringify(raw || {})), mtime };
+}
+
+/** Put one scope's settings back into the whole file, dropping what is empty so the file stays readable. */
+function withScope(raw, scope, settings) {
+  const clean = {};
+  if (settings.hidden && settings.hidden.length) clean.hidden = settings.hidden;
+  if (settings.groups && settings.groups.length) clean.groups = settings.groups;
+  if (settings.order && Object.keys(settings.order).length) clean.order = settings.order;
+  const topbar = Object.fromEntries(REGIONS.map((r) => [r, (settings.topbar || {})[r] || []]).filter(([, v]) => v.length));
+  if (Object.keys(topbar).length) clean.topbar = topbar;
+  if (settings.show && Object.keys(settings.show).length) clean.show = settings.show;
+  if (settings.items && settings.items.length) clean.items = settings.items;
+  const out = { ...raw };
+  if (scope === 'global') {
+    if (Object.keys(clean).length) out.global = clean; else delete out.global;
+  } else {
+    const ws = { ...(out.workspaces || {}) };
+    if (Object.keys(clean).length) ws[scope] = clean; else delete ws[scope];
+    if (Object.keys(ws).length) out.workspaces = ws; else delete out.workspaces;
+  }
+  return out;
+}
+
+module.exports = {
+  layoutFile, seenFile,
+  isId, slugId, scopeFor, navScopes,
+  REGIONS, TOPBAR_GROUPS, TOPBAR_LABELS, RESERVED, regionOf, emptyTopbar,
+  loadLayout, scopeLayout, layoutsFor, rawLayout, withScope, saveLayout,
+  arrange, customItemHtml, seenLabel, seenShips,
+  recordSeen, seenFor,
+};