htmlboard 0.6.0 → 0.8.0

package/README.md

@@ -39,6 +39,9 @@ Modern AI agents and developers generate dozens of HTML mockups, layout variatio
 - 📐 **Optional `designs.json`**: Curates when you want it (section titles, order, overrides); designs it doesn't list still show at the end, or don't (`"unlisted": "hide"`). `htmlboard migrate` moves an existing one into the files.
 - 📱 **Device Filters**: **Mobile**, **Tablet** and **Desktop** (and **Components**, or your own categories) lay out just those designs, side by side, to compare them.
 - 🔎 **Search**: Find designs by name, file, tags or section (case and accents don't matter); the others fade out in place.
+- 👁️ **Sections You Can Fold and Hide**: Fold a section in the list, or hide it from the canvas: its designs unload, so a canvas of hundreds of designs stays light. <kbd>Alt</kbd> + click its eye to see only that one; the list remembers what you folded and hid.
+- 🖼️ **Light When Zoomed Out**: Below 25%, each design shows as a picture of its page, made in the background, and the page under it isn't drawn: hundreds of designs pan and zoom smoothly, and their animations don't keep your computer busy. Zoom in and they're live again.
+- 📸 **Copy or Save as an Image**: Hover a design for two buttons: copy it to the clipboard as a PNG of its full size (twice that on a Retina screen), or save it in a folder you choose once. <kbd>C</kbd> and <kbd>S</kbd> do the same for the selected design.
 - 🎯 **Focus & Zoom-to-Fit**: Click a design in the list or double-click it on the canvas to fit it, <kbd>Shift</kbd> + <kbd>1</kbd> fits everything, <kbd>←</kbd> <kbd>→</kbd> step through the designs.
 - 🔗 **Deep Links**: The URL follows the selected design (`http://localhost:3000/#checkout-b`), so you can share or reload a view of one design.
 - ⌨️ **Keyboard-First Workflow**: Figma-like shortcuts; <kbd>?</kbd> lists them.
@@ -240,7 +243,8 @@ Checked 6 designs in designs (the canvas at http://localhost:3000): 2 with probl
 
 Every `.html` file under the folder is a design (hidden folders, `node_modules`, `dist`, `build` and the [components](#-components) in `components/` aside):
 
-- **Sections are folders.** Each folder is a row on the canvas, named after the folder; the files at the top of the folder make a first row without a title.
+- **Sections are folders.** Each folder is a row on the canvas, named after the folder; the files at the top of the folder make a first row without a title ("Top level" in the list).
+- **In the list, a section folds** under its title, and **its eye hides it from the canvas**: its designs unload and the rows below move up, which keeps a canvas of many designs light. <kbd>Alt</kbd> + click an eye shows only that section (again: all of them); the buttons above the sections fold, unfold, show or hide them all. A hidden section's designs stay in the list, faded, and the search still finds them: clicking one (or a link to it) shows its section. The list remembers what you folded and hid, for each project.
 - **Number prefixes set the order** of files and folders: `01-…`, `02-…`, `10-…` (up to three digits; `2` comes before `10`). They don't show in names or in links, so reordering breaks nothing.
 - **A file describes itself** in its `<head>`:
 
@@ -366,6 +370,7 @@ It writes each file's size, category, label, variants and description as tags af
 | <kbd>Shift</kbd> + <kbd>2</kbd>, double-click | Fit the design |
 | <kbd>←</kbd> / <kbd>→</kbd> | Previous / next design |
 | <kbd>Enter</kbd> | Open the selected design on its own |
+| <kbd>C</kbd> / <kbd>S</kbd> | Copy / save the selected design as an image (<kbd>Shift</kbd> + <kbd>S</kbd>: choose the folder) |
 | <kbd>/</kbd> | Search (<kbd>Enter</kbd> fits the first match, <kbd>Esc</kbd> clears) |
 | <kbd>1</kbd> – <kbd>4</kbd> | Show all, mobile, tablet, desktop (<kbd>5</kbd> on: the other categories) |
 | <kbd>R</kbd> | Reload the designs |
@@ -373,7 +378,11 @@ It writes each file's size, category, label, variants and description as tags af
 | <kbd>?</kbd> | Show the shortcuts |
 | <kbd>Esc</kbd> | Deselect, then clear the search, then the filter |
 
-On the canvas the designs are pictures: the canvas takes every click and scroll, so <kbd>Ctrl</kbd> + scroll never zooms the page itself. Use **Open** (or <kbd>Enter</kbd>) to try a design's links and hover states on its own.
+On the canvas the designs don't take clicks: the canvas takes every click and scroll, so <kbd>Ctrl</kbd> + scroll never zooms the page itself. Use **Open** (or <kbd>Enter</kbd>) to try a design's links and hover states on its own.
+
+**Zoomed out, pictures.** Below 25% zoom, each design shows a picture of its page instead of the page itself, so a canvas of hundreds of designs stays light: its animations stop, and nothing is drawn again until the view changes. The pictures are made in the background, a few at a time, nearest the middle of the screen first, once a page has loaded and built itself; until then, and while a saved design's picture is made again, its page shows as before. Zoom in past 25% and the designs come back to life once the canvas stops. A picture has the limits of an image of a design (below).
+
+**Images of a design.** Hovering a design shows two buttons over its top right corner. **Copy** puts it in the clipboard as a PNG, to paste anywhere; **Save** writes it in a folder you pick the first time (the canvas remembers it for the project, <kbd>Shift</kbd> + click picks another), as `<design id>.png`, then `-2`, `-3`… so it never replaces an image. Browsers without folder access (Firefox, Safari) download it instead. Your browser draws the image from the page as its frame shows it, with its stylesheets, fonts and images, at the frame's size and your screen's pixel density. A few things can't be in it: images from other sites that don't allow it, pages inside the page (iframes), and shadow DOM.
 
 ---
 
@@ -467,6 +476,7 @@ htmlboard/
 │   │   ├── explorer.css  # Dark chrome, dot grid
 │   │   ├── explorer.js   # Layout, pan/zoom, search, live reload
 │   │   ├── check.js      # Checks the designs in frames out of sight, for `htmlboard check`
+│   │   ├── picture.js    # A design as an image, drawn by the browser (copy, save, zoomed out)
 │   │   ├── probe.js      # Notes script errors and failed loads in the frames the check loads
 │   │   ├── favicon.svg, logo.svg, mark.svg
 │   │   └── fonts/        # Inter and Bricolage Grotesque (OFL)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlboard",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Infinite canvas and design explorer for HTML artboards — designed for humans and LLMs",
   "type": "module",
   "bin": {

package/src/client/explorer.css

@@ -158,6 +158,49 @@ kbd {
 
 .search input:focus ~ kbd, .search input:not(:placeholder-shown) ~ kbd { display: none; }
 
+/* All the sections at once: unfold or fold them in the list, show or hide them on the canvas */
+.sections-bar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin: 10px 12px 0;
+  padding: 6px 0 0 4px;
+  border-top: 1px solid var(--x-line-soft);
+}
+
+.sections-label { font-size: 11px; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; color: var(--x-text-faint); }
+.sections-tools { display: flex; align-items: center; gap: 2px; }
+.mini-gap { width: 6px; }
+
+/* A small icon button: the sections bar, a section's eye */
+.mini {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: 0;
+  border-radius: 5px;
+  background: none;
+  color: var(--x-text-soft);
+  cursor: pointer;
+}
+
+.mini:hover:not(:disabled) { background: var(--x-wash); color: var(--x-text); }
+.mini:disabled { opacity: 0.35; cursor: default; }
+
+.mini svg {
+  width: 15px;
+  height: 15px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
 .list { flex: 1; overflow-y: auto; padding: 0 8px 16px; scrollbar-width: thin; scrollbar-color: var(--x-line) transparent; }
 
 .list h2 {
@@ -174,6 +217,67 @@ kbd {
 .list ul { margin: 0; padding: 0; list-style: none; }
 .list section > ul:first-child { margin-top: 12px; } /* a section without a title (the files at the top) */
 
+/* A section of several: its title (and arrow) folds it, its eye hides it from the canvas. The eye
+   shows on hover, and stays while the section is hidden. */
+.group-head { display: flex; align-items: center; gap: 2px; margin: 12px 0 2px; border-radius: 5px; }
+.group-head:hover { background: var(--x-wash); }
+
+.group-toggle {
+  display: flex;
+  flex: 1;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+  padding: 4px 6px 4px 2px;
+  border: 0;
+  border-radius: 5px;
+  background: none;
+  color: var(--x-text-soft);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.group-toggle svg {
+  flex: none;
+  width: 14px;
+  height: 14px;
+  fill: none;
+  stroke: var(--x-text-faint);
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  transition: transform 0.12s;
+}
+
+.group-name {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.group-count { order: 1; flex: none; margin-left: auto; padding-left: 8px; font-size: 12px; color: var(--x-text-faint); font-variant-numeric: tabular-nums; }
+.group-eye { visibility: hidden; }
+.group-head:hover .group-eye, .group-eye:focus-visible, .group.is-hidden .group-eye { visibility: visible; }
+
+.group.is-folded .group-toggle svg { transform: rotate(-90deg); }
+.group.is-folded > ul, .group.is-folded > .section-desc { display: none; }
+.group-head ~ ul .item { padding-left: 20px; }
+.list .group-head ~ .section-desc { margin-left: 20px; }
+
+.group.is-hidden .group-name, .group.is-hidden .group-count, .group.is-hidden .item { opacity: 0.45; }
+.group.is-hidden .item:hover { opacity: 0.8; }
+
+/* A folded section holding the selected design says so */
+.group.has-selection .group-name { color: var(--x-accent-text); }
+.group.has-selection .group-toggle::after { content: ''; flex: none; width: 6px; height: 6px; margin-left: 3px; border-radius: 50%; background: var(--x-accent); }
+
 .item {
   display: flex;
   align-items: baseline;
@@ -210,10 +314,14 @@ kbd {
 
 /* ---------- The canvas ---------- */
 
+/* clip, not just hidden: a hidden box can still be scrolled, and a design calling scrollIntoView()
+   or focus() scrolls every box around its frame, which would shift the canvas, its toolbar and
+   where the pointer lands. A clipped box can't scroll. */
 .viewport {
   position: relative;
   flex: 1;
   overflow: hidden;
+  overflow: clip;
   touch-action: none;
   background-color: var(--x-canvas);
   background-image: radial-gradient(circle at 1px 1px, var(--x-dot) 1px, transparent 0);
@@ -225,6 +333,7 @@ kbd {
 .viewport.is-space { cursor: grab; }
 
 .world { position: absolute; left: 0; top: 0; transform-origin: 0 0; }
+.world.is-moving { will-change: transform; } /* see setView in explorer.js */
 
 .frame {
   position: absolute;
@@ -239,7 +348,17 @@ kbd {
 /* Designs the search leaves out stay in place, faded. */
 .frame.is-dimmed { opacity: 0.2; }
 
-.overlay { position: absolute; inset: 0; overflow: hidden; pointer-events: none; }
+/* Well off screen: not drawn (see paint in explorer.js) */
+.frame.is-away { content-visibility: hidden; }
+
+/* Zoomed out, a picture of the page over it, and the page not drawn while the picture is up to date
+   (see pictures in explorer.js) */
+.page { position: absolute; inset: 0; }
+.frame.is-still .page { content-visibility: hidden; }
+.picture { position: absolute; inset: 0; display: none; width: 100%; height: 100%; pointer-events: none; user-select: none; }
+.frame.is-picture .picture { display: block; }
+
+.overlay { position: absolute; inset: 0; overflow: hidden; overflow: clip; pointer-events: none; }
 
 .label, .section-title, .outline, .size { position: absolute; left: 0; top: 0; }
 
@@ -259,9 +378,38 @@ kbd {
 
 .section-title { font: 700 20px/24px var(--font-display); letter-spacing: 0.01em; white-space: nowrap; color: var(--x-text); }
 
+/* Zoomed far out, a title goes over the top of its designs: on a backing, so it reads over them */
+.section-title.is-over {
+  margin-left: -5px;
+  padding: 0 5px;
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--x-canvas) 85%, transparent);
+}
+
 .outline--hover { box-shadow: 0 0 0 1px var(--x-accent); }
 .outline--selected { box-shadow: 0 0 0 2px var(--x-accent); }
 
+/* The buttons of the design under the pointer, over its top right corner: copy it, save it */
+.actions {
+  position: absolute;
+  left: 0;
+  top: 0;
+  display: flex;
+  gap: 2px;
+  padding: 2px;
+  border: 1px solid var(--x-line);
+  border-radius: 8px;
+  background: var(--x-glass);
+  backdrop-filter: blur(16px) saturate(1.4);
+  box-shadow: 0 4px 16px rgb(0 0 0 / 0.4);
+}
+
+/* Bridges the gap to the design, so the pointer stays on it on the way to the buttons */
+.actions::after { content: ''; position: absolute; left: 0; right: 0; top: 100%; height: 8px; }
+.actions.is-below::after { top: auto; bottom: 100%; }
+.actions .mini { color: var(--x-text); }
+.actions[aria-busy='true'] .mini { opacity: 0.5; cursor: progress; }
+
 .size {
   padding: 2px 6px;
   border-radius: 4px;
@@ -375,6 +523,36 @@ kbd {
 
 .toast.is-on { opacity: 1; }
 
+/* The canvas with nothing left to show (every section hidden), and the way back */
+.empty {
+  position: absolute;
+  inset: 0 0 64px;
+  display: grid;
+  place-content: center;
+  justify-items: center;
+  gap: 12px;
+  font-size: 14px;
+  color: var(--x-text-soft);
+  pointer-events: none;
+}
+
+.empty p { margin: 0; }
+
+.empty-show {
+  height: 30px;
+  padding: 0 14px;
+  border: 1px solid var(--x-line);
+  border-radius: 15px;
+  background: var(--x-raised);
+  color: var(--x-text);
+  font: inherit;
+  font-size: 13px;
+  cursor: pointer;
+  pointer-events: auto;
+}
+
+.empty-show:hover { border-color: transparent; background: var(--x-accent-wash); color: var(--x-accent-text); }
+
 .notice {
   position: absolute;
   inset: 0;
@@ -403,5 +581,5 @@ kbd {
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .toast { transition: none; }
+  .toast, .group-toggle svg { transition: none; }
 }