htmlboard 0.6.0 → 0.8.0

package/src/client/explorer.js

@@ -1,10 +1,11 @@
 // HtmlBoard explorer: every design of the project side by side on one canvas.
 // Each design is an HTML file shown in an iframe at its real size, and the canvas pans and zooms
-// with one CSS transform. Names, outlines and section titles are drawn over it in screen pixels,
-// so they stay sharp and readable at any zoom. The server lists the designs at /api/designs and
-// pushes saved files at /api/events.
+// with one CSS transform. Zoomed out, a picture of each page stands in for it. Names, outlines and
+// section titles are drawn over it in screen pixels, so they stay sharp and readable at any zoom.
+// The server lists the designs at /api/designs and pushes saved files at /api/events.
 
 import { checkDesigns } from './check.js';
+import { drawDesign, forgetFiles } from './picture.js';
 
 const FRAME_GAP = 120;    // canvas px between the designs of a section
 const SECTION_GAP = 560;   // canvas px between sections
@@ -16,10 +17,19 @@ const MARGIN = 40;         // screen px around what a fit shows
 const NAME_SPACE = 24;     // screen px above a design for its name
 const MIN_NAMED = 56;      // screen px a design needs to be wide to show its name
 const TITLE_SPACE = 56;    // screen px above a section for its title and the names
+const TITLE_FONT = 20;     // screen px: a section's title, with room for it
+const TITLE_MIN = 13;      // screen px: the smallest it gets, zoomed far out
 const TOOLBAR_SPACE = 64;  // screen px kept clear at the bottom for the toolbar
 const DRAG_SLOP = 4;       // screen px a press can move and still be a click
 const DOUBLE_MS = 350;
 const CHANGE_MS = 60;      // saved files arriving this close together are applied at once
+const SETTLE_MS = 200;     // the canvas has stopped moving after this long still
+const AWAY_MARGIN = 0.25;  // of the screen's size: designs further off screen than this skip rendering
+const PICTURE_ZOOM = 0.25; // below this zoom, designs show as pictures of their pages
+const DRAWN_MS = 150;      // a page drawn this long has asked for its fonts and images…
+const QUIET_MS = 300;      // …and one that hasn't changed for this long has built itself,
+const BUILD_MS = 3000;     // or this long after it loaded, if it keeps changing
+const PICTURES_AT_ONCE = 3; // pictures made at the same time
 const DEFAULT_SIZE = [1200, 800]; // a design whose entry gives no size; without a height it grows with its page
 const FIT_HEIGHT = 100;    // a frame that fits its page however short (a component's) starts this tall
 
@@ -30,19 +40,25 @@ const els = {
   hover: $('hover'), selection: $('selection'), size: $('size'), zoom: $('zoom-reset'), open: $('open'),
   live: $('live'), help: $('help'), helpToggle: $('help-toggle'), toggleList: $('toggle-list'),
   toast: $('toast'), notice: $('notice'), noticeTitle: $('notice-title'), noticeText: $('notice-text'),
-  version: $('version'),
+  version: $('version'), sectionsBar: $('sections-bar'), expandAll: $('expand-all'), collapseAll: $('collapse-all'),
+  showAll: $('show-all'), hideAll: $('hide-all'), empty: $('empty'), emptyText: $('empty-text'),
+  actions: $('actions'), copyImage: $('copy-image'), saveImage: $('save-image'),
 };
 
 const state = {
   manifest: '',         // /api/designs as last read, to tell a real change
   autoDiscovered: false, // no designs.json: every HTML file is a design
-  sections: [],         // { name, designs, el, group, x, y, w, h }
-  designs: [],          // { id, file, path, title, search, w, h, autoHeight, x, y, frame, iframe, label, item, … }
+  // { id, name, designs, el, group, head, x, y, w, h, hidden, collapsed, searchCollapsed }
+  sections: [],
+  grouped: false,       // more than one section: each can be folded in the list and hidden from the canvas
+  designs: [],          // { id, file, path, title, search, section, w, h, autoHeight, x, y, frame, page, iframe, picture, label, item, … }
   view: { x: 0, y: 0, z: 1 },
   selected: null,
   hover: null,
+  actions: null,        // the design whose buttons show (copy, save as an image)
   query: [],            // the search's words, folded
   category: '',         // the filter: a category, or '' for all
+  pictures: false,      // zoomed out: designs show as pictures
   // What the first view fitted ('all' or a design). Until the user moves the canvas, it is fitted
   // again when the designs' real sizes come in.
   autoFit: null,
@@ -81,6 +97,12 @@ function el(tag, className, text) {
 
 const urlOf = (file) => encodeURI(`/${file}`);
 
+const ICONS = {
+  chevron: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg>',
+  eye: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M2.06 12.35a1 1 0 0 1 0-.7 10.75 10.75 0 0 1 19.88 0 1 1 0 0 1 0 .7 10.75 10.75 0 0 1-19.88 0"/><circle cx="12" cy="12" r="3"/></svg>',
+  eyeOff: '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M10.73 5.08a10.74 10.74 0 0 1 11.2 6.57 1 1 0 0 1 0 .7 10.75 10.75 0 0 1-1.44 2.49"/><path d="M14.08 14.16a3 3 0 0 1-4.24-4.24"/><path d="M17.48 17.5a10.75 10.75 0 0 1-15.42-5.15 1 1 0 0 1 0-.7 10.75 10.75 0 0 1 4.45-5.14"/><path d="m2 2 20 20"/></svg>',
+};
+
 // ---------------------------------------------------------------- loading
 
 async function fetchManifest() {
@@ -90,6 +112,7 @@ async function fetchManifest() {
 }
 
 function build(manifest) {
+  for (const design of state.designs) if (design.pictured) URL.revokeObjectURL(design.pictured.url);
   els.world.replaceChildren();
   els.list.replaceChildren();
   for (const node of els.overlay.querySelectorAll('.label, .section-title')) node.remove();
@@ -102,13 +125,25 @@ function build(manifest) {
   const title = manifest.title || 'Designs';
   els.title.textContent = title;
   document.title = `${title} · htmlboard`;
-  for (const entry of manifest.sections || []) {
+  const entries = manifest.sections || [];
+  // With one section there is nothing to choose between: it shows as before, and can't be hidden.
+  state.grouped = entries.length > 1;
+  const hidden = new Set(state.grouped ? readStore('hidden') || [] : []);
+  const collapsed = new Set(state.grouped ? readStore('collapsed') || [] : []);
+  const ids = new Set();
+  entries.forEach((entry, i) => {
     const name = entry.name || '';
-    const section = { name, designs: [], el: el('div', 'section-title', name), group: el('section') };
+    let id = String(entry.id || name || `section-${i + 1}`);
+    for (let n = 2; ids.has(id); n++) id = `${entry.id || name || `section-${i + 1}`}-${n}`;
+    ids.add(id);
+    const section = {
+      id, name, designs: [], el: el('div', 'section-title', name), group: el('section', 'group'),
+      hidden: hidden.has(id), collapsed: collapsed.has(id), searchCollapsed: false,
+    };
     els.overlay.insertBefore(section.el, els.hover);
     const items = el('ul');
-    // The files at the top of the folder make a first section without a title
-    if (name) section.group.append(el('h2', null, name));
+    if (state.grouped) section.group.append(sectionHead(section));
+    else if (name) section.group.append(el('h2', null, name)); // the files at the top of the folder have no title
     if (entry.description) section.group.append(el('p', 'section-desc', entry.description));
     section.group.append(items);
     for (const board of entry.artboards || []) {
@@ -119,7 +154,9 @@ function build(manifest) {
     }
     els.list.append(section.group);
     state.sections.push(section);
-  }
+  });
+  els.sectionsBar.hidden = !state.grouped;
+  placeFrames();
   if (!state.designs.length) {
     showNotice(
       'No designs yet',
@@ -140,6 +177,7 @@ function makeDesign(board, section) {
   const design = {
     id: String(board.id || file),
     category: board.category || '',
+    section,
     file,
     path: `/${file.split('?')[0]}`,
     title: board.title || file,
@@ -149,18 +187,30 @@ function makeDesign(board, section) {
     autoHeight: !Number(board.height),
     x: 0,
     y: 0,
+    // Its page: how many times it loaded, when it last did and last changed, since when it's drawn
+    loads: 0,
+    loadedAt: 0,
+    changedAt: 0,
+    drawnSince: 0,
+    pictured: null,  // the picture it has: { url, w, h, loads } (the size and load it was made at)
+    picturing: false,
+    failedAt: -1,    // the load a picture couldn't be made of
   };
   design.search = fold([design.title, file, board.description, board.category, ...(board.tags || []), section.name]
     .filter(Boolean).join(' '));
   design.frame = el('div', 'frame');
+  design.page = el('div', 'page');
   design.iframe = el('iframe');
   design.iframe.title = design.title;
   design.iframe.tabIndex = -1;
   design.iframe.setAttribute('scrolling', 'no');
   design.iframe.addEventListener('load', () => onLoad(design));
-  design.iframe.src = urlOf(file);
-  design.frame.append(design.iframe);
-  els.world.append(design.frame);
+  design.iframe.src = urlOf(file); // loads once placeFrames puts it on the canvas
+  design.page.append(design.iframe);
+  design.picture = el('img', 'picture');
+  design.picture.alt = '';
+  design.picture.draggable = false;
+  design.frame.append(design.page, design.picture);
 
   design.label = el('div', 'label', design.title);
   els.overlay.insertBefore(design.label, els.hover);
@@ -172,6 +222,8 @@ function makeDesign(board, section) {
   design.item.append(el('span', 'name', design.title), design.itemDims);
   design.item.addEventListener('click', () => {
     state.autoFit = null;
+    // A design of a hidden section shows its section
+    if (section.hidden) setHidden((s) => s.hidden && s !== section, { reveal: false });
     select(design, { fit: true });
   });
   design.li = el('li');
@@ -186,18 +238,27 @@ function showDims(design) {
 
 function onLoad(design) {
   const doc = design.iframe.contentDocument;
-  if (!doc || !design.autoHeight) return;
-  growToPage(design);
-  doc.fonts?.ready.then(() => growToPage(design));
-  // Pages go on building themselves after they load (components, scripts): measured again when
-  // they change. Not when the frame grows: a page always a bit taller than its frame would grow forever.
+  design.loads++; // its picture, if any, is of the page before
+  design.loadedAt = design.changedAt = performance.now();
+  paintFrame(design);
+  schedulePictures();
+  if (!doc) return;
+  if (design.autoHeight) {
+    growToPage(design);
+    doc.fonts?.ready.then(() => growToPage(design));
+  }
+  // Pages go on building themselves after they load (components, scripts): the picture waits for
+  // them, and a page without a height is measured again when its content changes. Not when the
+  // frame grows: a page always a bit taller than its frame would grow forever.
   let timer = 0;
-  new design.iframe.contentWindow.MutationObserver(() => {
+  new design.iframe.contentWindow.MutationObserver((records) => {
+    design.changedAt = performance.now();
+    if (!design.autoHeight || !records.some((record) => record.type === 'childList')) return;
     clearTimeout(timer);
     timer = setTimeout(() => {
       if (design.autoHeight && design.iframe.contentDocument === doc) growToPage(design);
     }, 50);
-  }).observe(doc.documentElement, { childList: true, subtree: true });
+  }).observe(doc.documentElement, { childList: true, subtree: true, characterData: true, attributes: true });
 }
 
 // A design without a height takes its page's.
@@ -223,13 +284,18 @@ function inFilter(design) {
   return !state.category || design.category === state.category;
 }
 
+// On the canvas: in a shown section, and kept by the filter.
+function placed(design) {
+  return !design.section.hidden && inFilter(design);
+}
+
 function matches(design) {
   return state.query.every((word) => design.search.includes(word));
 }
 
-// The designs the filter and the search keep.
+// The designs on the canvas the search keeps.
 function shown() {
-  return state.designs.filter((d) => inFilter(d) && matches(d));
+  return state.designs.filter((d) => placed(d) && matches(d));
 }
 
 function buildFilters() {
@@ -267,10 +333,12 @@ function setCategory(category, { fitAll = true } = {}) {
   if (fitAll) fit('all');
 }
 
+// The list shows what the filter and the search keep, hidden sections' designs too (faded), so they
+// can be found and shown again. The count is of the designs on the canvas.
 function applySearch() {
   let count = 0;
   for (const section of state.sections) {
-    let any = false;
+    let listed = 0;
     for (const design of section.designs) {
       const kept = inFilter(design);
       const on = kept && matches(design);
@@ -278,21 +346,152 @@ function applySearch() {
       design.frame.classList.toggle('is-dimmed', kept && !on);
       design.label.classList.toggle('is-dimmed', kept && !on);
       if (on) {
-        any = true;
-        count++;
+        listed++;
+        if (!section.hidden) count++;
       }
     }
-    section.group.hidden = !any;
+    section.group.hidden = !listed;
+    if (section.tally) section.tally.textContent = String(listed);
   }
   const total = state.designs.length;
-  const narrowed = state.query.length || state.category;
+  const searched = state.query.length || state.category;
+  const narrowed = searched || state.sections.some((s) => s.hidden);
   els.count.textContent = narrowed ? `${count} of ${total}` : String(total);
-  els.noMatch.hidden = !narrowed || count > 0;
+  els.noMatch.hidden = !searched || state.designs.some((d) => !d.li.hidden);
+  paintSections();
 }
 
 function search(text) {
+  const searching = state.query.length > 0;
   state.query = fold(text).split(/\s+/).filter(Boolean);
+  // A new search opens the folded sections, to show what it finds
+  if (!searching && state.query.length) for (const section of state.sections) section.searchCollapsed = false;
+  applySearch();
+}
+
+// ---------------------------------------------------------------- sections: folded in the list, hidden from the canvas
+
+// A section's row in the list: the arrow (or the title) folds it, the eye hides it from the canvas.
+function sectionHead(section) {
+  const head = el('div', 'group-head');
+  const toggle = el('button', 'group-toggle');
+  toggle.type = 'button';
+  toggle.innerHTML = ICONS.chevron;
+  section.tally = el('span', 'group-count');
+  toggle.append(el('span', 'group-name', section.name || 'Top level'), section.tally);
+  toggle.addEventListener('click', () => setCollapsed((s) => (s === section ? !isCollapsed(s) : isCollapsed(s))));
+  const eye = el('button', 'mini group-eye');
+  eye.type = 'button';
+  eye.addEventListener('click', (event) => {
+    if (event.altKey) {
+      // Only this section on the canvas; again, all of them
+      const alone = !section.hidden && state.sections.every((s) => s === section || s.hidden);
+      setHidden((s) => !alone && s !== section);
+    } else {
+      setHidden((s) => (s === section ? !s.hidden : s.hidden));
+    }
+  });
+  head.append(toggle, eye);
+  Object.assign(section, { head, toggle, eye });
+  return head;
+}
+
+// While searching, sections open to show what the search finds, and folding one lasts until the
+// search is cleared; otherwise it is remembered.
+function isCollapsed(section) {
+  return state.query.length ? section.searchCollapsed : section.collapsed;
+}
+
+// Folds and unfolds sections in the list: fn(section) says which are folded.
+function setCollapsed(fn) {
+  const searching = state.query.length > 0;
+  for (const section of state.sections) {
+    if (searching) section.searchCollapsed = Boolean(fn(section));
+    else section.collapsed = Boolean(fn(section));
+  }
+  saveSections();
+  paintSections();
+}
+
+// Hides and shows sections on the canvas: fn(section) says which are hidden. A hidden section's
+// designs leave the canvas and their pages unload, so a canvas of many designs stays light; the
+// rows below move up. `reveal`: bring the canvas into view when what's left is out of it.
+function setHidden(fn, { reveal = true } = {}) {
+  let changed = false;
+  for (const section of state.sections) {
+    const hidden = Boolean(fn(section));
+    if (section.hidden !== hidden) {
+      section.hidden = hidden;
+      changed = true;
+    }
+  }
+  if (!changed) return;
+  placeFrames();
+  if (state.selected && !placed(state.selected)) select(null);
+  if (state.hover && !placed(state.hover)) state.hover = null;
+  state.autoFit = null;
+  saveSections();
   applySearch();
+  layout();
+  if (reveal && state.designs.some(placed) && !inSight()) fit('all');
+}
+
+// The frames of the shown sections are on the canvas. Taken off it, a frame's page unloads; put
+// back, it loads again.
+function placeFrames() {
+  for (const design of state.designs) {
+    if (!design.section.hidden) {
+      if (!design.frame.isConnected) els.world.append(design.frame);
+    } else if (design.frame.isConnected) {
+      design.frame.remove();
+      // Its picture shows until the page has loaded again and been pictured anew
+      design.loads++;
+      design.loadedAt = 0;
+      design.drawnSince = 0;
+    }
+  }
+}
+
+function saveSections() {
+  if (!state.grouped) return;
+  writeStore('hidden', state.sections.filter((s) => s.hidden).map((s) => s.id));
+  writeStore('collapsed', state.sections.filter((s) => s.collapsed).map((s) => s.id));
+}
+
+// Whether any design on the canvas is on screen.
+function inSight() {
+  const { x, y, z } = state.view;
+  const screen = size();
+  return state.designs.some((d) => placed(d)
+    && x + (d.x + d.w) * z > 0 && x + d.x * z < screen.w && y + (d.y + d.h) * z > 0 && y + d.y * z < screen.h);
+}
+
+// The sections in the list as they are (folded, hidden, holding the selection), the buttons for all
+// of them, and the canvas's word when it has nothing left to show.
+function paintSections() {
+  for (const section of state.sections) {
+    const folded = state.grouped && isCollapsed(section);
+    section.group.classList.toggle('is-folded', folded);
+    section.group.classList.toggle('is-hidden', section.hidden);
+    section.group.classList.toggle('has-selection', folded && state.selected?.section === section);
+    if (!section.head) continue;
+    section.toggle.setAttribute('aria-expanded', String(!folded));
+    if (section.eyeShows !== section.hidden) {
+      section.eyeShows = section.hidden;
+      section.eye.innerHTML = section.hidden ? ICONS.eyeOff : ICONS.eye;
+      section.eye.title = `${section.hidden ? 'Show on the canvas' : 'Hide from the canvas'} (Alt + click: only this section)`;
+      section.eye.setAttribute('aria-label', `${section.hidden ? 'Show' : 'Hide'} ${section.name || 'Top level'}`);
+    }
+  }
+  const listed = state.sections.filter((s) => !s.group.hidden);
+  els.expandAll.disabled = !listed.some(isCollapsed);
+  els.collapseAll.disabled = listed.every(isCollapsed);
+  els.showAll.disabled = !state.sections.some((s) => s.hidden);
+  els.hideAll.disabled = state.sections.every((s) => s.hidden);
+  els.empty.hidden = !state.designs.length || state.designs.some(placed);
+  els.emptyText.textContent = state.sections.every((s) => s.hidden)
+    ? 'All sections are hidden.'
+    : 'This filter’s designs are all in hidden sections.';
 }
 
 // ---------------------------------------------------------------- layout and drawing
@@ -305,14 +504,14 @@ function layout() {
     let height = 0;
     for (const design of section.designs) {
       design.frame.hidden = !inFilter(design);
-      if (design.frame.hidden) continue;
+      if (!placed(design)) continue;
       design.x = x;
       design.y = y;
       Object.assign(design.frame.style, { left: `${x}px`, top: `${y}px`, width: `${design.w}px`, height: `${design.h}px` });
       x += design.w + FRAME_GAP;
       height = Math.max(height, design.h);
     }
-    // A section the filter empties takes no room
+    // A section the filter empties, or a hidden one, takes no room
     Object.assign(section, { x: 0, y, w: Math.max(0, x - FRAME_GAP), h: height, shown: x > 0 });
     if (section.shown) y += height + SECTION_GAP;
   }
@@ -322,7 +521,25 @@ function layout() {
 
 function paint() {
   const { x, y, z } = state.view;
+  const screen = size();
   els.world.style.transform = `translate(${x}px, ${y}px) scale(${z})`;
+  // Zoomed out, designs show as pictures. Zooming in, they come back to life once the canvas stops,
+  // not on the way past.
+  if (z < PICTURE_ZOOM) state.pictures = true;
+  else if (!moving) state.pictures = false;
+  // A design well off screen skips rendering: its page stays loaded, it just isn't drawn, so the
+  // designs on screen don't wait for the ones that aren't.
+  const mx = screen.w * AWAY_MARGIN;
+  const my = screen.h * AWAY_MARGIN;
+  for (const design of state.designs) {
+    if (placed(design)) {
+      const left = x + design.x * z;
+      const top = y + design.y * z;
+      design.away = left + design.w * z < -mx || left > screen.w + mx || top + design.h * z < -my || top > screen.h + my;
+      design.frame.classList.toggle('is-away', design.away);
+    }
+    paintFrame(design);
+  }
   // Dots every 32 canvas px, doubled or halved to stay 16 to 64 screen px apart.
   let grid = 32 * z;
   while (grid < 16) grid *= 2;
@@ -330,7 +547,9 @@ function paint() {
   els.viewport.style.setProperty('--grid', `${grid}px`);
   els.viewport.style.backgroundPosition = `${x}px ${y}px`;
   // Above each row: the section's title, then the designs' names. Zoomed far out the gap between
-  // rows gets thin: the names give way first, then the title.
+  // rows gets thin: the names give way, and the title shrinks to fit it, down to TITLE_MIN px.
+  // Further out it keeps that size and goes over the top of its own designs: finding a section
+  // matters more then than seeing the top of its designs.
   let first = true;
   for (const section of state.sections) {
     if (!section.shown) {
@@ -342,10 +561,18 @@ function paint() {
     first = false;
     const named = room >= TITLE_SPACE + 2;
     const top = Math.round(y + section.y * z);
-    section.el.hidden = room < 30 || !section.name;
-    section.el.style.transform = `translate(${Math.round(x + section.x * z)}px, ${top - (named ? 54 : 30)}px)`;
+    section.el.hidden = !section.name;
+    const font = named ? TITLE_FONT : Math.round(clamp((room - 6) / 1.2, TITLE_MIN, TITLE_FONT) * 2) / 2;
+    const line = Math.round(font * 1.2);
+    const titleTop = named ? top - 54 : Math.max(top - line - 4, Math.round(top - room + 2));
+    if (section.font !== font) {
+      section.font = font;
+      Object.assign(section.el.style, { fontSize: `${font}px`, lineHeight: `${line}px` });
+    }
+    section.el.classList.toggle('is-over', titleTop + line > top);
+    section.el.style.transform = `translate(${Math.round(x + section.x * z)}px, ${titleTop}px)`;
     for (const design of section.designs) {
-      if (design.frame.hidden) {
+      if (!placed(design)) {
         design.label.hidden = true;
         continue;
       }
@@ -358,6 +585,7 @@ function paint() {
   els.zoom.textContent = `${Math.round(z * 100)}%`;
   paintMarks();
   saveView();
+  schedulePictures();
 }
 
 // Selection and hover: the outlines and the names' colours.
@@ -375,6 +603,40 @@ function paintMarks() {
     design.label.classList.toggle('is-selected', design === state.selected);
     design.label.classList.toggle('is-hover', design === state.hover);
   }
+  paintActions();
+}
+
+// The buttons of the design under the pointer (on a touch screen, of the selected one): above its
+// top right corner, in the row of its name, which makes way for them. When its top is off screen,
+// they go at the top of the screen, over the design, or below it.
+const noHover = matchMedia('(hover: none)');
+let actionsSize = null;
+function paintActions() {
+  const before = state.actions;
+  const design = state.hover || (noHover.matches ? state.selected : null);
+  state.actions = design;
+  els.actions.hidden = !design;
+  const { x, y, z } = state.view;
+  if (before && before !== design) before.label.style.width = `${Math.round(before.w * z)}px`;
+  if (!design) return;
+  actionsSize ||= { w: els.actions.offsetWidth, h: els.actions.offsetHeight };
+  const { w, h } = actionsSize;
+  const left = x + design.x * z;
+  const top = y + design.y * z;
+  const bottom = top + design.h * z;
+  const ax = clamp(left + design.w * z - w, 6, size().w - w - 6);
+  let ay = top - h - 4;
+  let below = false;
+  if (ay < 6) {
+    ay = Math.max(6, top + 6);
+    if (ay + h > bottom - 6) {
+      ay = bottom + 4;
+      below = true;
+    }
+  }
+  els.actions.classList.toggle('is-below', below);
+  els.actions.style.transform = `translate(${Math.round(ax)}px, ${Math.round(ay)}px)`;
+  design.label.style.width = `${Math.round(ay < top ? Math.max(0, ax - left - 8) : design.w * z)}px`;
 }
 
 function place(node, design) {
@@ -394,8 +656,21 @@ function saveView() {
 
 // ---------------------------------------------------------------- moving the canvas
 
+// While the canvas moves, it is one layer the browser slides and scales without drawing every design
+// again on each frame; once it stops, they are drawn again, sharp, at the new zoom. (Kept as a layer
+// for good, it would hold more memory, and some browsers would leave it blurry after a zoom.)
+let settleTimer = 0;
+let moving = false;
 function setView(view) {
   state.view = view;
+  moving = true;
+  els.world.classList.add('is-moving');
+  clearTimeout(settleTimer);
+  settleTimer = setTimeout(() => {
+    moving = false;
+    els.world.classList.remove('is-moving');
+    paint(); // zoomed in, the designs come back to life; pictures carry on
+  }, SETTLE_MS);
   paint();
 }
 
@@ -428,8 +703,13 @@ function viewFor(rect, top) {
 // target: 'all' (what the search keeps) or a design.
 function fit(target, { animate = true } = {}) {
   if (target === 'all') {
-    const designs = shown();
-    moveTo(viewFor(boundsOf(designs.length ? designs : state.designs.filter(inFilter)), TITLE_SPACE), animate);
+    const found = shown();
+    const designs = found.length ? found : state.designs.filter(placed);
+    if (!designs.length) {
+      paint(); // every section hidden: nothing to fit
+      return;
+    }
+    moveTo(viewFor(boundsOf(designs), TITLE_SPACE), animate);
   } else {
     moveTo(viewFor(target, NAME_SPACE), animate);
   }
@@ -500,7 +780,11 @@ function select(design, { fit: fitIt = false, animate = true } = {}) {
   els.open.setAttribute('aria-disabled', String(!state.selected));
   const hash = state.selected ? `#${encodeURIComponent(state.selected.id)}` : '';
   if (location.hash !== hash) history.replaceState(null, '', hash || location.pathname + location.search);
-  if (state.selected && !state.selected.li.hidden) state.selected.item.scrollIntoView({ block: 'nearest' });
+  paintSections(); // a folded section marks the selection it holds
+  if (state.selected && !state.selected.li.hidden) {
+    const { section } = state.selected;
+    (state.grouped && isCollapsed(section) ? section.head : state.selected.item).scrollIntoView({ block: 'nearest' });
+  }
   if (state.selected && fitIt) fit(state.selected, { animate });
   else paintMarks();
 }
@@ -537,7 +821,7 @@ function hit(point) {
   const cy = (point.y - y) / z;
   for (let i = state.designs.length - 1; i >= 0; i--) {
     const d = state.designs[i];
-    if (d.frame.hidden) continue;
+    if (!placed(d)) continue;
     const top = d.y - (d.label.hidden ? 0 : NAME_SPACE / z);
     if (cx >= d.x && cx <= d.x + d.w && cy >= top && cy <= d.y + d.h) return d;
   }
@@ -548,6 +832,251 @@ function openSelected() {
   if (state.selected) window.open(urlOf(state.selected.file), '_blank', 'noopener');
 }
 
+// ---------------------------------------------------------------- a design as an image
+
+let exporting = false;
+
+const reason = (err) => String(err?.message || err || 'unknown error');
+
+// The design as a PNG of its full size, at the screen's pixel density (twice the size on a Retina screen).
+async function pngOf(design) {
+  const scale = clamp(Math.round(window.devicePixelRatio || 1), 1, 3);
+  const canvas = await drawDesign(design.iframe, { width: design.w, height: design.h, scale });
+  const blob = await new Promise((resolve) => canvas.toBlob(resolve, 'image/png'));
+  if (!blob) throw new Error('the image is too big');
+  return { blob, width: canvas.width, height: canvas.height };
+}
+
+function exportStarts(design) {
+  if (!design) toast('Select a design first');
+  if (!design || exporting || !design.frame.isConnected) return false;
+  exporting = true;
+  els.actions.setAttribute('aria-busy', 'true');
+  return true;
+}
+
+function exportEnds() {
+  exporting = false;
+  els.actions.removeAttribute('aria-busy');
+}
+
+async function copyImage(design) {
+  if (!navigator.clipboard?.write || typeof ClipboardItem === 'undefined') {
+    toast('This browser can’t copy images: save it instead (S)');
+    return;
+  }
+  if (!exportStarts(design)) return;
+  toast(`Copying ${design.title}…`);
+  const png = pngOf(design);
+  png.catch(() => {}); // told below
+  try {
+    // Written right away, while the click still allows it; the image follows when it's drawn
+    await navigator.clipboard.write([new ClipboardItem({ 'image/png': png.then((p) => p.blob) })]);
+    const { width, height } = await png;
+    toast(`Copied ${design.title} (${width} × ${height})`);
+  } catch (err) {
+    toast(`Couldn’t copy ${design.title}: ${reason(await png.then(() => err, (drawing) => drawing))}`);
+  } finally {
+    exportEnds();
+  }
+}
+
+// Saved in a folder chosen once per project; without folder access (Firefox, Safari), downloaded.
+async function saveImage(design, { choose = false } = {}) {
+  if (!exportStarts(design)) return;
+  const name = `${design.id.replace(/[\\/:*?"<>|\u0000-\u001f]+/g, '-')}.png`;
+  try {
+    if (!window.showDirectoryPicker) {
+      download((await pngOf(design)).blob, name);
+      toast(`Downloaded ${name}`);
+      return;
+    }
+    const folder = await saveFolder(choose); // asked for first, while the click still allows it
+    if (!folder) return;
+    toast(`Saving ${design.title}…`);
+    const { blob } = await pngOf(design);
+    const file = await freeName(folder, name);
+    const writable = await (await folder.getFileHandle(file, { create: true })).createWritable();
+    await writable.write(blob);
+    await writable.close();
+    toast(`Saved ${file} in ${folder.name || 'the folder'}`);
+  } catch (err) {
+    if (err?.name === 'NotFoundError') toast(`Couldn’t save ${design.title}: its folder is gone (Shift + click Save to choose another)`);
+    else if (err?.name !== 'AbortError') toast(`Couldn’t save ${design.title}: ${reason(err)}`); // not a cancelled picker
+  } finally {
+    exportEnds();
+  }
+}
+
+// The folder images go to: chosen the first time (or with Shift) and remembered for the project. On
+// a later visit the browser asks again for leave to write in it, unless it was given for good.
+async function saveFolder(choose) {
+  const key = `${storePrefix}save-folder`;
+  const saved = choose ? null : await folders('readonly', (store) => store.get(key)).catch(() => null);
+  if (saved) {
+    const mode = { mode: 'readwrite' };
+    if (await saved.queryPermission(mode) === 'granted' || await saved.requestPermission(mode) === 'granted') return saved;
+    toast(`Not allowed to save in ${saved.name}: Shift + click Save to choose another folder`);
+    return null;
+  }
+  const folder = await window.showDirectoryPicker({ id: 'htmlboard-images', mode: 'readwrite' });
+  await folders('readwrite', (store) => store.put(folder, key)).catch(() => {});
+  return folder;
+}
+
+// Kept in IndexedDB: a folder the browser gave access to can't go in localStorage.
+function folders(mode, request) {
+  return new Promise((resolve, reject) => {
+    const open = indexedDB.open('htmlboard', 1);
+    open.onupgradeneeded = () => open.result.createObjectStore('folders');
+    open.onerror = () => reject(open.error);
+    open.onsuccess = () => {
+      const db = open.result;
+      const tx = db.transaction('folders', mode);
+      const asked = request(tx.objectStore('folders'));
+      tx.oncomplete = () => {
+        db.close();
+        resolve(asked.result);
+      };
+      tx.onerror = tx.onabort = () => {
+        db.close();
+        reject(tx.error);
+      };
+    };
+  });
+}
+
+// name.png, or name-2.png, name-3.png… when that is taken: saving never replaces an image.
+async function freeName(folder, name) {
+  const stem = name.replace(/\.png$/, '');
+  for (let n = 1; n < 1000; n++) {
+    const file = n === 1 ? name : `${stem}-${n}.png`;
+    try {
+      await folder.getFileHandle(file);
+    } catch (err) {
+      if (err.name === 'NotFoundError') return file;
+      if (err.name !== 'TypeMismatchError') throw err; // a folder of that name: the next one
+    }
+  }
+  throw new Error(`${name} and 999 more are taken`);
+}
+
+function download(blob, name) {
+  const link = el('a');
+  link.href = URL.createObjectURL(blob);
+  link.download = name;
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(link.href), 10000);
+}
+
+// ---------------------------------------------------------------- pictures when zoomed out
+
+// Zoomed out, a design shows a picture of its page, and the page under it isn't drawn: a canvas of
+// many designs stays light, and their animations stop until it's zoomed in again. Pictures are made
+// a few at a time while the canvas rests, nearest the middle of the screen first, of pages that have
+// been drawn (a page loads its fonts and images as it's drawn) and have built themselves. Until a
+// design has a picture, and while its picture is out of date (its page reloaded, or resized), its
+// page is drawn, under the old picture if it has one.
+
+// What a design shows: its page, or zoomed out, its picture over it
+function paintFrame(design) {
+  const picture = state.pictures && Boolean(design.pictured);
+  const still = picture && isFresh(design); // the page under it isn't drawn
+  design.frame.classList.toggle('is-picture', picture);
+  design.frame.classList.toggle('is-still', still);
+  const drawn = placed(design) && design.frame.isConnected && !design.away && !still;
+  if (!drawn) {
+    design.drawnSince = 0;
+  } else if (!design.drawnSince) {
+    design.drawnSince = performance.now();
+    // Measured again on its way back: a page measured while it isn't drawn can come out a few px off
+    if (design.loadedAt && design.autoHeight) requestAnimationFrame(() => growToPage(design));
+  }
+}
+
+// Whether a design's picture shows its page as it is: made of this load, at this size
+function isFresh(design) {
+  const { pictured } = design;
+  return Boolean(pictured) && pictured.loads === design.loads && pictured.w === design.w && pictured.h === design.h;
+}
+
+let picturing = 0; // pictures being made
+let pictureTimer = 0;
+function schedulePictures() {
+  clearTimeout(pictureTimer);
+  if (moving) return; // carries on when the canvas stops
+  while (picturing < PICTURES_AT_ONCE) {
+    const { design, wait } = nextPicture();
+    if (!design) {
+      if (wait < Infinity) pictureTimer = setTimeout(schedulePictures, wait);
+      else if (!picturing) forgetFiles(); // every picture made: what they shared can go
+      return;
+    }
+    picturing++;
+    design.picturing = true;
+    takePicture(design).finally(() => {
+      design.picturing = false;
+      picturing--;
+      setTimeout(schedulePictures); // the canvas gets a turn between pictures
+    });
+  }
+}
+
+// The next design to picture, or how long until one is ready
+function nextPicture() {
+  const now = performance.now();
+  const { x, y, z } = state.view;
+  const screen = size();
+  let next = null;
+  let nearest = Infinity;
+  let wait = Infinity;
+  for (const design of state.designs) {
+    if (design.picturing || !design.drawnSince || !design.loadedAt || isFresh(design) || design.failedAt === design.loads) continue;
+    if (design.iframe.contentDocument?.readyState !== 'complete') continue;
+    const ready = Math.max(design.drawnSince + DRAWN_MS, Math.min(design.changedAt + QUIET_MS, design.loadedAt + BUILD_MS));
+    if (ready > now) {
+      wait = Math.min(wait, ready - now);
+      continue;
+    }
+    const distance = Math.hypot(x + (design.x + design.w / 2) * z - screen.w / 2, y + (design.y + design.h / 2) * z - screen.h / 2);
+    if (distance < nearest) {
+      next = design;
+      nearest = distance;
+    }
+  }
+  return { design: next, wait };
+}
+
+// Sharp up to PICTURE_ZOOM, at the screen's pixel density (twice on a Retina screen)
+async function takePicture(design) {
+  const { loads, w, h } = design;
+  const scale = PICTURE_ZOOM * clamp(window.devicePixelRatio || 1, 1, 2);
+  let url = '';
+  try {
+    const canvas = await drawDesign(design.iframe, { width: w, height: h, scale });
+    const blob = await new Promise((resolve) => canvas.toBlob(resolve, 'image/webp', 0.9));
+    canvas.width = 0; // its pixels can go
+    if (!blob) throw new Error('no picture');
+    url = URL.createObjectURL(blob);
+    const image = new Image();
+    image.src = url;
+    await image.decode(); // so it shows at once
+  } catch {
+    if (url) URL.revokeObjectURL(url);
+    if (design.loads === loads) design.failedAt = loads; // its page stays drawn, until it loads again
+    return;
+  }
+  // Its page reloaded, or the design changed size, while it was made (or the canvas was rebuilt)
+  if (design.loads !== loads || design.w !== w || design.h !== h || !state.designs.includes(design)) {
+    URL.revokeObjectURL(url);
+    return;
+  }
+  if (design.pictured) URL.revokeObjectURL(design.pictured.url);
+  design.pictured = { url, w, h, loads };
+  design.picture.src = url;
+  paintFrame(design);
+}
+
 // ---------------------------------------------------------------- panels and messages
 
 function toggleList(show = els.app.classList.contains('is-collapsed')) {
@@ -618,7 +1147,8 @@ function uses(design, path) {
 function rebuild(manifest) {
   const selected = state.selected?.id;
   build(manifest);
-  select(state.designs.find((d) => d.id === selected) || null);
+  const design = state.designs.find((d) => d.id === selected);
+  select(design && placed(design) ? design : null);
 }
 
 // What a new canvas changed, from the designs before and after it.
@@ -699,8 +1229,9 @@ async function reloadAll() {
     toast(`Could not read the designs (${err.message})`);
     return;
   }
+  forgetFiles();
   if (JSON.stringify(manifest) !== state.manifest) rebuild(manifest);
-  else state.designs.forEach(reloadFrame);
+  else state.designs.filter((d) => d.frame.isConnected).forEach(reloadFrame);
   toast('Designs reloaded');
 }
 
@@ -721,6 +1252,7 @@ async function applyChanges() {
   pending.files.clear();
   pending.manifest = false;
   pending.folders = false;
+  forgetFiles(); // pictures read the files again
 
   // A new canvas loads every design afresh, so nothing else is left to do.
   if (manifestChanged) {
@@ -736,8 +1268,9 @@ async function applyChanges() {
     if (await rebuildIfChanged() === 'rebuilt') return;
   }
 
+  // A hidden section's designs aren't loaded: they load as they are now when it is shown.
   const paths = files.map((file) => `/${file}`);
-  const frames = state.designs.filter((d) => paths.includes(d.path) || paths.some((path) => uses(d, path)));
+  const frames = state.designs.filter((d) => d.frame.isConnected && (paths.includes(d.path) || paths.some((path) => uses(d, path))));
   if (!frames.length) return;
   // Name the shared files the designs use (a stylesheet, a script), not whatever else was saved.
   // Asked before reloading: a reloading page forgets what it loaded.
@@ -849,14 +1382,14 @@ function local(event) {
 }
 
 function onCanvas(event) {
-  return !event.target.closest('.toolbar, .help, .notice');
+  return !event.target.closest('.toolbar, .help, .notice, .empty, .actions');
 }
 
 function wire() {
   const { viewport } = els;
 
   viewport.addEventListener('wheel', (event) => {
-    if (!onCanvas(event)) return;
+    if (event.target.closest('.toolbar, .help, .notice')) return; // over a design's buttons, it still moves
     event.preventDefault();
     state.autoFit = null;
     cancelAnimationFrame(animation);
@@ -880,6 +1413,8 @@ function wire() {
       }
       setView({ ...state.view, x: state.view.x - dx, y: state.view.y - dy });
     }
+    // The canvas moved under the pointer: the design under it now
+    if (!pointers.size) setHover(hit(local(event)));
   }, { passive: false });
 
   // Ctrl + scroll and pinches anywhere else (the list, the toolbar) would zoom the whole page.
@@ -996,11 +1531,12 @@ function wire() {
         els.search.blur();
       }
     } else if (event.key === 'Enter') {
-      // The first design found, fitted.
+      // The first design found on the canvas, fitted; else the first in the list, its section shown.
       event.preventDefault();
-      const [first] = shown();
+      const [first = state.designs.find((d) => !d.li.hidden)] = shown();
       if (first) {
         state.autoFit = null;
+        if (first.section.hidden) setHidden((s) => s.hidden && s !== first.section, { reveal: false });
         select(first, { fit: true });
       }
     }
@@ -1037,6 +1573,8 @@ function wire() {
         search('');
       } else if (state.category) setCategory('');
     } else if (key === 'Enter' && !onControl) openSelected();
+    else if (key === 'c' || key === 'C') copyImage(state.selected || state.hover);
+    else if (key === 's' || key === 'S') saveImage(state.selected || state.hover, { choose: event.shiftKey });
     else if (key === 'r' || key === 'R') reloadAll();
     else if (key === '/') {
       if (els.app.classList.contains('is-collapsed')) toggleList(true);
@@ -1069,6 +1607,14 @@ function wire() {
     viewport.classList.remove('is-space');
   });
 
+  // A design calling scrollIntoView() or focus() scrolls every box around its frame. The canvas
+  // clips instead of scrolling (explorer.css); where clip isn't supported, it is put back.
+  viewport.addEventListener('scroll', () => {
+    viewport.scrollLeft = 0;
+    viewport.scrollTop = 0;
+  });
+  window.addEventListener('scroll', () => window.scrollTo(0, 0));
+
   window.addEventListener('resize', () => {
     if (state.autoFit) fit(state.autoFit, { animate: false });
     else paint();
@@ -1078,6 +1624,7 @@ function wire() {
     const design = designFromHash();
     if (design && design !== state.selected) {
       state.autoFit = null;
+      if (design.section.hidden) setHidden((s) => s.hidden && s !== design.section, { reveal: false });
       if (!inFilter(design)) setCategory('', { fitAll: false });
       select(design, { fit: true });
     }
@@ -1090,6 +1637,14 @@ function wire() {
   $('reload').addEventListener('click', reloadAll);
   els.toggleList.addEventListener('click', () => toggleList());
   els.helpToggle.addEventListener('click', () => toggleHelp());
+  els.expandAll.addEventListener('click', () => setCollapsed(() => false));
+  els.collapseAll.addEventListener('click', () => setCollapsed(() => true));
+  els.showAll.addEventListener('click', () => setHidden(() => false));
+  els.hideAll.addEventListener('click', () => setHidden(() => true));
+  $('empty-show').addEventListener('click', () => setHidden(() => false));
+  els.copyImage.addEventListener('click', () => copyImage(state.actions));
+  els.saveImage.addEventListener('click', (event) => saveImage(state.actions, { choose: event.shiftKey }));
+  if (!window.showDirectoryPicker) els.saveImage.title = 'Download as an image (S)';
   for (const id of ['zoom-in', 'zoom-out', 'zoom-reset', 'fit-all']) {
     $(id).addEventListener('click', () => {
       state.autoFit = null;
@@ -1126,6 +1681,7 @@ async function start() {
   const design = designFromHash();
   const saved = readStore('view');
   if (design) {
+    if (design.section.hidden) setHidden((s) => s.hidden && s !== design.section, { reveal: false });
     state.autoFit = design;
     select(design, { fit: true, animate: false });
   } else if (saved && [saved.x, saved.y, saved.z].every(Number.isFinite) && saved.z > 0) {