domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/plans/2026-08-19-collection-context-sort-export.md

@@ -0,0 +1,1577 @@
+# Collection Context Menu - Sort, Group, Export & Copy - Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extend the public-site right-click collection menu from filter-only to filter + sort + group + export + copy + print, with export permissions set in the collection schema and edited from the admin.
+
+**Architecture:** A new shared ESM module `public/js/collection-export.mjs` owns the CSV/JSON/Markdown dialect and is imported by both the browser menu and the server's `exportEntries()`, so the two cannot diverge. `collection-context.js` keeps ownership of menu and display state, gaining a drill-in panel stack, a sort comparator, and grouping. Export permission is resolved server-side into the `data-ctx` payload and gated client-side.
+
+**Tech Stack:** Node 20+ ESM, Fastify 5, `node:test` + `assert/strict`, Domma (`$`/`T`/`E`), no build step for `public/js`.
+
+**Spec:** `docs/superpowers/specs/2026-08-19-collection-context-sort-export-design.md`
+
+---
+
+## File Structure
+
+| File | Responsibility |
+|---|---|
+| `public/js/collection-export.mjs` | **New.** Value coercion, CSV dialect, JSON/Markdown serialisation, download + clipboard sinks. The only place that knows how a value becomes text. |
+| `public/js/collection-context.js` | Menu, panel stack, filter/sort/group state, per-display-type application. Grows; does not own serialisation. |
+| `public/js/site.js` | Passes table export config from payload to wrapper. Single-line change. |
+| `public/css/site.css` | Group headings, print stylesheet. |
+| `server/services/markdown.js` | `buildCtxAttr()` third parameter; export-permission resolution; threaded through 8 call sites. |
+| `server/services/collections.js` | `exportEntries()` delegates to the shared dialect. |
+| `server/templates/page.html` | `collection-context.js` becomes `type="module"`; cache-buster bumps. |
+| `admin/js/templates/collection-editor.html` | Tab rename; export rows. |
+| `admin/js/views/collection-editor.js` | Render/read/save the `export` block. |
+| `tests/services/csv-dialect.test.js` | **New.** The dialect's unit tests. |
+| `tests/services/collections-export.test.js` | **New.** `exportEntries()` behaviour incl. the `[object Object]` regression. |
+| `tests/markdown/collection-ctx-export.test.js` | **New.** Export config resolution in `buildCtxAttr`. |
+
+**Why `.mjs`:** root `package.json` is `"type": "module"`, but `public/js/package.json` pins `"type": "commonjs"`, so a `.js` file there is CommonJS to Node. `.mjs` is ESM unconditionally - importable by Node tests, by `server/services/collections.js`, and by a browser `type="module"` script. `public/js/menu-decor.mjs` is the existing precedent.
+
+---
+
+## Task 1: The shared CSV dialect
+
+**Files:**
+- Create: `public/js/collection-export.mjs`
+- Test: `tests/services/csv-dialect.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/services/csv-dialect.test.js`:
+
+```js
+/**
+ * Shared CSV dialect - the single source of truth for turning collection
+ * values into CSV text, used by both the browser export menu and the
+ * server's exportEntries(). Locks in coercion, formula-injection
+ * sanitising, quoting, and the Excel BOM.
+ */
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {coerce, sanitiseCsv, csvCell, toCsv, CSV_BOM} from '../../public/js/collection-export.mjs';
+
+test('coerce: nullish becomes empty string', () => {
+    assert.equal(coerce(null), '');
+    assert.equal(coerce(undefined), '');
+});
+
+test('coerce: arrays join with semicolons', () => {
+    assert.equal(coerce(['news', 'tech']), 'news; tech');
+    assert.equal(coerce([]), '');
+});
+
+test('coerce: objects stringify rather than [object Object]', () => {
+    assert.equal(coerce({title: 'Hi'}), '{"title":"Hi"}');
+});
+
+test('coerce: dates become ISO 8601', () => {
+    assert.equal(coerce(new Date('2026-08-19T10:00:00Z')), '2026-08-19T10:00:00.000Z');
+});
+
+test('sanitiseCsv: formula leaders are neutralised', () => {
+    assert.equal(sanitiseCsv('=HYPERLINK("http://x")'), "'=HYPERLINK(\"http://x\")");
+    assert.equal(sanitiseCsv('@SUM(A1)'), "'@SUM(A1)");
+    assert.equal(sanitiseCsv('+1 555 0100'), "'+1 555 0100");
+});
+
+test('sanitiseCsv: finite numbers are exempt so -5 survives', () => {
+    assert.equal(sanitiseCsv('-5'), '-5');
+    assert.equal(sanitiseCsv('-12.75'), '-12.75');
+});
+
+test('sanitiseCsv: ordinary text is untouched', () => {
+    assert.equal(sanitiseCsv('Hello'), 'Hello');
+    assert.equal(sanitiseCsv(''), '');
+});
+
+test('csvCell: quotes always, escapes embedded quotes', () => {
+    assert.equal(csvCell('plain'), '"plain"');
+    assert.equal(csvCell('say "hi"'), '"say ""hi"""');
+    assert.equal(csvCell('a,b'), '"a,b"');
+    assert.equal(csvCell('line1\nline2'), '"line1\nline2"');
+});
+
+test('csvCell: accented text passes through unchanged', () => {
+    assert.equal(csvCell('café'), '"café"');
+});
+
+test('toCsv: BOM, quoted header from labels, newline-separated rows', () => {
+    const columns = [{name: 'title', label: 'Title'}, {name: 'qty'}];
+    const rows = [{title: 'One', qty: 1}, {title: 'Two', qty: -2}];
+    const out = toCsv(rows, columns);
+    assert.ok(out.startsWith(CSV_BOM), 'output must start with the BOM');
+    assert.equal(out.slice(1), '"Title","qty"\n"One","1"\n"Two","-2"');
+});
+
+test('toCsv: missing values render as empty cells', () => {
+    const out = toCsv([{title: 'Only'}], [{name: 'title'}, {name: 'absent'}]);
+    assert.equal(out.slice(1), '"title","absent"\n"Only",""');
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `node --test tests/services/csv-dialect.test.js`
+Expected: FAIL - `Cannot find module .../public/js/collection-export.mjs`
+
+- [ ] **Step 3: Write the implementation**
+
+Create `public/js/collection-export.mjs`:
+
+```js
+/**
+ * Collection export - the shared serialisation dialect.
+ *
+ * Imported by BOTH the browser (public/js/collection-context.js, as a module
+ * script) and the server (server/services/collections.js). Keeping one copy is
+ * the whole point: the admin's export button and the public right-click export
+ * must produce byte-identical files for the same values.
+ *
+ * `.mjs` is deliberate - public/js/package.json pins "type": "commonjs", so a
+ * .js file here would be CommonJS to Node and unimportable from server ESM.
+ */
+
+/** Excel needs a BOM to read UTF-8 correctly. */
+export const CSV_BOM = '';
+
+/**
+ * Turn any collection value into a string.
+ * Arrays join with '; ' (semicolons survive a CSV round-trip; commas do not).
+ * Objects stringify - String({}) would give the useless '[object Object]'.
+ */
+export function coerce(v) {
+    if (v === null || v === undefined) return '';
+    if (Array.isArray(v)) return v.map(coerce).join('; ');
+    if (v instanceof Date) return v.toISOString();
+    if (typeof v === 'object') return JSON.stringify(v);
+    return String(v);
+}
+
+const FORMULA_LEAD = /^[=+\-@\t\r]/;
+
+/**
+ * Neutralise spreadsheet formula injection. A cell beginning =, +, -, @, TAB
+ * or CR is executed as a formula by Excel and Sheets, and collection content
+ * is user-authored, so this is a live path.
+ *
+ * Finite numbers are exempt - without that exemption every negative number
+ * would export as '-5 rather than -5.
+ */
+export function sanitiseCsv(s) {
+    if (!FORMULA_LEAD.test(s)) return s;
+    if (s !== '' && Number.isFinite(Number(s))) return s;
+    return "'" + s;
+}
+
+/** One CSV cell: coerced, sanitised, always quoted, inner quotes doubled. */
+export function csvCell(v) {
+    return '"' + sanitiseCsv(coerce(v)).replace(/"/g, '""') + '"';
+}
+
+/**
+ * @param {object[]} rows    - plain value objects
+ * @param {Array<{name: string, label?: string}>} columns
+ * @returns {string} CSV text, BOM-prefixed, LF-separated
+ */
+export function toCsv(rows, columns) {
+    const header = columns.map(c => csvCell(c.label || c.name)).join(',');
+    const body = rows.map(r => columns.map(c => csvCell(r[c.name])).join(','));
+    return CSV_BOM + [header, ...body].join('\n');
+}
+```
+
+Line endings are LF, not RFC 4180's CRLF - this matches what `exportEntries()` already emits, and changing it would break operators' existing importers for no user-visible gain.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `node --test tests/services/csv-dialect.test.js`
+Expected: PASS, 11 tests
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add public/js/collection-export.mjs tests/services/csv-dialect.test.js
+git commit -m "feat(export): shared CSV dialect with injection sanitising and BOM"
+```
+
+---
+
+## Task 2: JSON and Markdown serialisation
+
+**Files:**
+- Modify: `public/js/collection-export.mjs`
+- Test: `tests/services/csv-dialect.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `tests/services/csv-dialect.test.js`:
+
+```js
+import {serialise} from '../../public/js/collection-export.mjs';
+
+const COLS = [{name: 'title', label: 'Title'}, {name: 'qty', label: 'Qty'}];
+const ROWS = [{title: 'One', qty: 1}, {title: 'Two | pipe', qty: -2}];
+
+test('serialise json: array of objects keyed by field name', () => {
+    assert.equal(serialise(ROWS, COLS, 'json'),
+        JSON.stringify([{title: 'One', qty: 1}, {title: 'Two | pipe', qty: -2}], null, 2));
+});
+
+test('serialise json: restricted to the given columns', () => {
+    const out = JSON.parse(serialise([{title: 'A', secret: 'x'}], COLS, 'json'));
+    assert.deepEqual(Object.keys(out[0]), ['title', 'qty']);
+});
+
+test('serialise markdown: pipe table with escaped pipes', () => {
+    assert.equal(serialise(ROWS, COLS, 'markdown'), [
+        '| Title | Qty |',
+        '| --- | --- |',
+        '| One | 1 |',
+        '| Two \\| pipe | -2 |'
+    ].join('\n'));
+});
+
+test('serialise csv: delegates to toCsv', () => {
+    assert.equal(serialise(ROWS, COLS, 'csv'), toCsv(ROWS, COLS));
+});
+
+test('serialise: unknown format throws rather than returning junk', () => {
+    assert.throws(() => serialise(ROWS, COLS, 'xml'), /Unknown export format/);
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `node --test tests/services/csv-dialect.test.js`
+Expected: FAIL - `serialise` is not exported
+
+- [ ] **Step 3: Write the implementation**
+
+Append to `public/js/collection-export.mjs`:
+
+```js
+/** Markdown table cells must not break the pipe grid. */
+function mdCell(v) {
+    return coerce(v).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+/**
+ * Serialise rows to text. The column list doubles as the field allowlist -
+ * a field absent from `columns` cannot appear in the output.
+ *
+ * @param {object[]} rows
+ * @param {Array<{name: string, label?: string}>} columns
+ * @param {'csv'|'json'|'markdown'} format
+ * @returns {string}
+ */
+export function serialise(rows, columns, format) {
+    if (format === 'csv') return toCsv(rows, columns);
+    if (format === 'json') {
+        return JSON.stringify(
+            // `?? null` is load-bearing: JSON.stringify DROPS undefined values,
+            // so a row missing a field would silently lose that key and the
+            // export would have ragged objects. null keeps every column present.
+            rows.map(r => Object.fromEntries(columns.map(c => [c.name, r[c.name] ?? null]))),
+            null, 2
+        );
+    }
+    if (format === 'markdown') {
+        return [
+            '| ' + columns.map(c => mdCell(c.label || c.name)).join(' | ') + ' |',
+            '| ' + columns.map(() => '---').join(' | ') + ' |',
+            ...rows.map(r => '| ' + columns.map(c => mdCell(r[c.name])).join(' | ') + ' |')
+        ].join('\n');
+    }
+    throw new Error(`Unknown export format: ${format}`);
+}
+```
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `node --test tests/services/csv-dialect.test.js`
+Expected: PASS, 16 tests
+
+All 16 were run against this exact implementation during planning, so a failure here means a
+transcription slip rather than a design gap.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add public/js/collection-export.mjs tests/services/csv-dialect.test.js
+git commit -m "feat(export): JSON and Markdown serialisation"
+```
+
+---
+
+## Task 3: Server `exportEntries()` adopts the dialect
+
+Fixes the live `[object Object]` bug for object-valued fields such as `blog-posts.seo`.
+
+**Files:**
+- Modify: `server/services/collections.js:475-497`
+- Test: `tests/services/collections-export.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/services/collections-export.test.js`:
+
+```js
+/**
+ * exportEntries() - CSV/JSON export of a whole collection from the admin.
+ * Locks in the shared dialect, most importantly that object-valued fields
+ * no longer export as the literal string [object Object].
+ */
+import {after, before, test} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'fs/promises';
+import path from 'path';
+import {exportEntries} from '../../server/services/collections.js';
+import {CSV_BOM} from '../../public/js/collection-export.mjs';
+
+const SLUG = 'rt-export-audit';
+const DIR = path.resolve('content/collections', SLUG);
+
+before(async () => {
+    await fs.mkdir(DIR, {recursive: true});
+    await fs.writeFile(path.join(DIR, 'schema.json'), JSON.stringify({
+        slug: SLUG, name: 'Export Audit',
+        fields: [{name: 'title', type: 'text'}, {name: 'seo', type: 'json'}, {name: 'tags', type: 'text'}]
+    }));
+    await fs.writeFile(path.join(DIR, 'e1.json'), JSON.stringify({
+        id: 'e1',
+        data: {title: 'First', seo: {desc: 'A "quoted" desc'}, tags: ['a', 'b']},
+        meta: {createdAt: '2026-08-19T00:00:00.000Z'}
+    }));
+    await fs.writeFile(path.join(DIR, 'e2.json'), JSON.stringify({
+        id: 'e2',
+        data: {title: '=cmd|calc', seo: null, tags: []},
+        meta: {createdAt: '2026-08-19T00:00:01.000Z'}
+    }));
+});
+
+after(async () => { await fs.rm(DIR, {recursive: true, force: true}); });
+
+test('csv: object fields stringify instead of [object Object]', async () => {
+    const csv = await exportEntries(SLUG, 'csv');
+    assert.ok(!csv.includes('[object Object]'), 'regression: object exported as [object Object]');
+    // The cell holds JSON, so its quotes are CSV-doubled. Assert the shape
+    // rather than the exact byte soup, which is unreadable in a literal.
+    assert.ok(csv.includes('""desc""'), 'nested object should appear as escaped JSON');
+});
+
+test('csv: arrays join with semicolons', async () => {
+    const csv = await exportEntries(SLUG, 'csv');
+    assert.ok(csv.includes('"a; b"'));
+});
+
+test('csv: formula-leading values are sanitised', async () => {
+    const csv = await exportEntries(SLUG, 'csv');
+    assert.ok(csv.includes(`"'=cmd|calc"`));
+});
+
+test('csv: starts with the BOM and keeps id/createdAt columns', async () => {
+    const csv = await exportEntries(SLUG, 'csv');
+    assert.ok(csv.startsWith(CSV_BOM));
+    const header = csv.slice(1).split('\n')[0];
+    assert.equal(header, '"id","title","seo","tags","createdAt"');
+});
+
+test('json export is unchanged', async () => {
+    const json = JSON.parse(await exportEntries(SLUG, 'json'));
+    assert.equal(json.length, 2);
+    assert.equal(json[0].data.title, 'First');
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `node --test tests/services/collections-export.test.js`
+Expected: FAIL - the `[object Object]` assertion and the BOM assertion both fail
+
+- [ ] **Step 3: Write the implementation**
+
+In `server/services/collections.js`, add near the other imports:
+
+```js
+import {toCsv} from '../../public/js/collection-export.mjs';
+```
+
+Replace the `if (format === 'csv') { ... }` block inside `exportEntries` (currently `:482-493`) with:
+
+```js
+    if (format === 'csv') {
+        const columns = [
+            {name: 'id'},
+            ...schema.fields.map(f => ({name: f.name})),
+            {name: 'createdAt'}
+        ];
+        const rows = entries.map(e => ({
+            id: e.id,
+            ...Object.fromEntries(schema.fields.map(f => [f.name, e.data?.[f.name]])),
+            createdAt: e.meta?.createdAt || ''
+        }));
+        return toCsv(rows, columns);
+    }
+```
+
+Note two deliberate output changes: the header row is now quoted like every other row, and the file is BOM-prefixed. Both are consequences of adopting the shared dialect.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `node --test tests/services/collections-export.test.js`
+Expected: PASS, 5 tests
+
+- [ ] **Step 5: Run the full suite for regressions**
+
+Run: `npm test`
+Expected: PASS. Any pre-existing test asserting an unquoted CSV header must be updated to the quoted form - that is the intended change, not a break.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add server/services/collections.js tests/services/collections-export.test.js
+git commit -m "fix(export): object fields no longer export as [object Object]"
+```
+
+---
+
+## Task 4: Server resolves export permission into the ctx payload
+
+**Files:**
+- Modify: `server/services/markdown.js:186-197` and its 8 call sites
+- Test: `tests/markdown/collection-ctx-export.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/markdown/collection-ctx-export.test.js`:
+
+```js
+/**
+ * buildCtxAttr() export config - the data-ctx payload must carry enough for
+ * the browser to decide whether to offer export, without ever carrying a
+ * field the display did not render.
+ */
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {resolveExportConfig} from '../../server/services/markdown.js';
+
+test('absent schema block defaults to enabled and role-gated', () => {
+    const cfg = resolveExportConfig(undefined, {}, 'subscriber');
+    assert.equal(cfg.allowed, true);
+    assert.equal(cfg.access, 'subscriber');
+    assert.deepEqual(cfg.formats, ['csv', 'json']);
+});
+
+test('enabled:false wins over exportable="true"', () => {
+    const cfg = resolveExportConfig({enabled: false}, {exportable: 'true'}, 'subscriber');
+    assert.equal(cfg.allowed, false);
+});
+
+test('exportable="true" is grandfathered as a public opt-in', () => {
+    const cfg = resolveExportConfig(undefined, {exportable: 'true'}, 'subscriber');
+    assert.equal(cfg.allowed, true);
+    assert.equal(cfg.access, 'public');
+});
+
+test('explicit public access needs no shortcode attribute', () => {
+    const cfg = resolveExportConfig({access: 'public'}, {}, 'subscriber');
+    assert.equal(cfg.access, 'public');
+});
+
+test('formats are honoured and filtered to known values', () => {
+    const cfg = resolveExportConfig({formats: ['csv', 'pdf']}, {}, 'subscriber');
+    assert.deepEqual(cfg.formats, ['csv']);
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `node --test tests/markdown/collection-ctx-export.test.js`
+Expected: FAIL - `resolveExportConfig` is not exported
+
+- [ ] **Step 3: Write the implementation**
+
+In `server/services/markdown.js`, above `buildCtxAttr`:
+
+```js
+const EXPORT_FORMATS = ['csv', 'json'];
+
+/**
+ * Decide whether a display offers export, and to whom. First match wins:
+ *   1. schema export.enabled === false  → never (exportable="true" ignored)
+ *   2. exportable="true" on the shortcode → public (grandfathered: that is
+ *      exactly what the attribute has always meant)
+ *   3. schema export.access             → as configured
+ *   4. otherwise                        → the least-privileged role
+ *
+ * @param {object|undefined} schemaExport - schema.json `export` block
+ * @param {object} attrs                  - shortcode attributes
+ * @param {string} defaultRole            - least-privileged role name
+ */
+export function resolveExportConfig(schemaExport, attrs, defaultRole) {
+    const cfg = schemaExport || {};
+    if (cfg.enabled === false) return {allowed: false, access: null, formats: []};
+    const formats = (Array.isArray(cfg.formats) ? cfg.formats : EXPORT_FORMATS)
+        .filter(f => EXPORT_FORMATS.includes(f));
+    const access = attrs?.exportable === 'true' ? 'public' : (cfg.access || defaultRole);
+    return {allowed: true, access, formats};
+}
+```
+
+Change the `buildCtxAttr` signature and payload:
+
+```js
+function buildCtxAttr(fields, entries, opts = {}) {
+    const names = [...new Set(fields.map(f => f?.name).filter(Boolean))];
+    if (!names.length || !entries.length) return '';
+    const payload = {
+        fields: names.map(n => ({name: n, label: fields.find(f => f.name === n)?.label || n})),
+        entries: entries.map(e => ({
+            id: String(e.id ?? ''),
+            data: Object.fromEntries(names.map(n => [n, e.data?.[n] ?? '']))
+        }))
+    };
+    if (opts.slug) payload.slug = opts.slug;
+    if (opts.export) payload.export = opts.export;
+    return ` data-ctx="${Buffer.from(JSON.stringify(payload), 'utf8').toString('base64')}"`;
+}
+```
+
+### Threading it to the call sites - CORRECTED
+
+The earlier draft of this plan claimed there were 8 call sites and that each "already has `schema`
+and `attrs` in scope". Both claims are false. Verified facts:
+
+**There are 7 call sites of `buildCtxAttr`:** `:289, 508, 535, 566, 604, 666, 759`.
+
+**None of them has `schema` in scope.** They sit inside seven render helpers whose signatures take
+neither `schema` nor `attrs`:
+
+| Line | Enclosing render helper | Signature shape |
+|---|---|---|
+| 289 | `renderCollectionBlocks` (`:257`) | positional |
+| 508 | `renderCollectionCards` (`:483`) | positional |
+| 535 | `renderCollectionList` (`:511`) | positional |
+| 566 | `renderCollectionAccordion` (`:547`) | positional |
+| 604 | `renderCollectionTimeline` (`:587`) | `(entries, opts)` |
+| 666 | `renderCollectionCarousel` (`:632`) | `(entries, opts)` |
+| 759 | `renderCollectionListgroup` (`:719`) | `(entries, opts)` |
+
+**Each helper is called from TWO dispatch sites**, which differ in what they know:
+
+- `renderCollectionFragment(attrs, …)` (`:1281`) - the `[collection]` path. Dispatches at
+  `:1330-1392`. Has `attrs`, and has `schema` from `getCollection(slug)` at `:1305`. Straightforward.
+- `processViewBlocks(markdown, tagSet)` (`:772`) - the `[view]` path. Dispatches at `:843-904`.
+  Has `attrs` and a **view** slug, and loads `viewConfig` via `getView(slug)` at `:821`. It does
+  **not** have the collection schema and must resolve it from the view config before it can
+  compute an export config.
+
+**Approach:** give all seven helpers a trailing optional `ctxOpts = {}` parameter and pass it
+straight through to `buildCtxAttr`. A trailing optional parameter is backwards-compatible, so the
+three `(entries, opts)` helpers do not need their options object reshaped and no existing caller
+breaks. Then compute the config once at each of the two dispatch sites and pass it down.
+
+Resolve `defaultRole` from `userTypes.getRoleHierarchy()` - the entry with the highest level
+number (level 0 is admin, so highest number is least privileged).
+
+For the `[view]` path, resolve the underlying collection schema from `viewConfig` before computing
+the export config. If the view's collection cannot be resolved, fall back to a **closed** config
+(`{allowed: false}`) rather than an open one - failing closed is correct for a permission gate.
+
+**Do not** hoist the export config into a module-level variable. `markdown.js` renders shortcodes recursively, so a `[collection]` nested inside a `[card]` would clobber the outer one's config.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run: `node --test tests/markdown/collection-ctx-export.test.js`
+Expected: PASS, 5 tests
+
+- [ ] **Step 5: Run the display tests for regressions**
+
+Run: `node --test tests/services/collection-displays.test.js`
+Expected: PASS - the payload gained keys but no display markup changed.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add server/services/markdown.js tests/markdown/collection-ctx-export.test.js
+git commit -m "feat(collections): resolve export permission into the ctx payload"
+```
+
+---
+
+## Task 5: Table displays carry export config
+
+**Files:**
+- Modify: `server/services/markdown.js:473-474` (table payload)
+- Modify: `public/js/site.js:764,814-826`
+
+- [ ] **Step 1: Add export config to the table payload**
+
+In `markdown.js` where the table payload object is built (around `:473`), alongside `sortable` and `exportable`:
+
+```js
+        exportCfg: resolveExportConfig(schema.export, attrs, defaultRole),
+        slug: schema.slug,
+```
+
+- [ ] **Step 2: Surface it on the wrapper in site.js**
+
+In `public/js/site.js`, extend the destructure at `:764`:
+
+```js
+      const {columns, rows, search, sortable, exportable, pageSize, empty, ctaConfig, exportCfg, slug} = payload;
+```
+
+and extend the `wrapper._dmTable` object (`:814`) with the two new keys so the context menu can read them:
+
+```js
+      wrapper._dmTable = {
+          columns,
+          rows,
+          slug,
+          exportCfg,
+          render(rowSubset) { /* unchanged */ }
+      };
+```
+
+- [ ] **Step 3: Verify by hand**
+
+Run: `curl -s localhost:4096/<a-page-with-a-table-collection> | grep -o 'data-payload="[^"]\{0,60\}'`
+Then decode one payload and confirm `exportCfg` is present:
+`node -e "console.log(JSON.parse(Buffer.from(process.argv[1],'base64')).exportCfg)" <paste>`
+Expected: an object with `allowed`, `access`, `formats`.
+
+The dev server on port 4096 is always running and does **not** hot-reload. Clear the cache after server-side edits with `POST /api/cache/clear` using a JWT minted from `JWT_SECRET`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add server/services/markdown.js public/js/site.js
+git commit -m "feat(collections): carry export config on table displays"
+```
+
+---
+
+## Task 6: Comparator extraction and sort state
+
+**Files:**
+- Create: `public/js/collection-sort.mjs`
+- Create: `tests/services/collection-sort.test.js`
+- Modify: `server/templates/page.html:120`
+- Modify: `public/js/collection-context.js:80-121`
+
+### Why a separate module, and why the module conversion moves here
+
+The repo has **no jsdom or equivalent** - `tests/services/collection-browser-shell.test.js:8-10`
+records the house convention that DOM behaviour is verified manually, not under `node:test`. Taken
+literally that would ship the sort comparator with zero automated coverage, and the comparator is
+the one piece of this feature that is pure logic with real edge cases: numeric versus date versus
+string ordering, mixed types in one column, empty values.
+
+So the comparator goes in its own `.mjs` - importable by `node:test` exactly as
+`collection-export.mjs` is, and importable by the browser. Everything that touches the DOM stays
+in `collection-context.js` and remains manually verified.
+
+This requires `collection-context.js` to be a module, which the earlier draft deferred to Task 11.
+Doing it here instead means Tasks 6-12 can all import shared pure helpers. The change is the same
+either way - `page.html:120` gains `type="module"` and drops `defer` (module scripts defer by
+default), matching `site.js` (`:119`) and `forms.js` (`:128`), which already do this. The file is
+already an IIFE under `'use strict'`, so nothing else changes.
+
+- [ ] **Step 1: Extract the comparison ladder into a testable module**
+
+The type-detection ladder is currently trapped inside the `gt`/`lt` case of `matches()` (`:92-99`). Lift it out so filtering and sorting share one definition of "which value is larger":
+
+```js
+    /**
+     * Compare two values: numeric if both parse as numbers, then date, then
+     * string. Shared by gt/lt filtering and by sorting, so the two can never
+     * disagree about ordering.
+     */
+    function compareValues(a, b) {
+        const na = parseFloat(a), nb = parseFloat(b);
+        if (!Number.isNaN(na) && !Number.isNaN(nb)) return na - nb;
+        const da = Date.parse(a), db = Date.parse(b);
+        if (!Number.isNaN(da) && !Number.isNaN(db)) return da - db;
+        return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+    }
+```
+
+Rewrite the `gt`/`lt` case to use it:
+
+```js
+            case 'gt':
+            case 'lt': {
+                const c = compareValues(str, f.value);
+                return f.op === 'gt' ? c > 0 : c < 0;
+            }
+```
+
+- [ ] **Step 2: Sort inside apply()**
+
+Replace the first line of `apply()` (`:107`):
+
+```js
+        const sort = wrapper._dmCtxSort || null;
+        let allowedEntries = model.entries.filter(e => filters.every(f => matches(e, f)));
+        if (sort) {
+            allowedEntries = allowedEntries.slice().sort((x, y) => {
+                const c = compareValues(x.data?.[sort.field] ?? '', y.data?.[sort.field] ?? '');
+                return sort.dir === 'desc' ? -c : c;
+            });
+        }
+        const allowed = new Set(allowedEntries.map(e => e.id));
+```
+
+`.slice()` is required - `model.entries` is the pristine source order and clearing the sort must be able to return to it.
+
+Table, timeline and carousel now sort with no further change, because each takes its order from the array it is handed.
+
+- [ ] **Step 3: Verify in a real browser**
+
+Load a page with a `[collection display="table"]`, set `wrapper._dmCtxSort` from the console, call the module's `apply` via a right-click filter, and confirm row order changes. Per project convention, do not record sort as working until a real browser has shown it.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add public/js/collection-context.js
+git commit -m "refactor(collections): extract compareValues; sort filtered entries"
+```
+
+---
+
+## Task 7: Reordering for DOM-toggle displays
+
+Cards, list, listgroup, accordion and block hide in place rather than re-rendering, so they need explicit reordering.
+
+**Files:**
+- Modify: `public/js/collection-context.js` (the `else` branch of `apply()`)
+
+- [ ] **Step 1: Reorder siblings after toggling visibility**
+
+Replace the final `else` branch of `apply()`:
+
+```js
+        } else {
+            const els = Array.from(wrapper.querySelectorAll('[data-entry-id]'));
+            els.forEach(el => el.classList.toggle('dm-ctx-hidden', !allowed.has(el.dataset.entryId)));
+            // Declared at branch level, not inside the `if` below - Task 10's
+            // grouping code appends after the reorder and needs both.
+            const byId = new Map(els.map(el => [el.dataset.entryId, el]));
+            const parent = els.length ? els[0].parentNode : null;
+            if (sort && parent) {
+                // Reorder by appending in sorted order. appendChild MOVES nodes
+                // rather than cloning, so listeners and Domma instance
+                // references on each entry survive intact.
+                allowedEntries.forEach(e => {
+                    const el = byId.get(e.id);
+                    if (el && el.parentNode === parent) parent.appendChild(el);
+                });
+            }
+        }
+```
+
+Entries hidden by filters keep their DOM position; only visible ones are reordered, which is invisible to the user and avoids touching nodes needlessly.
+
+- [ ] **Step 2: Verify in a real browser**
+
+Load a page with `[collection display="cards"]` and `display="accordion"`. Sort, and confirm order changes and accordion panels still open and close - proving listeners survived the move.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add public/js/collection-context.js
+git commit -m "feat(collections): sort DOM-toggle displays by reordering entries"
+```
+
+---
+
+## Task 8: Drill-in panel stack
+
+**Files:**
+- Modify: `public/js/collection-context.js:290-380` (the menu section)
+
+- [ ] **Step 1: Replace single-panel rendering with a stack**
+
+`openMenu()` currently builds one flat panel. Introduce a panel stack so any row can push a
+sub-panel into the same element, needing no hover-intent timers and no flyout collision maths.
+
+**The viewport clamp must be re-run on every panel swap.** An earlier draft of this plan claimed
+the existing clamp was reusable "unchanged". It is not. The clamp (now at `:383-386`, after Task 6
+shifted the file) measures `getBoundingClientRect()` once, immediately after the menu is first
+appended to the body. A drill-in changes the panel's height - the Sort panel renders two rows per
+field and is typically the tallest - so a menu opened near the bottom of the viewport would
+overflow off-screen with no correction.
+
+Extract the clamp into a helper and call it after every `renderPanel`, retaining the original
+click coordinates so the menu keeps its anchor rather than drifting across the screen:
+
+```js
+    function clamp(menu, x, y) {
+        const r = menu.getBoundingClientRect();
+        menu.style.left = Math.min(x, window.innerWidth - r.width - 8) + 'px';
+        menu.style.top = Math.min(y, window.innerHeight - r.height - 8) + 'px';
+    }
+```
+
+Store `x`/`y` on the menu element when it opens so `renderPanel` can re-clamp without threading
+coordinates through every push and pop.
+
+```js
+    // Panel stack - a menu is a list of builder functions. Pushing renders a
+    // new panel into the SAME element, so positioning and the outside-click
+    // handlers are set up once and never recomputed.
+    function renderPanel(menu, build, title) {
+        menu.replaceChildren();
+        if (title) {
+            const back = document.createElement('button');
+            back.type = 'button';
+            back.className = 'dm-ctx-row dm-ctx-back';
+            back.textContent = '‹ Back';
+            back.addEventListener('click', () => menu._dmPop());
+            const head = document.createElement('div');
+            head.className = 'dm-ctx-panel-head';
+            head.appendChild(back);
+            head.appendChild(heading(title));
+            menu.appendChild(head);
+        }
+        build(menu);
+    }
+
+    function makeStack(menu) {
+        const stack = [];
+        menu._dmPush = (build, title) => {
+            stack.push({build, title});
+            renderPanel(menu, build, title);
+        };
+        menu._dmPop = () => {
+            stack.pop();
+            const prev = stack[stack.length - 1];
+            if (prev) renderPanel(menu, prev.build, prev.title);
+        };
+        return menu;
+    }
+```
+
+- [ ] **Step 2: Add the panel-head styles**
+
+Append to the injected `style.textContent` array:
+
+```js
+        '.dm-ctx-panel-head { display: flex; align-items: center; justify-content: space-between; gap: .5rem;'
+            + 'border-bottom: 1px solid var(--dm-border, #2a2a40); margin-bottom: .25rem; }',
+        '.dm-ctx-menu button.dm-ctx-back { width: auto; padding: .3rem .5rem; color: var(--dm-text-muted, #9a9aac); }',
+        '.dm-ctx-group-heading { font-size: .75rem; text-transform: uppercase; letter-spacing: .04em;'
+            + 'color: var(--dm-text-muted, #9a9aac); padding: .5rem 0 .25rem; grid-column: 1 / -1; }',
+```
+
+`grid-column: 1 / -1` matters: card displays render into a Domma Grid, so a heading must span every column or it will sit in a cell.
+
+Note this puts the group-heading rule in the injected stylesheet rather than `public/css/site.css`
+as the spec's file table suggested. Deliberate: every other context-menu style is injected here, and
+splitting them across two files would mean editing both for one visual change. The print stylesheet
+stays in `site.css` (Task 12), because print rules target the page, not the menu.
+
+- [ ] **Step 3: Convert openMenu to push a root panel**
+
+Wrap the existing body of `openMenu` in a root builder and push it:
+
+```js
+        const menu = makeStack(document.createElement('div'));
+        menu.className = 'dm-ctx-menu';
+        _menu = menu;
+        menu._dmPush(m => buildRootPanel(m, wrapper, entry, clickedField, model), null);
+```
+
+Move the existing filter rows and the search input into `buildRootPanel(menu, wrapper, entry, clickedField, model)` unchanged. The search input keeps its autofocus, and filter stays one click.
+
+- [ ] **Step 4: Verify in a real browser**
+
+Right-click a collection: the existing filter rows and search must behave exactly as before. This task is a refactor with no user-visible change.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add public/js/collection-context.js
+git commit -m "refactor(collections): drill-in panel stack for the context menu"
+```
+
+---
+
+## Task 9: The Sort panel
+
+**Files:**
+- Modify: `public/js/collection-context.js`
+
+- [ ] **Step 1: Add a type-aware direction labeller**
+
+```js
+    /** Direction wording follows the detected value type. */
+    function dirLabels(model, field) {
+        const sample = model.entries.map(e => e.data?.[field]).find(v => v !== '' && v != null);
+        const s = String(sample ?? '');
+        if (s !== '' && !Number.isNaN(parseFloat(s))) return ['low → high', 'high → low'];
+        if (!Number.isNaN(Date.parse(s))) return ['oldest → newest', 'newest → oldest'];
+        return ['A → Z', 'Z → A'];
+    }
+```
+
+- [ ] **Step 2: Build the panel**
+
+```js
+    function buildSortPanel(menu, wrapper, model) {
+        model.fields.forEach(f => {
+            const [asc, desc] = dirLabels(model, f.name);
+            menu.appendChild(row(`${f.label || f.name}   ${asc}`, () => {
+                wrapper._dmCtxSort = {field: f.name, label: f.label || f.name, dir: 'asc'};
+                apply(wrapper);
+                closeMenu();
+            }));
+            menu.appendChild(row(`${f.label || f.name}   ${desc}`, () => {
+                wrapper._dmCtxSort = {field: f.name, label: f.label || f.name, dir: 'desc'};
+                apply(wrapper);
+                closeMenu();
+            }));
+        });
+        if (wrapper._dmCtxSort) {
+            menu.appendChild(row('Clear sort', () => {
+                wrapper._dmCtxSort = null;
+                apply(wrapper);
+                closeMenu();
+            }));
+        }
+    }
+```
+
+- [ ] **Step 3: Add the root-panel row**
+
+In `buildRootPanel`, in the display-scoped block:
+
+```js
+        menu.appendChild(row('Sort…', () => menu._dmPush(m => buildSortPanel(m, wrapper, model), 'Sort')));
+```
+
+- [ ] **Step 4: Verify in a real browser**
+
+Right-click each of the eight display types, drill into Sort, apply ascending and descending, then Clear sort and confirm the original order returns.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add public/js/collection-context.js
+git commit -m "feat(collections): sort panel in the right-click menu"
+```
+
+---
+
+## Task 10: Grouping (DOM-toggle displays only)
+
+**Files:**
+- Modify: `public/js/collection-context.js`
+
+- [ ] **Step 1: Add a strategy predicate**
+
+Grouping needs entries as siblings with room for a heading between them. Table fights `T.create`'s pagination, `Progression.setItems()` takes items rather than headers, and grouped carousel slides are not meaningful.
+
+```js
+    /** True when the display filters by toggling [data-entry-id] siblings. */
+    function isDomToggle(wrapper) {
+        return !wrapper._dmTable && !wrapper._dmCtx?.instance?.setItems && !wrapper._dmCtxSlides;
+    }
+```
+
+- [ ] **Step 2: Insert headings during apply()**
+
+Inside the reorder branch added in Task 7, after the reorder loop:
+
+```js
+            wrapper.querySelectorAll('.dm-ctx-group-heading').forEach(h => h.remove());
+            const group = wrapper._dmCtxGroup;
+            if (group) {
+                let last = null;
+                allowedEntries.forEach(e => {
+                    const val = String(e.data?.[group] ?? '') || '-';
+                    if (val === last) return;
+                    last = val;
+                    const h = document.createElement('div');
+                    h.className = 'dm-ctx-group-heading';
+                    h.textContent = val;
+                    const el = byId.get(e.id);
+                    if (el) parent.insertBefore(h, el);
+                });
+            }
+```
+
+Headings are rebuilt from scratch on every `apply()` - cheaper to reason about than diffing, and the entry counts here are page-sized.
+
+- [ ] **Step 3: Build the panel and gate the row**
+
+```js
+    function buildGroupPanel(menu, wrapper, model) {
+        model.fields.forEach(f => {
+            menu.appendChild(row(f.label || f.name, () => {
+                wrapper._dmCtxGroup = f.name;
+                // Grouping implies a primary sort by the group field.
+                if (!wrapper._dmCtxSort || wrapper._dmCtxSort.field !== f.name) {
+                    wrapper._dmCtxSort = {field: f.name, label: f.label || f.name, dir: 'asc'};
+                }
+                apply(wrapper);
+                closeMenu();
+            }));
+        });
+        if (wrapper._dmCtxGroup) {
+            menu.appendChild(row('Clear grouping', () => {
+                wrapper._dmCtxGroup = null;
+                apply(wrapper);
+                closeMenu();
+            }));
+        }
+    }
+```
+
+In `buildRootPanel`, render the row only where it can work - hidden, not disabled, because a greyed row invites "why?" on every open:
+
+```js
+        if (isDomToggle(wrapper)) {
+            menu.appendChild(row('Group by…', () => menu._dmPush(m => buildGroupPanel(m, wrapper, model), 'Group by')));
+        }
+```
+
+- [ ] **Step 4: Verify in a real browser**
+
+Confirm headings appear on cards, list, listgroup, accordion and block; confirm the `Group by…` row is absent on table, timeline and carousel; confirm a card-grid heading spans the full grid width.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add public/js/collection-context.js
+git commit -m "feat(collections): group-by for sibling-rendered displays"
+```
+
+---
+
+## Task 11: Export, copy, and the client-side gate
+
+**Files:**
+- Modify: `public/js/collection-context.js`
+- Modify: `server/templates/page.html:120`
+
+- [ ] **Step 1: Make the context menu a module**
+
+`collection-context.js` must `import` the serialiser, so it can no longer be a classic script. In `server/templates/page.html:120`:
+
+```html
+    <script src="/public/js/collection-context.js?v=20260819-sort-export" type="module"></script>
+```
+
+`defer` is dropped because module scripts defer by default. `site.js` (`:119`) and `forms.js` (`:128`) already use this exact form. Add the import at the top of `collection-context.js`, above the IIFE:
+
+```js
+import {serialise} from '/public/js/collection-export.mjs';
+```
+
+- [ ] **Step 2: Add the sinks**
+
+```js
+    function download(text, filename, mime) {
+        const url = URL.createObjectURL(new Blob([text], {type: mime}));
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        a.remove();
+        setTimeout(() => URL.revokeObjectURL(url), 0);
+    }
+
+    /**
+     * Copy via a throwaway textarea, NOT navigator.clipboard.
+     *
+     * navigator.clipboard exists only in a secure context - HTTPS or localhost.
+     * config/server.json binds 0.0.0.0 and this CMS is routinely reached over
+     * plain HTTP on a LAN address, where navigator.clipboard is `undefined` and
+     * every copy would throw TypeError. This mirrors the existing house
+     * fallback at admin/js/lib/crud-tutorial.js:119-129, whose comment records
+     * the same reasoning.
+     */
+    function toClipboard(text, note) {
+        const ta = document.createElement('textarea');
+        ta.value = text;
+        ta.style.cssText = 'position:fixed;opacity:0;';
+        document.body.appendChild(ta);
+        ta.select();
+        const ok = document.execCommand('copy');
+        ta.remove();
+        if (typeof E !== 'undefined' && E.toast) {
+            E.toast(ok ? note : 'Copy failed', {type: ok ? 'success' : 'error'});
+        }
+    }
+
+    /** ISO date without the time part, for filenames. */
+    function stamp() { return new Date().toISOString().slice(0, 10); }
+```
+
+- [ ] **Step 3: Add the gate**
+
+```js
+    // One lookup per page, cached. The dataset already ships inside data-ctx,
+    // so this gate stops a casual visitor being handed a download button - it
+    // is not, and is not documented as, an enforcement boundary.
+    //
+    // Auth is a Bearer token from Domma storage, NOT a cookie: @fastify/cookie
+    // is not registered and @fastify/jwt is registered with only {secret}
+    // (server/server.js:98), so request.jwtVerify() reads the Authorization
+    // header and nothing else. `credentials: 'same-origin'` would send no
+    // credential at all and every visitor would look anonymous.
+    // This mirrors the established public-site idiom at site.js:582 and
+    // collection-browser.js:944.
+    let _mePromise = null;
+    function currentUser() {
+        if (!_mePromise) {
+            const token = (typeof S !== 'undefined' && S.get) ? S.get('auth_token') : null;
+            // No token means anonymous - skip the request entirely.
+            _mePromise = token
+                ? fetch('/api/auth/me', {headers: {Authorization: `Bearer ${token}`}})
+                    .then(r => r.ok ? r.json() : null)
+                    .catch(() => null)
+                : Promise.resolve(null);
+        }
+        return _mePromise;
+    }
+
+    async function exportAllowed(cfg) {
+        if (!cfg || !cfg.allowed) return false;
+        if (cfg.access === 'public') return true;
+        return Boolean(await currentUser());
+    }
+```
+
+- [ ] **Step 4: Build the Export and Copy panels**
+
+```js
+    function visibleRows(wrapper, model) {
+        const filters = wrapper._dmCtxFilters || [];
+        let rows = model.entries.filter(e => filters.every(f => matches(e, f)));
+        const sort = wrapper._dmCtxSort;
+        if (sort) {
+            rows = rows.slice().sort((x, y) => {
+                const c = compareValues(x.data?.[sort.field] ?? '', y.data?.[sort.field] ?? '');
+                return sort.dir === 'desc' ? -c : c;
+            });
+        }
+        return rows.map(e => e.data);
+    }
+
+    function buildExportPanel(menu, wrapper, model, cfg) {
+        const slug = model.slug || wrapper._dmTable?.slug || 'collection';
+        cfg.formats.forEach(fmt => {
+            menu.appendChild(row(fmt.toUpperCase(), () => {
+                const text = serialise(visibleRows(wrapper, model), model.fields, fmt);
+                download(text, `${slug}-${stamp()}.${fmt}`,
+                    fmt === 'csv' ? 'text/csv;charset=utf-8' : 'application/json');
+                closeMenu();
+            }));
+        });
+    }
+
+    function buildCopyPanel(menu, wrapper, model, entry, clickedField) {
+        if (entry && clickedField) {
+            menu.appendChild(row('This value', () => {
+                toClipboard(String(entry.data?.[clickedField.name] ?? ''), 'Value copied');
+                closeMenu();
+            }));
+        }
+        if (entry) {
+            menu.appendChild(row('This row (JSON)', () => {
+                toClipboard(serialise([entry.data], model.fields, 'json'), 'Row copied');
+                closeMenu();
+            }));
+        }
+        menu.appendChild(row('Visible entries as a table', () => {
+            toClipboard(serialise(visibleRows(wrapper, model), model.fields, 'markdown'), 'Table copied');
+            closeMenu();
+        }));
+    }
+```
+
+- [ ] **Step 5: Add the root rows**
+
+In `buildRootPanel`'s display-scoped block:
+
+```js
+        menu.appendChild(row('Copy…', () =>
+            menu._dmPush(m => buildCopyPanel(m, wrapper, model, entry, clickedField), 'Copy')));
+
+        const cfg = model.export || wrapper._dmTable?.exportCfg;
+        exportAllowed(cfg).then(ok => {
+            if (!ok || _menu !== menu) return;
+            menu.appendChild(row('Export…', () =>
+                menu._dmPush(m => buildExportPanel(m, wrapper, model, cfg), 'Export')));
+        });
+```
+
+The `_menu !== menu` guard matters: the fetch resolves asynchronously, and without it a slow response would append a row to a menu the user already closed.
+
+- [ ] **Step 6: Verify in a real browser**
+
+Signed out, confirm no Export row on a default-config collection. Sign in, reload, confirm it appears. Export CSV and open the file in a spreadsheet: check accented characters render (BOM working) and that a value beginning `=` appears as text rather than a formula. Confirm Copy rows land on the clipboard.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add public/js/collection-context.js server/templates/page.html
+git commit -m "feat(collections): export and copy from the right-click menu"
+```
+
+---
+
+## Task 12: Print, copy-link, and URL state
+
+**Files:**
+- Modify: `public/js/collection-context.js`
+- Modify: `public/css/site.css`
+
+- [ ] **Step 1: Add the print stylesheet**
+
+Append to `public/css/site.css`:
+
+```css
+/* Right-click "Print" - isolate one collection display for printing.
+   body * hidden, then the marked subtree walked back to visible. */
+@media print {
+    body.dm-ctx-printing * { visibility: hidden; }
+    body.dm-ctx-printing [data-dm-print],
+    body.dm-ctx-printing [data-dm-print] * { visibility: visible; }
+    body.dm-ctx-printing [data-dm-print] {
+        position: absolute; left: 0; top: 0; width: 100%;
+    }
+    /* Closed accordions would otherwise print as a stack of bare headers.
+       The collapsible region is .accordion-content - verified against both the
+       markup markdown.js emits (renderCollectionAccordion, :547) and the class
+       list in the Domma bundle. There is no .accordion-panel; an earlier draft
+       of this plan targeted that name and would have silently done nothing. */
+    body.dm-ctx-printing [data-dm-print] .accordion-content { display: block !important; height: auto !important; }
+    body.dm-ctx-printing .dm-ctx-hidden { display: none !important; }
+}
+```
+
+- [ ] **Step 2: Add the print and copy-link rows**
+
+```js
+        menu.appendChild(row('Print', () => {
+            wrapper.setAttribute('data-dm-print', '');
+            document.body.classList.add('dm-ctx-printing');
+            closeMenu();
+            const cleanup = () => {
+                wrapper.removeAttribute('data-dm-print');
+                document.body.classList.remove('dm-ctx-printing');
+                window.removeEventListener('afterprint', cleanup);
+            };
+            window.addEventListener('afterprint', cleanup);
+            window.print();
+        }));
+
+        menu.appendChild(row('Copy link to this view', () => {
+            syncHash();
+            toClipboard(location.href, 'Link copied');
+            closeMenu();
+        }));
+```
+
+- [ ] **Step 3: Extend the hash payload**
+
+`syncHash()` currently stores a bare filter array per display index. Store an object instead:
+
+```js
+    function syncHash() {
+        const state = {};
+        allWrappers().forEach((w, i) => {
+            const entry = {};
+            if (w._dmCtxFilters && w._dmCtxFilters.length) entry.f = w._dmCtxFilters;
+            if (w._dmCtxSort) entry.s = w._dmCtxSort;
+            if (w._dmCtxGroup) entry.g = w._dmCtxGroup;
+            if (Object.keys(entry).length) state[i] = entry;
+        });
+        /* …rest unchanged… */
+    }
+```
+
+And read both shapes in `restoreFromHash()`, so links shared before this change keep working:
+
+```js
+        for (const [idx, raw] of Object.entries(state)) {
+            const w = wrappers[Number(idx)];
+            // Legacy links stored a bare filter array; current ones store {f,s,g}.
+            const cfg = Array.isArray(raw) ? {f: raw} : (raw || {});
+            if (!w) continue;
+            /* …hydration check unchanged… */
+            w._dmCtxFilters = (cfg.f || []).filter(f => f && f.field && f.op != null && 'value' in f);
+            w._dmCtxSort = cfg.s || null;
+            w._dmCtxGroup = cfg.g || null;
+            apply(w);
+        }
+```
+
+Note the `pending` guard above this loop must also stop skipping wrappers with no filters, since a display may now carry only a sort.
+
+- [ ] **Step 4: Verify in a real browser**
+
+Apply a filter, sort and group; copy the link; open it in a fresh tab and confirm all three restore. Take a `dmf=` link generated before this change and confirm it still restores its filters. Print and confirm only the display appears.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add public/js/collection-context.js public/css/site.css
+git commit -m "feat(collections): print, copy-link, and sort/group in the URL hash"
+```
+
+---
+
+## Task 13: Admin UI for the export block
+
+**Files:**
+- Modify: `admin/js/templates/collection-editor.html:17`
+- Modify: `admin/js/views/collection-editor.js:218-249, 297-305, 432, 463, 480`
+
+This file is one of seven admin views committed with mangled identifiers (see the spec). **Write new code with readable names** - a file that is 5% legible beats one that is 0%. Do not attempt to restore the file here; that is a separate task.
+
+- [ ] **Step 1: Rename the tab**
+
+In `admin/js/templates/collection-editor.html:17`:
+
+```html
+        <button class="tab-item">API &amp; Export</button>
+```
+
+- [ ] **Step 2: Render the export rows**
+
+At the end of the function that renders `#api-access-rows` (`:218-249`), after the verb loop:
+
+```js
+    // Export row - schema-level permission for the public right-click export.
+    // Mirrors the verb rows above; the Formats sub-row follows the existing
+    // "Read fields" sub-row precedent.
+    const exportCfg = schemaExport || {};
+    const exportRow = document.createElement('div');
+    exportRow.style.cssText = 'display:grid;grid-template-columns:140px 1fr 160px;gap:.75rem;align-items:center;padding:.6rem 0;border-top:2px solid var(--dm-border,#333);';
+    const exportLabel = document.createElement('strong');
+    exportLabel.textContent = 'Export';
+    exportLabel.style.cssText = 'font-size:.9rem;';
+    const exportToggle = document.createElement('label');
+    exportToggle.style.cssText = 'display:flex;align-items:center;gap:.45rem;cursor:pointer;font-size:.875rem;';
+    const exportEnabled = document.createElement('input');
+    exportEnabled.type = 'checkbox';
+    exportEnabled.id = 'export-enabled';
+    exportEnabled.checked = exportCfg.enabled !== false;
+    exportToggle.appendChild(exportEnabled);
+    exportToggle.appendChild(document.createTextNode('Allow export'));
+    const exportAccess = document.createElement('select');
+    exportAccess.id = 'export-access';
+    exportAccess.className = 'form-input';
+    // `ae` (collection-editor.js:45) is the API access list and includes
+    // "token". An API token is a machine credential for /api/v1 - it is
+    // meaningless for a browser download, and the spec forbids it here. Filter
+    // it out rather than reusing `ae` wholesale.
+    ae.filter(roleName => roleName !== 'token').forEach(roleName => {
+        const opt = document.createElement('option');
+        opt.value = roleName;
+        opt.textContent = roleName.charAt(0).toUpperCase() + roleName.slice(1);
+        if (roleName === exportCfg.access) opt.selected = true;
+        exportAccess.appendChild(opt);
+    });
+    exportRow.appendChild(exportLabel);
+    exportRow.appendChild(exportToggle);
+    exportRow.appendChild(exportAccess);
+    t.appendChild(exportRow);
+
+    const formatsRow = document.createElement('div');
+    formatsRow.style.cssText = 'display:grid;grid-template-columns:140px 1fr;gap:.75rem;align-items:center;padding:.6rem 0;border-bottom:1px solid var(--dm-border,#333);';
+    const formatsLabel = document.createElement('label');
+    formatsLabel.style.cssText = 'font-size:.85rem;color:var(--dm-text-muted,#aaa);';
+    formatsLabel.textContent = 'Formats';
+    const formatsWrap = document.createElement('div');
+    formatsWrap.style.cssText = 'display:flex;gap:1rem;';
+    const chosenFormats = Array.isArray(exportCfg.formats) ? exportCfg.formats : ['csv', 'json'];
+    ['csv', 'json'].forEach(fmt => {
+        const wrap = document.createElement('label');
+        wrap.style.cssText = 'display:flex;align-items:center;gap:.35rem;cursor:pointer;font-size:.875rem;';
+        const box = document.createElement('input');
+        box.type = 'checkbox';
+        box.id = `export-format-${fmt}`;
+        box.checked = chosenFormats.includes(fmt);
+        wrap.appendChild(box);
+        wrap.appendChild(document.createTextNode(fmt.toUpperCase()));
+        formatsWrap.appendChild(wrap);
+    });
+    formatsRow.appendChild(formatsLabel);
+    formatsRow.appendChild(formatsWrap);
+    t.appendChild(formatsRow);
+```
+
+**Verified identifiers in this mangled file:** `ae` (`:45`) is
+`["public","token","subscriber","editor","manager","admin"]`; `ee` (`:46`) is
+`["create","read","update","delete"]`; the render function is `se(e, t)` at `:217`, called from
+`:380`; `t` is the rows container and `e` the existing `api` block. Pass the loaded schema's
+`export` block in as a third parameter `schemaExport`.
+
+- [ ] **Step 3: Read the values on save**
+
+Beside `readApiRows()` (`:297-305`):
+
+```js
+/** Read the export block back out of the API & Export tab. */
+function readExportBlock() {
+    const formats = ['csv', 'json'].filter(fmt => document.getElementById(`export-format-${fmt}`)?.checked);
+    return {
+        enabled: document.getElementById('export-enabled')?.checked ?? true,
+        access: document.getElementById('export-access')?.value || 'subscriber',
+        formats
+    };
+}
+```
+
+- [ ] **Step 4: Include it in the three save paths**
+
+At `:432`, `:463` and `:480`, where the payload currently carries `api: b`, add:
+
+```js
+                        export: readExportBlock(),
+```
+
+- [ ] **Step 5: Load it when editing an existing collection**
+
+At `:373`, where `r = l.api || r` restores the API block, add alongside:
+
+```js
+            schemaExport = l.export || {},
+```
+
+and pass it into the render function.
+
+- [ ] **Step 6: Verify in a real browser**
+
+Open a collection in the admin, go to API & Export, untick CSV, save, reload, confirm the tick state persisted. Check the written `schema.json` on disk contains the `export` block.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add admin/js/templates/collection-editor.html admin/js/views/collection-editor.js
+git commit -m "feat(admin): export permission controls in the collection editor"
+```
+
+---
+
+## Task 14: Documentation
+
+**Files:**
+- Modify: `docs/configuration.md`
+- Modify: `docs/markdown-shortcodes.md`
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 1: Document the schema block**
+
+Add to `docs/configuration.md`, beside the `api` block reference:
+
+```markdown
+### `export` (collection schema)
+
+Controls the public right-click export menu.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | `false` disables export entirely and overrides `exportable="true"` |
+| `access` | least-privileged role | `"public"`, or a role name |
+| `formats` | `["csv", "json"]` | Offered download formats |
+
+`[collection exportable="true"]` is treated as an explicit public opt-in for that placement,
+preserving the behaviour that attribute has always had.
+
+**This gate is a convenience affordance, not an enforcement boundary.** Collection entries are
+already embedded in the rendered page's `data-ctx` attribute so the browser can filter them
+without a round trip. Restricting `access` stops a visitor being handed a download button; it
+does not stop a determined one reading the page source. Collections whose contents must not
+reach a visitor at all should not be rendered on a page that visitor can load - set
+`page.visibility`, or gate the collection's `api.read.access`.
+```
+
+- [ ] **Step 2: Document the menu's per-display capabilities**
+
+Add to `docs/markdown-shortcodes.md`, in the collection display section:
+
+```markdown
+#### Right-click menu capabilities by display type
+
+| Display | Filter | Sort | Group | Export / copy |
+|---|---|---|---|---|
+| cards, list, listgroup, accordion, block | ✅ | ✅ | ✅ | ✅ |
+| table | ✅ | ✅ | - | ✅ |
+| timeline | ✅ | ✅ | - | ✅ |
+| carousel | ✅ | ✅ | - | ✅ |
+
+Grouping needs entries rendered as siblings with room for a heading between them. Table
+displays are re-rendered by `T.create` (heading rows would fight its pagination), timelines
+are driven by `Progression.setItems()` which accepts items rather than section headers, and
+carousel slides are a sequence. The `Group by…` row is hidden on those three.
+```
+
+- [ ] **Step 3: Update the project guide**
+
+In `CLAUDE.md`, extend the "Collection displays & public filtering" section to note that the
+menu now also sorts, groups, exports and copies, that export permission lives in the schema's
+`export` block, and that `public/js/collection-export.mjs` is shared with the server.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/configuration.md docs/markdown-shortcodes.md CLAUDE.md
+git commit -m "docs: collection export permissions and menu capabilities"
+```
+
+---
+
+## Task 15: Full verification
+
+- [ ] **Step 1: Run the whole suite**
+
+Run: `npm test`
+Expected: PASS, with the three new test files included.
+
+- [ ] **Step 2: Clear the dev server cache**
+
+The port-4096 dev server is always running and does not hot-reload. Mint a JWT from `JWT_SECRET` and `POST /api/cache/clear`. Never start or kill that server.
+
+- [ ] **Step 3: Browser pass**
+
+Walk one page carrying all eight display types:
+
+- Filter still applies in one click; search still autofocuses.
+- Sort works on all eight; Clear sort restores source order.
+- Group by is offered on five, hidden on three; card headings span the grid.
+- Export absent signed out, present signed in; CSV opens cleanly in a spreadsheet with accents intact and formula-leading values inert.
+- Copy value, copy row, copy table all reach the clipboard.
+- Print shows only the display, with accordions expanded.
+- A link copied from the menu restores filter + sort + group in a fresh tab.
+- A pre-existing `dmf=` link still restores its filters.
+- Long-press on a touch device opens the menu and Back works.
+
+- [ ] **Step 4: Confirm the admin round-trip**
+
+Set `export.enabled = false` on a collection, save, reload the public page, and confirm the Export row is gone even with `exportable="true"` on the shortcode.
+
+- [ ] **Step 5: Final commit**
+
+**Never `git add -A` in this repo.** Running `npm test` boots the server, which calls
+`seedCoreProject()` and rewrites `updatedAt` timestamps in
+`content/collections/projects/data.json` on every single run. `git add -A` would sweep that
+churn into the commit. Stage explicit paths only:
+
+```bash
+git status --porcelain          # confirm nothing unexpected
+git checkout -- content/collections/projects/data.json   # discard test-run churn
+git add <the specific files this task changed>
+git commit -m "feat(collections): sort, group, export and copy in the right-click menu"
+```