@transclude/core 0.4.0 → 0.6.0

package/bin/build.js

@@ -22,8 +22,9 @@ import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
 import { sitemap } from '../src/sitemap.js';
 import { etagOf, loadAssets, loadStatic } from '../src/static-cache.js';
-import { buildSprite, readIcons, refuseSpriteClash, SPRITE_PATH } from '../src/icons.js';
+import { buildSprite, readLibraries, refuseSpriteClash, spritePath } from '../src/icons.js';
 import { PRECACHE_PATH, precacheDocument, precacheList } from '../src/precache.js';
+import { speculateSettings, speculationRules } from '../src/speculate.js';
 import { cookiesOf } from '../src/cookies.js';
 import { pool } from '../src/pool.js';
 import { precompress } from '../src/compress.js';
@@ -171,6 +172,7 @@ async function render(route, { url, params }) {
     stylesheet,
     csp: config.csp,
     lang: config.lang,
+    speculate: speculateRules,
     include,
   });
 
@@ -240,6 +242,32 @@ if (manifest.error) {
   });
 }
 
+// ---- speculation rules ------------------------------------------------------
+//
+// Before the render, because every page carries the block and the pages are
+// about to be rendered. The URLs are already known: `targets` is what will be
+// written and `dynamic` is what will not, and a target that then fails to render
+// fails the build rather than leaving a rule pointing at nothing.
+//
+// Computed once and carried in the manifest, so the server rendering the dynamic
+// routes sends the same block the files carry. Two computations is two answers
+// to what a browser may prerender, and only one of them was ever checked.
+//
+// The split is the whole point. A file has no loader left to run, so
+// prerendering it is free. A server render's loader may read a cookie or count a
+// view, so the browser may fetch that and not run it. The 404 and 500 pages
+// carry a `file` rather than a route URL, which is what keeps them out of both.
+const speculate = speculateSettings(config.speculate);
+const speculateRules = speculate
+  ? speculationRules(
+      {
+        prerendered: targets.filter((entry) => !entry.file).map((entry) => entry.target.url),
+        dynamic: dynamic.map((route) => route.pattern),
+      },
+      speculate,
+    )
+  : null;
+
 const CONCURRENCY = Number(process.env.TRANSCLUDE_BUILD_CONCURRENCY ?? 8);
 
 const outcomes = await pool(targets, CONCURRENCY, async ({ route, target, file, label }) => {
@@ -256,7 +284,6 @@ const outcomes = await pool(targets, CONCURRENCY, async ({ route, target, file,
 
 const failures = outcomes.filter((outcome) => !outcome.ok);
 const prerendered = outcomes.filter((outcome) => outcome.ok).map((outcome) => outcome.url);
-
 // A file, like every other page. The served route answers the same document, but
 // `dist/static` is meant to be servable by a host that runs none of this, and a
 // site with no sitemap there would be missing one only on the host that needs it
@@ -309,6 +336,9 @@ fs.writeFileSync(
       notFound: manifest.notFound ? { id: manifest.notFound.id } : null,
       error: manifest.error ? { id: manifest.error.id } : null,
       stylesheet,
+      // Carried rather than recomputed. The server renders the routes that are
+      // not files, and those pages have to say what the files say.
+      speculate: speculateRules,
     },
     null,
     2,
@@ -356,20 +386,29 @@ function countFiles(dir) {
 // It is not counted as a public file, because the author did not write it.
 //
 // An icon named for a file the author can see is worth a stop: `buildSprite`
-// throws on a missing viewBox or two files claiming one name, and the build ends
-// there rather than shipping icons that render wrong.
+// throws on a missing viewBox, and the build ends there rather than shipping
+// icons that render wrong.
+//
+// One file per library. A downloaded icon set is a directory here, so the count
+// this reports is two numbers: an icon total says nothing about how much any one
+// page fetches, and the sheets are what a page fetches.
 
 const iconsSrc = config.iconsDir ? path.join(root, config.appDir, config.iconsDir) : null;
 let iconCount = 0;
+let libraryCount = 0;
 
 if (iconsSrc) {
-  const icons = readIcons(iconsSrc, root);
-  if (icons.length) {
-    refuseSpriteClash(publicSrc);
-    fs.mkdirSync(publicOut, { recursive: true });
-    fs.writeFileSync(path.join(publicOut, path.basename(SPRITE_PATH)), buildSprite(icons));
-    iconCount = icons.length;
+  const libraries = readLibraries(iconsSrc, root);
+  refuseSpriteClash(publicSrc, libraries);
+
+  if (libraries.length) fs.mkdirSync(publicOut, { recursive: true });
+
+  for (const { name, icons } of libraries) {
+    const file = path.join(publicOut, path.basename(spritePath(name)));
+    fs.writeFileSync(file, buildSprite(icons));
+    iconCount += icons.length;
   }
+  libraryCount = libraries.length;
 }
 
 // ---- assets, for runtimes with no filesystem ------------------------------
@@ -495,7 +534,12 @@ const summary = [
   `${dynamic.length} route${dynamic.length === 1 ? '' : 's'} left to the server`,
   `${assets.size} client entr${assets.size === 1 ? 'y' : 'ies'}`,
   ...(publicFiles ? [`${publicFiles} public file${publicFiles === 1 ? '' : 's'}`] : []),
-  ...(iconCount ? [`${iconCount} icon${iconCount === 1 ? '' : 's'}`] : []),
+  ...(iconCount
+    ? [
+        `${iconCount} icon${iconCount === 1 ? '' : 's'} in ` +
+          `${libraryCount} sheet${libraryCount === 1 ? '' : 's'}`,
+      ]
+    : []),
 ];
 console.log(`\n${summary.join(', ')}`);
 for (const url of prerendered) console.log(`  ${url}`);

package/bin/dev.js

@@ -7,7 +7,7 @@ import http from 'node:http';
 import path from 'node:path';
 import { getRequestListener } from '@hono/node-server';
 import { publicFiles as publicHandler } from '../src/public-files.js';
-import { buildSprite, readIcons, refuseSpriteClash, SPRITE_PATH } from '../src/icons.js';
+import { buildSprite, readLibraries, refuseSpriteClash } from '../src/icons.js';
 import { createServer as createViteServer } from 'vite';
 import {
   ACTION_METHODS,
@@ -66,18 +66,36 @@ const publicFiles =
 const iconsRoot = config.iconsDir ? path.join(root, config.appDir, config.iconsDir) : null;
 
 /**
- * The sprite the build writes, built per request instead.
+ * One library's sprite, built per request rather than read off disk.
  *
  * Reading a directory of small files on every request is what the rest of dev
  * already does, and it is what makes adding an icon show up on reload. A refusal
- * from `buildSprite` is returned as text rather than thrown, so a missing
- * viewBox reads the same here as the message that would stop the build.
+ * is returned as text rather than thrown, so a missing viewBox reads the same
+ * here as the message that would stop the build.
+ *
+ * A name no library answers to is a 404, not an empty sprite. `/lucdie.svg` is a
+ * typo, and a blank icon is a worse way to find that out than a missing file.
  */
-function sprite() {
+function sprite(name) {
   try {
-    const icons = readIcons(iconsRoot, root);
-    refuseSpriteClash(publicRoot);
-    return { status: 200, type: 'image/svg+xml; charset=utf-8', body: buildSprite(icons) };
+    const libraries = readLibraries(iconsRoot, root);
+    refuseSpriteClash(publicRoot, libraries);
+
+    const library = libraries.find((entry) => entry.name === name);
+    if (!library) {
+      const known = libraries.map((entry) => entry.name).join(', ') || 'none';
+      return {
+        status: 404,
+        type: 'text/plain; charset=utf-8',
+        body: `no icon library "${name}". There is: ${known}`,
+      };
+    }
+
+    return {
+      status: 200,
+      type: 'image/svg+xml; charset=utf-8',
+      body: buildSprite(library.icons),
+    };
   } catch (error) {
     return { status: 500, type: 'text/plain; charset=utf-8', body: error.message };
   }
@@ -284,8 +302,12 @@ async function buildApp() {
   // A public file at this URL is refused rather than raced, so registering after
   // `baseApp` costs nothing: the public handler can only fall through to here.
   if (iconsRoot) {
-    app.get(SPRITE_PATH, (c) => {
-      const { status, type, body } = sprite();
+    // Any `/name.svg` at the root, because a library is named by a directory the
+    // author made and dev has no list of them until it reads the disk. The public
+    // handler ran first, so an .svg the author wrote still wins.
+    app.get('/:file{[^/]+\\.svg}', (c) => {
+      const name = c.req.param('file').slice(0, -'.svg'.length);
+      const { status, type, body } = sprite(name);
       return c.body(body, status, { 'content-type': type });
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",

package/skills/transclude/SKILL.md

@@ -37,8 +37,11 @@ app/
     api/_shared.js # not a route, the _ prefix says so
   elements/        # every custom element, one file each
     note-card.html # <note-card>, the name needs a dash
+    svg-icon.html  # scaffolded by npm create, yours to edit
   icons/           # one SVG file per icon, compiled to /icons.svg
     check.svg      # <use href="/icons.svg#check">
+    lucide/        # a subdirectory is a library: /lucide.svg
+      check.svg    # <use href="/lucide.svg#check">
   public/          # copied to the site root as-is
 transclude.config.js
 ```
@@ -168,8 +171,23 @@ shows. The file name is the id.
 <svg width="16" height="16"><use href="/icons.svg#check"></use></svg>
 ```
 
-Every icon file needs a `viewBox`, and two files cannot share a name. The build
-refuses either rather than shipping an icon that renders wrong.
+A subdirectory is a library of its own, served under its name. Put a downloaded
+icon set in whole and reference it by library and name:
+
+```html
+<svg width="16" height="16"><use href="/lucide.svg#check"></use></svg>
+```
+
+Every icon file needs a `viewBox`. A library is one flat directory, so a
+directory inside one is refused. Two libraries may each have a `check`.
+
+A new project has `app/elements/svg-icon.html`, which wraps the `<use>` and gets
+the two aria spellings right. It is the project's file, not the framework's.
+
+```html
+<svg-icon name="check"></svg-icon>
+<svg-icon library="lucide" name="check" label="Mark as done"></svg-icon>
+```
 
 Most apps wrap this in a light element so a page names an icon instead of a URL.
 See [references/elements.md](references/elements.md).
@@ -207,6 +225,12 @@ on something inside it.
 into the DOM it already rendered and never replaces a child. That is a compile
 error naming `shadow`. Add `export const shadow = true` or keep the list still.
 
+**A dialog does not need a click handler.** `command` and `commandfor` are the
+platform's invoker: `<button command="show-modal" commandfor="prefs">` opens
+`<dialog id="prefs">` with no script. Writing a listener for this is the common
+mistake, and it loses the keyboard and screen reader behavior the attributes
+already carry.
+
 **`setHTMLUnsafe()`, never `innerHTML`.** `innerHTML` does not process nested
 declarative shadow roots, so a child element becomes a dead `<template>`.
 

package/skills/transclude/references/elements.md

@@ -125,6 +125,35 @@ schedules the render, the way an attribute change does for a prop.
 </script>
 ```
 
+## Styling on state
+
+A boolean state field is reflected as a custom state, so CSS can select it. No
+attribute is written and no class is added, which is the point: the document
+still cannot read the state, and a stylesheet still reacts to it.
+
+```html
+<script state>
+  export default {
+    hot: false,
+  };
+</script>
+
+<style>
+  :scope:state(hot) output {
+    color: #b4232c;
+  }
+</style>
+
+<output>${n}</output>
+```
+
+Booleans only. A custom state is a name and not a value, so a number or a string
+has nothing to select on. The state lands with the render rather than with the
+assignment, so `await element.updateComplete` before asserting on it.
+
+Nothing is reflected on the server. A state field starts at the default its
+block declares, so the first paint is that default either way.
+
 ## Behavior
 
 A plain `<script>` block is the element's own code. `host` is the element,
@@ -188,13 +217,15 @@ rest of them.
 
 ## An icon element
 
-The framework compiles `app/icons/` into one `/icons.svg` and ships no element
-for it. This is the one most apps write, and it is worth copying rather than
-inventing.
+The framework compiles `app/icons/` into one `/icons.svg` and defines no element
+for it. `npm create @transclude` writes this file into a new project, so it is
+already there and it belongs to the project. Reproduced here for a project that
+predates it, or one that deleted it.
 
 ```html
 <script properties>
   export default {
+    library: 'icons',
     name: '',
     label: '',
   };
@@ -211,10 +242,14 @@ inventing.
   }
 </style>
 
-<svg if="label" role="img" aria-label="${label}"><use href="/icons.svg#${name}"></use></svg>
-<svg else aria-hidden="true"><use href="/icons.svg#${name}"></use></svg>
+<svg if="label" role="img" aria-label="${label}"><use href="/${library}.svg#${name}"></use></svg>
+<svg else aria-hidden="true"><use href="/${library}.svg#${name}"></use></svg>
 ```
 
+`library` is the directory in `app/icons/`, and `icons` is the files loose at the
+top. `<svg-icon library="lucide" name="check">` draws
+`app/icons/lucide/check.svg`.
+
 `<svg-icon name="check">` is decorative and hidden from a screen reader, which is
 right when the icon sits beside its own label. `<svg-icon name="check"
 label="Mark as done">` is announced, which is what a control holding nothing but

package/skills/transclude/references/server.md

@@ -85,7 +85,7 @@ Source is JavaScript with JSDoc. Do not convert it to TypeScript.
 | `appDir` | `'app'` | Where the app lives, relative to the project root. |
 | `routesDir` | `'routes'` | Pages and endpoints. Relative to `appDir`. |
 | `elementsDir` | `'elements'` | Custom elements. Relative to `appDir`. |
-| `iconsDir` | `'icons'` | One SVG file per icon, compiled to `/icons.svg`. Relative to `appDir`. |
+| `iconsDir` | `'icons'` | One SVG file per icon, compiled to `/icons.svg`. A subdirectory is a library at `/<name>.svg`. Relative to `appDir`. |
 | `publicDir` | `'public'` | Copied to the site root as-is. Relative to `appDir`. |
 | `outDir` | `'dist'` | Where the build writes. |
 | `stylesheet` | — | One global stylesheet, relative to the project root. |
@@ -94,6 +94,7 @@ Source is JavaScript with JSDoc. Do not convert it to TypeScript.
 | `strict` | `false` | Full TypeScript strictness. |
 | `csrf` | `true` | `false` to turn it off, or an object for `hono/csrf`. |
 | `csp` | `false` | `true`, or `{ directives, reportOnly }`. |
+| `speculate` | `false` | `true` emits speculation rules. See below. |
 | `cookieSecret` | `null` | Signs cookies. |
 | `fragmentParam` | `'fragment'` | The query parameter that asks for a fragment. |
 | `fragmentHeader` | `null` | A request header that may name one. Adds it to `Vary`. |
@@ -106,6 +107,27 @@ Source is JavaScript with JSDoc. Do not convert it to TypeScript.
 | `precache` | `false` | `true` writes `/precache.json`. |
 | `onError` | `null` | `(error, { request, url, method })` per failed request. |
 
+
+### speculate
+
+`true` writes a `<script type="speculationrules">` block into every page, so the
+browser can fetch or render the next document before the reader clicks. No
+JavaScript of the framework's is involved.
+
+The split matters and the build decides it. A URL prerendered to a file has no
+loader left to run, so it goes in `prerender`. Every route the server still
+renders goes in `prefetch` only, because its loader may read a cookie or count a
+view and a prerender would run that for a reader who never clicked. Endpoints are
+in neither.
+
+```js
+speculate: { eagerness: 'moderate', exclude: ['/logout'] }
+```
+
+`eagerness` defaults to `moderate`, which waits for a hover. `exclude` is matched
+against the emitted pattern, so a route `/docs/:path{.+}` is excluded as
+`/docs/*`.
+
 ## The build
 
 ```sh

package/src/app.js

@@ -340,6 +340,9 @@ export function createApp({
                 stylesheet: manifest.stylesheet,
                 csp: config.csp,
                 lang: config.lang,
+                // Written by the build and carried here, so a server-rendered
+                // page says the same thing about speculation that a file does.
+                speculate: manifest.speculate ?? null,
                 include,
               })
             : await renderFragment(page, ctx, { region: region || null, include });
@@ -408,6 +411,7 @@ export function createApp({
             stylesheet: manifest.stylesheet,
             csp: config.csp,
             lang: config.lang,
+            speculate: manifest.speculate ?? null,
             include,
           });
 

package/src/document.js

@@ -566,13 +566,14 @@ export function methodsOf(page) {
  *
  * @param {object[]} chain the compiled modules, outermost first
  * @param {object[]} datas one per level, in the same order
- * @param {{ clientEntry?: string|null, stylesheet?: string|null, lang?: string }} [options]
+ * @param {{ clientEntry?: string|null, stylesheet?: string|null, lang?: string,
+ *   speculate?: string|null }} [options]
  * @returns {string} the document, starting at `<!doctype html>`
  */
 export function renderDocument(
   chain,
   datas,
-  { clientEntry, stylesheet, lang = 'en' } = {},
+  { clientEntry, stylesheet, lang = 'en', speculate = null } = {},
 ) {
   // Each level renders to a slot map and hands it to the level above, so a page
   // can fill more than one hole in its layout.
@@ -641,6 +642,7 @@ ${openTag('html', { lang, ...attrsOf(chain, datas, 'renderHtmlAttrs') })}
 <meta charset="utf-8">
 ${defaults}
 ${title}
+${speculate ? `<script type="speculationrules">${speculate}</script>` : ''}
 ${headScripts.join('\n')}
 ${stylesheet ? `<link rel="stylesheet" href="${stylesheet}">` : ''}
 ${head.join('\n')}

package/src/icons.js

@@ -1,18 +1,24 @@
-// A directory of SVG files, as one sprite.
+// A directory of SVG files, as one sprite. A directory of those, as several.
 //
 // An icon stays a file the author manages: `app/icons/check.svg` is a whole SVG
 // document they can open, edit and diff. What a browser wants is the other
 // shape, one file of `<symbol>`s, so `<use href="/icons.svg#check">` costs one
 // cached request however many icons a page shows.
 //
+// A subdirectory is a library, and it is the case people arrive with: an icon
+// set is downloaded as a folder of files, and the way to use it should be to put
+// the folder here. `app/icons/lucide/check.svg` is `/lucide.svg#check`, and
+// nothing was renamed to get there. Loose files at the top are the `icons`
+// library, which is why the default sheet keeps the name it had.
+//
 // Build-time only, like `public-files.js` and outside the portable core: the
 // sprite is bytes on disk by the time any server answers for it. `buildSprite`
 // takes contents rather than a directory anyway, so the half that decides what
 // the markup is can be tested without fixtures.
 //
-// The dev server and the build both call `readIcons` then `buildSprite`. They
-// used to be the same two lines written twice, which is how `/icons.svg` served
-// in production and 404'd in dev.
+// The dev server and the build both call `readLibraries` then `buildSprite`.
+// They used to be the same two lines written twice, which is how `/icons.svg`
+// served in production and 404'd in dev.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -20,8 +26,23 @@ import { parse, serializeOuter } from 'parse5';
 
 const SVG_NS = 'http://www.w3.org/2000/svg';
 
-/** Where the sprite is served. Fixed, because `<use href>` is written by hand. */
-export const SPRITE_PATH = '/icons.svg';
+/**
+ * What loose files at the top of `app/icons/` are called.
+ *
+ * It is the name the one sheet already had, so a project that never makes a
+ * subdirectory sees the URL it always saw.
+ */
+export const DEFAULT_LIBRARY = 'icons';
+
+/**
+ * Where a library is served. At the site root, beside the author's public files,
+ * because `<use href>` is written by hand and `/lucide.svg` is what someone
+ * guesses.
+ *
+ * @param {string} library
+ * @returns {string}
+ */
+export const spritePath = (library) => `/${library}.svg`;
 
 /**
  * Root attributes that must not survive into a `<symbol>`.
@@ -122,53 +143,101 @@ export function buildSprite(icons) {
 }
 
 /**
- * Refuses a hand-written public file at the sprite's URL.
+ * Refuses a hand-written public file at a library's URL.
  *
- * Two things would answer for `/icons.svg`, and the two servers pick different
+ * Two things would answer for `/lucide.svg`, and the two servers pick different
  * winners: the build copies the public directory first and writes the sprite
  * over it, while dev asks the public handler first and never reaches the sprite.
  * Rather than pick one, neither runs until the author has.
  *
+ * Every library is checked, not just the default one. A library is named by a
+ * directory the author made, so the set of URLs this claims grows with their
+ * tree rather than being one name written down here.
+ *
  * @param {string|null} publicDir the author's public directory, not the copy
- * @throws when a file already sits at the sprite's URL
+ * @param {Array<{ name: string }>} libraries
+ * @throws when a file already sits at a library's URL
  */
-export function refuseSpriteClash(publicDir) {
+export function refuseSpriteClash(publicDir, libraries) {
   if (!publicDir) return;
 
-  const clash = path.join(publicDir, path.basename(SPRITE_PATH));
-  if (!fs.existsSync(clash)) return;
+  for (const { name } of libraries) {
+    const url = spritePath(name);
+    const clash = path.join(publicDir, path.basename(url));
+    if (!fs.existsSync(clash)) continue;
+
+    throw new Error(
+      `[transclude] ${clash} and the ${name} icons both answer for ${url}. ` +
+        `The sprite is built from the icons, so rename the public file or delete it.`,
+    );
+  }
+}
+
+/** The icon files directly inside `dir`, ignoring anything that is not an SVG. */
+function iconsIn(dir, root) {
+  const icons = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() || !entry.name.endsWith('.svg')) continue;
 
-  throw new Error(
-    `[transclude] ${clash} and the icons directory both answer for ${SPRITE_PATH}. ` +
-      `The sprite is built from the icons, so rename the public file or delete it.`,
-  );
+    const full = path.join(dir, entry.name);
+    icons.push({
+      id: path.basename(entry.name, '.svg'),
+      file: path.relative(root, full),
+      svg: fs.readFileSync(full, 'utf8'),
+    });
+  }
+  return icons;
 }
 
 /**
- * Every `.svg` under `dir`, ready for `buildSprite`.
+ * Every library under `dir`, each ready for `buildSprite`.
  *
- * Nested directories are read, and an icon is still named by its file alone, so
- * `ui/check.svg` and `nav/check.svg` collide. `buildSprite` says so by name.
- * Sorting is left to it, so one directory reads the same on any filesystem.
+ * Loose files at the top are the default library. Each subdirectory is a library
+ * of its own, named by the directory, which is what makes dropping a downloaded
+ * icon set in here the whole of using it.
+ *
+ * One level. A directory inside a library is refused rather than flattened or
+ * skipped: flattening would give two files one id, and skipping loses icons
+ * without saying so. Sorted, so a build reads the same on any filesystem.
  *
  * @param {string} dir
  * @param {string} [root] what the reported file paths are relative to
- * @returns {Array<{ id: string, file: string, svg: string }>} empty if `dir` is absent
+ * @returns {Array<{ name: string, icons: Array<{ id: string, file: string, svg: string }> }>}
+ *   empty if `dir` is absent, and a library with no icons in it is not one
+ * @throws when a library holds a directory
  */
-export function readIcons(dir, root = dir) {
+export function readLibraries(dir, root = dir) {
   if (!fs.existsSync(dir)) return [];
 
-  const icons = [];
+  const libraries = [];
+
+  const loose = iconsIn(dir, root);
+  if (loose.length) libraries.push({ name: DEFAULT_LIBRARY, icons: loose });
+
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
     const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) icons.push(...readIcons(full, root));
-    else if (entry.name.endsWith('.svg')) {
-      icons.push({
-        id: path.basename(entry.name, '.svg'),
-        file: path.relative(root, full),
-        svg: fs.readFileSync(full, 'utf8'),
-      });
-    }
+    refuseNesting(full, root);
+
+    const icons = iconsIn(full, root);
+    if (icons.length) libraries.push({ name: entry.name, icons });
+  }
+
+  return libraries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/** A library is a flat directory. Anything deeper has no name to be served under. */
+function refuseNesting(dir, root) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const inner = path.relative(root, path.join(dir, entry.name));
+    throw new Error(
+      `[transclude] ${inner} is a directory inside a library, and a library is ` +
+        `one flat directory of icons. Move it up to be a library of its own, or ` +
+        `flatten it into the one it is in.`,
+    );
   }
-  return icons;
 }

package/src/project.js

@@ -96,6 +96,7 @@ const DEFAULTS = {
   strict: false,
   csrf: true,
   csp: false,
+  speculate: false,
 };
 
 /**

package/src/runtime/index.js

@@ -986,7 +986,10 @@ export function defineLight(def, init) {
 
     constructor() {
       super();
-      if (def.formAssociated) this.#internals = this.attachInternals();
+      // Also when a boolean state can be reflected. Narrow on purpose: internals
+      // is attached for the thing that needs it and not for every element that
+      // happens to hold a number.
+      if (def.formAssociated || hasCustomStates(def)) this.#internals = this.attachInternals();
     }
 
     get internals() {
@@ -1059,6 +1062,9 @@ export function defineLight(def, init) {
 
     #data(raw) {
       this.#was = { ...stateOf(this, def.stateDefs) };
+      // The one place both classes work out current state, so the one place a
+      // custom state can be kept true without a third copy of the rule.
+      reflectStates(this.#internals, def.stateDefs, this.#was);
       return { ...this.#was, ...def.coerce(raw) };
     }
 
@@ -1088,6 +1094,41 @@ function hasMembers(def) {
   return Object.keys(def.members ?? {}).length > 0;
 }
 
+/**
+ * A boolean state field, as a custom state CSS can select.
+ *
+ * `:state(open)` rather than an attribute, which is the whole reason state is
+ * not in the document: the page has no business reading it, and CSS still has
+ * to be able to react to it. Booleans only, because a custom state is a name
+ * and not a value.
+ *
+ * Nothing is reflected on the server. A state field always starts at its
+ * declared default, so the first paint is the default either way and there was
+ * never anything for the markup to say.
+ */
+function reflectStates(internals, defs, state) {
+  if (!internals?.states) return;
+
+  for (const name of Object.keys(defs ?? {})) {
+    const value = state[name];
+    if (typeof value !== 'boolean') continue;
+
+    if (value) internals.states.add(name);
+    else internals.states.delete(name);
+  }
+}
+
+/**
+ * Whether any state field is declared a boolean.
+ *
+ * The declared default decides, at define time. A custom state is a name and
+ * not a value, so a number or a string has nothing to reflect, and an element
+ * holding only those is left without internals it would never use.
+ */
+function hasCustomStates(def) {
+  return Object.values(def.stateDefs ?? {}).some((value) => typeof value === 'boolean');
+}
+
 /** State counts as behavior: its accessors are the only way to change it. */
 function hasState(def) {
   return Object.keys(def.stateDefs ?? {}).length > 0;
@@ -1202,7 +1243,10 @@ export function defineComponent(def, init) {
       super();
       // In the constructor, which is where it belongs and where it can only
       // happen once. For a server-rendered element that is upgrade time.
-      if (def.formAssociated) this.#internals = this.attachInternals();
+      // Also when a boolean state can be reflected. Narrow on purpose: internals
+      // is attached for the thing that needs it and not for every element that
+      // happens to hold a number.
+      if (def.formAssociated || hasCustomStates(def)) this.#internals = this.attachInternals();
     }
 
     /** What this element would submit, if it is a control. */
@@ -1308,6 +1352,9 @@ export function defineComponent(def, init) {
      *  be hidden by one. The compiler rejects that clash anyway. */
     #data(raw) {
       this.#was = { ...stateOf(this, def.stateDefs) };
+      // The one place both classes work out current state, so the one place a
+      // custom state can be kept true without a third copy of the rule.
+      reflectStates(this.#internals, def.stateDefs, this.#was);
       return { ...this.#was, ...def.coerce(raw) };
     }
 

package/src/speculate.js

@@ -0,0 +1,103 @@
+// What the browser may fetch, or run, before the reader clicks.
+//
+// This framework ships no client router: every link is a document request. That
+// is the whole bet, and the cost of it is one round trip per navigation.
+// Speculation rules are the platform's answer, and they cost no JavaScript of
+// ours: a JSON block in the head, and the browser decides.
+//
+// The part worth writing down is what must *not* be speculated. A prerender
+// runs the page. A route this build wrote to a file has no loader left to run,
+// so prerendering it is free and safe. Everything else is a server render whose
+// loader may read a cookie, count a view or hand out a one-time token, and
+// prerendering that for a reader who never clicked is wrong rather than slow.
+// The build knows which is which. A hand-written rules block does not.
+//
+// No `node:` imports. The build calls this with the lists it already holds.
+
+/** What the spec allows, so a typo is caught here rather than ignored by Chrome. */
+const EAGERNESS = new Set(['immediate', 'eager', 'moderate', 'conservative']);
+
+/**
+ * A route pattern as something `href_matches` understands.
+ *
+ * Hono writes `/docs/:path{.+}` and `/people/:name`. Both become `*`: the regex
+ * half is Hono's own spelling and means nothing to a URL pattern, and a rule
+ * that matches too little is a missed prefetch while one that matches too much
+ * speculates a URL that 404s.
+ *
+ * @param {string} pattern
+ * @returns {string}
+ */
+export function hrefPattern(pattern) {
+  return pattern.replace(/:[A-Za-z0-9_]+(\{[^}]*\})?/g, '*');
+}
+
+/** `{ href_matches }` for each, or null when there is nothing to match. */
+function where(patterns) {
+  if (!patterns.length) return null;
+  return { or: patterns.map((pattern) => ({ href_matches: pattern })) };
+}
+
+/**
+ * The `<script type="speculationrules">` body for a site, or null.
+ *
+ * Two lists, because they are two different promises. `prerendered` is every URL
+ * written to a file, and the browser may run those. `dynamic` is every route the
+ * server still renders, and the browser may only fetch those: the response is
+ * the same document a click would have got, and no page script runs early.
+ *
+ * Endpoints are in neither. A `.js` route answers with whatever it builds, and
+ * speculating one spends a request on something no navigation will reuse.
+ *
+ * @param {object} site
+ * @param {string[]} [site.prerendered] URLs written to a file
+ * @param {string[]} [site.dynamic] route patterns the server renders
+ * @param {object} [options]
+ * @param {string[]} [options.exclude] patterns to leave out of both
+ * @param {string} [options.eagerness] how soon the browser may act
+ * @returns {string|null} JSON, or null when nothing is speculated
+ * @throws when `eagerness` is not one the spec names
+ */
+export function speculationRules({ prerendered = [], dynamic = [] }, options = {}) {
+  const { exclude = [], eagerness = 'moderate' } = options;
+
+  if (!EAGERNESS.has(eagerness)) {
+    throw new Error(
+      `[transclude] speculate.eagerness is ${JSON.stringify(eagerness)}. ` +
+        `It is one of ${[...EAGERNESS].join(', ')}.`,
+    );
+  }
+
+  const excluded = new Set(exclude);
+  const keep = (pattern) => !excluded.has(pattern);
+
+  // Sorted and deduplicated, so two builds of one site produce the same bytes
+  // and the CSP hash of this block does not change for no reason.
+  const clean = (list) => [...new Set(list)].filter(keep).sort();
+
+  const rules = {};
+  // A prerendered URL is already a URL. A route is a pattern, and `exclude` is
+  // matched against what comes out, so what an author writes is what they read
+  // in the emitted rules.
+  const run = where(clean(prerendered));
+  const fetchOnly = where(clean(dynamic.map(hrefPattern)));
+
+  if (run) rules.prerender = [{ where: run, eagerness }];
+  if (fetchOnly) rules.prefetch = [{ where: fetchOnly, eagerness }];
+
+  return run || fetchOnly ? JSON.stringify(rules) : null;
+}
+
+/**
+ * `speculate` as `{ exclude, eagerness }`, or null for off.
+ *
+ * Off by default, like every other thing here that changes what a browser is
+ * told to do. `true` is the defaults.
+ *
+ * @param {boolean|object} [setting]
+ * @returns {object|null}
+ */
+export function speculateSettings(setting) {
+  if (!setting) return null;
+  return setting === true ? {} : setting;
+}