orz-paged 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# orz-paged
+
+> **Status: built and browser-verified** — 12 starter templates, 7 light themes,
+> the full document-element set, an in-file editor with a template picker, and a
+> dynamic switch (e.g. exam answer keys). **Not yet published to npm**, so use it
+> from a local checkout: `npm install`, `npm run build`, then
+> `npm run gen -- tests/sample.md` produces a working `.paged.html`. See
+> [DESIGN.md](./DESIGN.md) for the design.
+
+Generate a single, self-contained, **editable** `.paged.html` from Markdown — a
+document shown as **print pages** in any browser (A4/Letter, real margins,
+running headers/footers, page numbers), edited and saved **in the browser**, and
+exported to PDF by **printing it** (no PDF binary, no Puppeteer).
+
+It is the paginated-document sibling of:
+
+- **[orz-mdhtml](../orz-mdhtml)** — a continuous document (`.md.html`)
+- **[orz-slides](../orz-slides)** — a reveal.js deck (`.slides.html`)
+
+and is authored in **[orz-markdown](../orz-markdown)**, the family's parser.
+
+## How it differs from `.md.pdf`
+
+The **orz-md-pdf** VS Code extension produces a `.md.pdf`: a real PDF binary with
+the Markdown embedded inside, rendered by Puppeteer. **orz-paged keeps the file as
+editable HTML** in a paged view; a PDF is produced only on demand, by the
+browser's own `Print → Save as PDF`. It borrows orz-md-pdf's *document model* (as
+a spec, reimplemented in TypeScript) and its paged.js pagination — not its PDF
+binary, Puppeteer, or untested code.
+
+## Principles
+
+- **Print on light paper.** White or light-colored backgrounds only — **no dark
+  mode**, no screen-only constructs (avoid tabs, spoilers, embedded video).
+- **Assume internet.** Fonts, web images, and math/diagram libraries load from
+  CDN at view/print time; files stay small.
+- **Curated, not sprawling.** A dozen common templates + seven light themes (shared
+  with the orz family) + a clear agent skill, rather than every option — but every
+  element/theme/setting stays independently composable for power users and agents.
+
+## Pipeline (all in the browser)
+
+```
+Markdown ──orz-markdown──► content HTML
+         ──pipeline-model─► paged HTML (page config, headers/footers, elements, fonts, theme)
+         ──paged.js───────► .pagedjs_page boxes  (the visible pages — and what prints)
+```
+
+## Commands
+
+```
+orz-paged <input.md> [-o out.paged.html] [--inline | --cdn] [--title t]
+orz-paged --template <name> [-o out.paged.html]   # scaffold + render a starter document
+orz-paged --new <name> [-o out.md]                # write a starter .md you then edit
+orz-paged --list-templates                        # list the templates
+```
+
+`--inline` (default) embeds the engine + paged.js + every theme. `--cdn` instead
+references jsDelivr for the engine + theme — but that needs `orz-paged-browser`
+published, so **while orz-paged is unpublished, use the default `--inline`**.
+**Fonts, web images, and math/diagram libraries always load from CDN** (internet
+assumed) — so files stay small. The document's `{{nyml kind: document}}` block
+(`template:`, `theme:`, …) is the source of truth.
+
+## Templates & themes
+
+**Clear split:** a **template owns layout** (page size, furniture, which elements
+appear and where) and a **theme owns the look** (font, decoration color, element
+styling) — so the same theme renders the same across every template.
+
+Twelve starter **templates** scaffold a real document, not just defaults —
+`article`, `report`, and `exam` each in a **title-page** and a **title-section**
+variant, three CV styles (`cv` classic, `cv-modern`, `cv-elegant`), plus
+`letter`, `cover-letter`, and `note`. Pick one with `--template <name>`, or in the
+in-file editor from the **template picker** (the 📄 toolbar button); the picker
+drops the starter into the editor (keeping any existing content in a comment).
+
+Seven light **themes** are vendored from orz-markdown and print-adapted —
+`light-neat-1/2/3`, `light-academic-1/2`, `beige-decent-1/2` — selectable per
+document (`theme:`) or live in the editor (switching swaps font + color + style
+together). The **default is `light-academic-1`**. They are **light only by design**
+(ink on paper); an explicit `font_preset` / `decoration_color` / `page_background`
+still overrides a theme's font / accent / page tint.
+
+## Dynamic switch — one source, several versions
+
+A `dynamic_choices` document setting (a `key: value` map) drives conditional
+content: elements tagged `data-show-when="key=value"` / `data-hide-when="key=value"`
+are kept or dropped at render time. The headline use is **exam answer keys** — the
+question answers are tagged `answer-key=show`, so one source prints both the
+student copy (`answer-key: hide`) and the instructor key (`show`). Flip it in the
+source, or live from the editor's **answer key** dropdown. Define your own keys for
+any tailored-variant document.
+
+## Authoring
+
+A `{{nyml kind: document}}` block sets page size/margins, font, headers/footers,
+page numbers, and a template/theme; `{{nyml kind: element}}` blocks insert
+constructs like title sections, abstracts, letterheads, TOCs, CV headers, and exam
+questions. orz-paged ships a **curated** subset of this model (the most common
+templates/elements) with a clear agent skill — see
+[DESIGN.md §8](./DESIGN.md). The full model orz-paged draws from is in
+[docs/document-model.md](docs/document-model.md) (a spec reference from
+orz-md-pdf).
+
+## Use with an AI agent
+
+The package ships an **agent skill** that teaches an AI agent the document format —
+page templates, headers/footers, the curated elements (CVs, letters, exams), and
+the dynamic switch. The quickest way to produce a document is to let an agent do it:
+
+- **Claude Code** — copy `orz-paged-skills/` into `~/.claude/skills/orz-paged/`.
+- **Any agent** — point it at the local `orz-paged-skills/SKILL.md`, then describe
+  what you want.
+
+Once orz-paged is published to npm, the skill will also be loadable from jsDelivr
+(`https://cdn.jsdelivr.net/npm/orz-paged/orz-paged-skills/SKILL.md`), like the other
+orz tools. More install routes: <https://markdown.orz.how/agents.html>
+
+## Security — treat these as programs, not documents
+
+A `.paged.html` is **self-contained executable HTML**: opening one runs the
+JavaScript embedded in it (the engine, the editor, and — because the parser allows
+raw HTML in the source — potentially anything in the content). The trust model is
+the same as **running a downloaded program**, not opening a PDF.
+
+- **Only open or edit files from sources you trust.** Anyone can craft a file that
+  looks authentic (same chrome, logo, layout) but contains hostile code. The
+  format has no built-in authenticity — appearance proves nothing.
+- **What the browser limits.** A page can't run native code or read your disk
+  silently (Save uses the File System Access prompt and is scoped to the file you
+  pick). Realistic harm from a hostile file is web-context — phishing, exfiltrating
+  what you type or paste, beaconing — within the browser sandbox.
+- **The one-click update is opt-in and fixed-source.** It only checks for and
+  fetches a new framework after you enter edit mode and click **Update**, always
+  from the canonical jsDelivr packages over HTTPS (the source is hardcoded in the
+  engine — a tampered file cannot redirect it), and it shows the exact URLs for
+  confirmation first. Clicking Update places trust in npm + jsDelivr for those
+  packages.
+- **Integrity can't be self-verified.** A file cannot prove its own integrity (a
+  forgery would just lie). If you need authenticity, verify it out-of-band — a
+  checksum or signature from the publisher over a trusted channel.
+
+## License
+
+TBD.

package/assets/app.js

@@ -0,0 +1,413 @@
+/* orz-paged in-file editor (A4). Plain browser JS, inlined into every
+ * .paged.html. The rendered pages are the live preview: editing re-assembles +
+ * re-paginates them (debounced). Save is self-reproducing — it serializes the
+ * whole document with the edited source baked back into #orz-src, stripping
+ * runtime-injected nodes ([data-orz-runtime]) and the rendered pages so the saved
+ * file re-renders cleanly on next open. Ported in spirit from orz-mdhtml/slides.
+ */
+(function () {
+  'use strict';
+  var CM_BASE = 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16';
+  var cm = null;
+  var rerenderTimer = null;
+
+  function $(id) { return document.getElementById(id); }
+  function api() { return window.orzpaged; }
+  function srcEl() { return $('orz-src'); }
+  function currentSource() { return cm ? cm.getValue() : (srcEl() ? srcEl().textContent.replace(/^\n/, '').replace(/\n\s*$/, '') : ''); }
+
+  function toast(msg) {
+    var t = $('orz-toast'); if (!t) return;
+    t.textContent = msg; t.classList.add('show');
+    setTimeout(function () { t.classList.remove('show'); }, 1800);
+  }
+
+  /* ---- load CodeMirror on demand ---- */
+  function loadCss(href) {
+    if (document.querySelector('link[href="' + href + '"]')) return;
+    var l = document.createElement('link'); l.rel = 'stylesheet'; l.href = href;
+    l.setAttribute('data-orz-runtime', '1'); document.head.appendChild(l);
+  }
+  function loadJs(src) {
+    return new Promise(function (resolve, reject) {
+      if (document.querySelector('script[data-cm="' + src + '"]')) return resolve();
+      var s = document.createElement('script'); s.src = src; s.async = false;
+      s.setAttribute('data-cm', src); s.setAttribute('data-orz-runtime', '1');
+      s.onload = resolve; s.onerror = reject; document.head.appendChild(s);
+    });
+  }
+  function ensureCodeMirror() {
+    if (window.CodeMirror) return Promise.resolve();
+    loadCss(CM_BASE + '/codemirror.min.css');
+    return loadJs(CM_BASE + '/codemirror.min.js')
+      .then(function () { return loadJs(CM_BASE + '/mode/markdown/markdown.min.js'); });
+  }
+
+  function pagesEl() { return $('orz-pages'); }
+  function isEdit() { return document.documentElement.getAttribute('data-mode') === 'edit'; }
+
+  /* ---- preview zoom-to-fit (side-by-side pane is narrower than an A4 page) ---- */
+  function fitPreview() {
+    var pages = pagesEl(); if (!pages) return;
+    var wrap = pages.querySelector('.pagedjs_pages'); if (!wrap) return;
+    if (!isEdit()) { wrap.style.zoom = ''; return; }
+    wrap.style.zoom = '';                       // measure natural page width
+    var page = pages.querySelector('.pagedjs_page');
+    var pageW = page ? page.getBoundingClientRect().width : 0;
+    if (!pageW) return;
+    wrap.style.zoom = Math.min(1, (pages.clientWidth - 28) / pageW);
+  }
+  window.__orzPagedAfterRender = function () { fitPreview(); buildDynControls(); }; // engine calls this after every render
+
+  /* ---- dynamic switch (live) — a control per key the document actually uses ---- */
+  function humanizeKey(k) { return String(k).replace(/_/g, ' '); }
+  function normKey(k) { return String(k).trim().toLowerCase().replace(/-/g, '_'); }
+
+  function buildDynControls() {
+    var host = $('orz-dyn'); if (!host) return;
+    if (!api() || !api().getDynamicState) { host.innerHTML = ''; host.removeAttribute('data-keys'); return; }
+    var st = api().getDynamicState();
+    var opts = st.options || {}, choices = st.choices || {};
+    // Only keys the CURRENT document actually uses (data-show-when / -hide-when),
+    // so the control disappears when you switch to a template that has none.
+    var keys = Object.keys(opts).sort();
+    if (!keys.length) { host.innerHTML = ''; host.removeAttribute('data-keys'); return; }
+    var sig = keys.join(',');
+    if (host.getAttribute('data-keys') === sig) {            // same keys → just sync values
+      keys.forEach(function (k) {
+        var s = host.querySelector('select[data-key="' + k + '"]');
+        if (s) s.value = choices[k] || '';
+      });
+      return;
+    }
+    host.setAttribute('data-keys', sig);
+    host.innerHTML = '';
+    keys.forEach(function (k) {
+      var vals = (opts[k] || []).slice();
+      var cur = choices[k] || '';
+      if (cur && vals.indexOf(cur) < 0) vals.unshift(cur);   // keep the current value selectable
+      var ctl = document.createElement('span'); ctl.className = 'orz-dyn-ctl';
+      var lab = document.createElement('label'); lab.textContent = humanizeKey(k); lab.htmlFor = 'orz-dyn-' + k;
+      var sel = document.createElement('select'); sel.id = 'orz-dyn-' + k; sel.setAttribute('data-key', k); sel.title = humanizeKey(k);
+      vals.forEach(function (v) { var o = document.createElement('option'); o.value = v; o.textContent = v; sel.appendChild(o); });
+      sel.value = cur;
+      // Write the choice back into the source's `dynamic_choices` block so the
+      // dropdown and the nyml stay in sync (and editing the nyml drives the dropdown).
+      sel.addEventListener('change', function () { applyDynChoiceToSource(k, sel.value); });
+      ctl.appendChild(lab); ctl.appendChild(sel); host.appendChild(ctl);
+    });
+  }
+
+  /** Set `key: value` inside the document block's `dynamic_choices:` map, matching
+   *  the key by normalized form (so `answer-key` and `answer_key` are the same). */
+  function setSourceDynamicChoice(src, key, value) {
+    key = normKey(key);
+    var lines = src.split('\n');
+    var dcIdx = -1, dcIndent = 0;
+    for (var i = 0; i < lines.length; i++) {
+      var m = lines[i].match(/^(\s*)dynamic_choices\s*:/);
+      if (m) { dcIdx = i; dcIndent = m[1].length; break; }
+    }
+    if (dcIdx < 0) return null;                       // no block — nothing to sync
+    for (var j = dcIdx + 1; j < lines.length; j++) {
+      if (lines[j].trim() === '') continue;
+      var lm = lines[j].match(/^(\s*)([A-Za-z][\w-]*)\s*:\s*(.*)$/);
+      if (!lm || lm[1].length <= dcIndent) break;     // dedented / not a key → end of block
+      if (normKey(lm[2]) === key) { lines[j] = lm[1] + lm[2] + ': ' + value; return lines.join('\n'); }
+    }
+    var indent = ''; for (var s = 0; s < dcIndent + 2; s++) indent += ' ';
+    lines.splice(dcIdx + 1, 0, indent + key.replace(/_/g, '-') + ': ' + value);
+    return lines.join('\n');
+  }
+
+  function applyDynChoiceToSource(key, value) {
+    var next = setSourceDynamicChoice(currentSource(), key, value);
+    if (next == null) return;
+    if (cm) cm.setValue(next);
+    else { var ta = $('orz-ta'); if (ta) ta.value = next; }
+    syncSource();
+    if (api() && api().refresh) api().refresh();
+  }
+
+  /* ---- draggable divider (relative width) ---- */
+  function wireDivider() {
+    var d = $('orz-divider'); if (!d || d.__wired) return; d.__wired = true;
+    var dragging = false;
+    d.addEventListener('mousedown', function (e) {
+      dragging = true; d.classList.add('dragging'); e.preventDefault();
+      document.body.style.userSelect = 'none';
+    });
+    document.addEventListener('mousemove', function (e) {
+      if (!dragging) return;
+      var pct = Math.max(20, Math.min(78, (e.clientX / window.innerWidth) * 100));
+      document.documentElement.style.setProperty('--orz-split', pct + '%');
+    });
+    document.addEventListener('mouseup', function () {
+      if (!dragging) return;
+      dragging = false; d.classList.remove('dragging'); document.body.style.userSelect = '';
+      if (cm) cm.refresh(); fitPreview();
+    });
+  }
+
+  /* ---- proportional editor <-> preview scroll sync (toggleable) ---- */
+  var syncLock = false;
+  var syncEnabled = true;
+  try { syncEnabled = localStorage.getItem('orz-paged-sync') !== '0'; } catch (e) {}
+  function setSync(on) {
+    syncEnabled = !!on;
+    try { localStorage.setItem('orz-paged-sync', syncEnabled ? '1' : '0'); } catch (e) {}
+    var b = $('orz-sync'); if (b) b.setAttribute('aria-pressed', syncEnabled ? 'true' : 'false');
+  }
+  function wireSync() {
+    if (!cm || cm.__sync) return; cm.__sync = true;
+    cm.on('scroll', function () {
+      if (!syncEnabled || syncLock || !isEdit()) return;
+      var info = cm.getScrollInfo(); var max = info.height - info.clientHeight;
+      if (max <= 0) return;
+      var pages = pagesEl(); var pmax = pages.scrollHeight - pages.clientHeight;
+      syncLock = true; pages.scrollTop = (info.top / max) * pmax;
+      setTimeout(function () { syncLock = false; }, 24);
+    });
+    pagesEl().addEventListener('scroll', function () {
+      if (!syncEnabled || syncLock || !isEdit()) return;
+      var pages = pagesEl(); var pmax = pages.scrollHeight - pages.clientHeight;
+      if (pmax <= 0) return;
+      var info = cm.getScrollInfo(); var max = info.height - info.clientHeight;
+      syncLock = true; cm.scrollTo(null, (pages.scrollTop / pmax) * max);
+      setTimeout(function () { syncLock = false; }, 24);
+    });
+  }
+
+  /* ---- edit mode ---- */
+  function enterEdit() {
+    document.documentElement.setAttribute('data-mode', 'edit');
+    checkVersion(); // edit view only — broad viewers never see the update banner
+    wireDivider();
+    // reflect the theme actually in effect (document theme or a prior override)
+    var th = $('orz-theme');
+    if (th && api() && api().getTheme) { var cur = api().getTheme(); if (cur) th.value = cur; }
+    ensureCodeMirror().then(function () {
+      if (!cm) {
+        var ta = $('orz-ta');
+        ta.value = currentSource();
+        cm = window.CodeMirror.fromTextArea(ta, {
+          mode: 'markdown', lineNumbers: true, lineWrapping: true, theme: 'default',
+        });
+        cm.on('change', scheduleRerender);
+      }
+      wireSync();
+      setTimeout(function () { if (cm) { cm.refresh(); cm.focus(); } fitPreview(); }, 30);
+      setTimeout(fitPreview, 260); // re-fit once the slide-in transition settles
+    }).catch(function () { toast('Could not load the editor (offline?)'); });
+  }
+  function exitEdit() {
+    document.documentElement.removeAttribute('data-mode');
+    fitPreview();                  // clear zoom immediately
+    setTimeout(fitPreview, 260);   // and again after the slide-out settles
+  }
+
+  function scheduleRerender() {
+    if (rerenderTimer) clearTimeout(rerenderTimer);
+    rerenderTimer = setTimeout(function () {
+      syncSource();
+      if (api() && api().refresh) api().refresh();
+    }, 500);
+  }
+
+  /** Keep #orz-src in sync with the editor (so refresh()/setTheme()/save use current text). */
+  function syncSource() {
+    var el = srcEl(); if (!el) return;
+    el.textContent = '\n' + currentSource() + '\n';
+  }
+
+  /* ---- self-reproducing save ---- */
+  function serialize() {
+    syncSource();
+    var clone = document.documentElement.cloneNode(true);
+    clone.removeAttribute('data-mode');
+    // strip runtime-injected nodes (fonts, libs, katex, CodeMirror assets)
+    var rt = clone.querySelectorAll('[data-orz-runtime]');
+    for (var i = 0; i < rt.length; i++) rt[i].parentNode.removeChild(rt[i]);
+    // clear the rendered pages (the engine re-renders on load)
+    var pages = clone.querySelector('#orz-pages'); if (pages) pages.innerHTML = '';
+    // never bake in the (edit-only) update banner so a viewer can't see it
+    var ub = clone.querySelector('#orz-update'); if (ub) { ub.classList.remove('show'); ub.removeAttribute('data-latest'); }
+    // reset the editor host to a bare textarea (drop CodeMirror DOM)
+    var host = clone.querySelector('#orz-editor-host');
+    if (host) host.innerHTML = '<textarea id="orz-ta" spellcheck="false"></textarea>';
+    // guard against a closing script tag inside the source breaking the file
+    var src = clone.querySelector('#orz-src');
+    if (src) src.textContent = src.textContent.replace(/<\/(script)/gi, '<\\/$1');
+    return '<!DOCTYPE html>\n' + clone.outerHTML;
+  }
+
+  function suggestedName() {
+    var t = (document.title || 'document').replace(/[^\w.-]+/g, '-');
+    return t.replace(/\.paged$/, '') + '.paged.html';
+  }
+
+  /** Write `html` to disk; resolves true if saved in place (FS-Access), false if downloaded. */
+  function persist(html) {
+    if (window.showSaveFilePicker) {
+      return window.showSaveFilePicker({
+        suggestedName: suggestedName(),
+        types: [{ description: 'paged HTML', accept: { 'text/html': ['.paged.html', '.html'] } }],
+      }).then(function (handle) {
+        return handle.createWritable().then(function (w) {
+          return w.write(html).then(function () { return w.close(); });
+        });
+      }).then(function () { return true; });
+    }
+    downloadFile(html);
+    return Promise.resolve(false);
+  }
+  function save() {
+    persist(serialize()).then(function (inPlace) { if (inPlace) toast('Saved'); })
+      .catch(function (e) { if (e && e.name !== 'AbortError') downloadFile(serialize()); });
+  }
+  function downloadFile(html) {
+    var blob = new Blob([html], { type: 'text/html' });
+    var a = document.createElement('a');
+    a.href = URL.createObjectURL(blob); a.download = suggestedName();
+    document.body.appendChild(a); a.click();
+    setTimeout(function () { URL.revokeObjectURL(a.href); a.remove(); }, 1000);
+    toast('Downloaded a copy');
+  }
+
+  /* ---- framework self-update (checked only in edit view) ---- */
+  // SECURITY: the update source is HARDCODED here, never read from the file's
+  // config — so a tampered/forged file cannot redirect "Update" to fetch
+  // attacker-controlled code. The host is fixed to jsDelivr over HTTPS, and the
+  // exact URLs are shown to the user for confirmation before anything is fetched.
+  // (This protects genuine files; a wholly-malicious file controls this code too —
+  // see the security note in the README. Clicking Update trusts npm + jsDelivr.)
+  var UPD = {
+    host: 'https://cdn.jsdelivr.net/npm/',
+    manifest: 'https://data.jsdelivr.com/v1/packages/npm/orz-paged-browser/resolved',
+    enginePkg: 'orz-paged-browser',
+    engineFile: 'orz-paged.browser.js',
+    appPkg: 'orz-paged'
+  };
+  function CFG() { return window.__ORZ_PAGED__ || {}; }
+  function isNewer(a, b) {
+    var pa = String(a).split('.'), pb = String(b).split('.');
+    for (var i = 0; i < 3; i++) { var x = parseInt(pa[i], 10) || 0, y = parseInt(pb[i], 10) || 0; if (x > y) return true; if (x < y) return false; }
+    return false;
+  }
+  var versionChecked = false;
+  function checkVersion() {
+    if (versionChecked) return; versionChecked = true;
+    var c = CFG(); if (!c.version) return;
+    fetch(UPD.manifest).then(function (r) { return r.json(); }).then(function (j) {
+      var latest = j && j.version;
+      if (latest && isNewer(latest, c.version)) showUpdate(latest);
+    }).catch(function () {});
+  }
+  function showUpdate(latest) {
+    var bar = $('orz-update'); if (!bar) return;
+    bar.querySelector('.upd-text').textContent =
+      'Framework ' + latest + ' available (this file uses ' + CFG().version + ').';
+    bar.setAttribute('data-latest', latest);
+    bar.classList.add('show');
+  }
+  /** One-click update: re-fetch the engine bundle + app.js from the lockstep CDN
+   *  at the latest version, re-inline them, bump the version, save, and reload. */
+  function applyUpdate() {
+    var bar = $('orz-update'); var latest = bar && bar.getAttribute('data-latest'); if (!latest) return;
+    var engineUrl = UPD.host + UPD.enginePkg + '@' + latest + '/' + UPD.engineFile;
+    var appUrl = UPD.host + UPD.appPkg + '@' + latest + '/assets/app.js';
+    if (!window.confirm('Update the framework to ' + latest + '?\n\nThis downloads and runs code from:\n  ' + engineUrl + '\n  ' + appUrl + '\n\nOnly proceed if you trust this document and its publisher.')) return;
+    toast('Downloading framework ' + latest + '…');
+    Promise.all([
+      fetch(engineUrl).then(function (r) { if (!r.ok) throw new Error('engine'); return r.text(); }),
+      fetch(appUrl).then(function (r) { if (!r.ok) throw new Error('app'); return r.text(); }),
+    ]).then(function (res) {
+      var es = document.querySelector('script[data-orz-asset="engine"]');
+      if (es) { if (es.getAttribute('src')) es.setAttribute('src', engineUrl); else es.textContent = res[0]; }
+      var as = document.querySelector('script[data-orz-asset="app"]');
+      if (as) as.textContent = res[1];
+      var cs = document.querySelector('script[data-orz-asset="config"]');
+      if (cs) { c.version = latest; cs.textContent = 'window.__ORZ_PAGED__ = ' + JSON.stringify(c) + ';'; }
+      bar.classList.remove('show');
+      return persist(serialize());
+    }).then(function (inPlace) {
+      if (inPlace === undefined) return;
+      if (inPlace) { toast('Updated to ' + latest + ' — reloading…'); setTimeout(function () { location.reload(); }, 700); }
+      else { toast('Updated copy downloaded — reopen it to use the new framework.'); }
+    }).catch(function () { toast('Update failed — check your connection.'); });
+  }
+
+  /* ---- template picker ---- */
+  function templates() { return (window.__ORZ_PAGED__ && window.__ORZ_PAGED__.templates) || []; }
+  function esc(s) { return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'); }
+  var TPL_ACCENT = { Article: '#2962a4', Report: '#2f6fe0', Exam: '#9a2820', Letter: '#2e7d32', CV: '#7a3f9a', Note: '#b7791f' };
+  function buildTemplateMenu() {
+    var menu = $('orz-template-menu'); if (!menu || menu.getAttribute('data-built')) return;
+    var list = templates(); if (!list.length) return;
+    var html = '', lastGroup = '';
+    for (var i = 0; i < list.length; i++) {
+      var t = list[i];
+      if (t.group !== lastGroup) { lastGroup = t.group; html += '<div class="tpl-group">' + esc(t.group) + '</div>'; }
+      html += '<button type="button" class="tpl" data-i="' + i + '" style="--tpl-accent:' + (TPL_ACCENT[t.group] || '#2f6fe0') + '">'
+        + '<span class="tpl-ic"></span>'
+        + '<span class="tpl-meta"><span class="tpl-label">' + esc(t.label) + '</span>'
+        + '<span class="tpl-desc">' + esc(t.description) + '</span></span></button>';
+    }
+    menu.innerHTML = html;
+    menu.addEventListener('click', function (e) {
+      var b = e.target.closest ? e.target.closest('.tpl') : null;
+      if (!b) return;
+      applyTemplate(list[+b.getAttribute('data-i')]);
+      menu.hidden = true;
+    });
+    menu.setAttribute('data-built', '1');
+  }
+  function toggleTemplateMenu(show) {
+    var menu = $('orz-template-menu'); if (!menu) return;
+    if (show === undefined) show = menu.hidden;
+    if (show) buildTemplateMenu();
+    menu.hidden = !show;
+  }
+  function applyTemplate(t) {
+    if (!t || !t.skeleton) return;
+    var cur = currentSource().trim();
+    var next = t.skeleton;
+    // Preserve the old content in a comment so it's kept but inert (nyml blocks
+    // inside a comment don't render). Neutralize any `-->` in it first, else the
+    // first one would close the wrapper early and leak the rest back in.
+    if (cur) next += '\n\n<!-- Previous content (kept below — edit or delete):\n\n'
+      + cur.replace(/--+>/g, '--​>') + '\n-->\n';
+    if (cm) { cm.setValue(next); cm.focus(); }
+    else { var ta = $('orz-ta'); if (ta) ta.value = next; syncSource(); if (api() && api().refresh) api().refresh(); }
+    toast('Started from "' + t.label + '"');
+  }
+
+  /* ---- wire up ---- */
+  function init() {
+    var fab = $('orz-edit-fab'); if (fab) fab.addEventListener('click', enterEdit);
+    var close = $('orz-close'); if (close) close.addEventListener('click', exitEdit);
+    var exp = $('orz-export'); if (exp) exp.addEventListener('click', function () { if (api()) api().exportPdf(); });
+    var sav = $('orz-save'); if (sav) sav.addEventListener('click', save);
+    var tpl = $('orz-template'); if (tpl) tpl.addEventListener('click', function (e) { e.stopPropagation(); toggleTemplateMenu(); });
+    document.addEventListener('click', function (e) {
+      var menu = $('orz-template-menu'), btn = $('orz-template');
+      if (menu && !menu.hidden && !menu.contains(e.target) && (!btn || !btn.contains(e.target))) menu.hidden = true;
+    });
+    var theme = $('orz-theme');
+    if (theme) theme.addEventListener('change', function () { if (api() && api().setTheme) api().setTheme(theme.value); });
+    var sync = $('orz-sync');
+    if (sync) { setSync(syncEnabled); sync.addEventListener('click', function () { setSync(!syncEnabled); }); }
+    var updApply = $('orz-upd-apply'); if (updApply) updApply.addEventListener('click', applyUpdate);
+    var updDismiss = $('orz-upd-dismiss');
+    if (updDismiss) updDismiss.addEventListener('click', function () { var u = $('orz-update'); if (u) u.classList.remove('show'); });
+    var rz; window.addEventListener('resize', function () {
+      if (!isEdit()) return; clearTimeout(rz);
+      rz = setTimeout(function () { if (cm) cm.refresh(); fitPreview(); }, 120);
+    });
+    document.addEventListener('keydown', function (e) {
+      if ((e.metaKey || e.ctrlKey) && (e.key === 's' || e.key === 'S')) { e.preventDefault(); save(); }
+    });
+  }
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init);
+  else init();
+})();

package/assets/templates/article-page.md

@@ -0,0 +1,71 @@
+{{nyml
+kind: document
+template: article-page
+front_matter: clean
+}}
+
+{{nyml
+kind: article-title
+title: Your Article Title
+subtitle: A Concise, Descriptive Subtitle
+authors: |
+  First Author | 1,* | first.author@example.edu | 0000-0002-1825-0097
+  Second Author | 2 | second.author@example.org
+  Third Author | 1,2
+affiliations: |
+  1: Department of Example, University of Example
+  2: Institute of Example, Example City
+notes: |
+  *: Corresponding author
+date: Month Year
+placement: page
+}}
+
+{{nyml
+kind: abstract
+text: Briefly state the problem, what you did, and what you found. Summarize your main contribution in one or two sentences. Close with the significance of the result for the field.
+keywords: keyword one, keyword two, keyword three
+placement: page
+}}
+
+## Introduction
+
+Open with the context and motivation for your work. State the gap your study
+addresses and the question you set out to answer. End the section with a short
+statement of your contribution and an outline of what follows.
+
+## Methods
+
+Describe your approach so that a reader could reproduce it. Summarize the key
+parameters of your setup in a compact table:
+
+| Parameter | Symbol | Value |
+|---|---|---|
+| Sample size | $n$ | 120 |
+| Trials per group | $k$ | 5 |
+| Significance level | $\alpha$ | 0.05 |
+
+Quantities are reported with their uncertainties, and the mass–energy relation
+$E = mc^2$ is used where relevant. The core model is given by
+
+$$
+\hat{y} = \beta_0 + \sum_{i=1}^{n} \beta_i x_i + \varepsilon
+$$
+
+where the residual term $\varepsilon$ is assumed normally distributed.
+
+## Results
+
+- The primary measure improved by 18% over the baseline.
+- The effect held across all three experimental groups.
+- Results were statistically significant ($p < 0.05$).
+
+## Conclusion
+
+Restate the main finding, note its limitations, and point to one direction for
+future work.
+
+## References
+
+1. Author Name. *Title of the First Reference.* Journal Name, Year, pp. 1–10.
+2. Author Name. *Title of the Second Reference.* Publisher, Year.