tosijs-ui 1.16.21 → 1.16.23

package/dist/doc-system/site/dev-auth.js

@@ -646,7 +646,17 @@ export function isSameOriginRequest(request) {
 export function mayWriteSource(opts) {
     if (opts.viaTunnel)
         return opts.hasValidSession && opts.sessionMayWrite !== false;
-    return isLoopbackAddressForAuth(opts.peer);
+    if (isLoopbackAddressForAuth(opts.peer))
+        return true;
+    /*
+    LAN trust leans on the same-origin check the caller applies (`isSameOriginRequest`), and that
+    check rules out DNS rebinding from a LAN browser only because the dev server is HTTPS-only,
+    with a certificate for localhost and <host>.local: a rebound hostname fails TLS. A plain-HTTP
+    listener would turn this into a rebinding path. Do not add one without revisiting this.
+    */
+    return (opts.trustLan === true &&
+        opts.proxied !== true &&
+        isPrivateNetworkAddress(opts.peer));
 }
 /**
  * May the holder of this session token write?
@@ -682,7 +692,10 @@ export function cookieMayWrite(state, cookieValue) {
  * diverge, this is the one place to change, and every caller already says which it means.
  */
 export function mayDriveWithAgent(opts) {
-    return mayWriteSource(opts);
+    // LAN trust (#227) is for reading and editing source, and is never passed here: driving a
+    // page with an agent stays this machine and authorized tunnel sessions only.
+    const { viaTunnel, peer, hasValidSession } = opts;
+    return mayWriteSource({ viaTunnel, peer, hasValidSession });
 }
 /**
  * THE loopback test. dev-server re-exports this as `isLoopbackAddress`; it used to
@@ -703,6 +716,31 @@ export function isLoopbackAddressForAuth(address) {
     const mapped = a.startsWith('::ffff:') ? a.slice(7) : a;
     return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(mapped);
 }
+/**
+ * A private-network peer: RFC 1918 IPv4 (10/8, 172.16/12, 192.168/16), IPv6 unique-local
+ * (fc00::/7) or link-local (fe80::/10), including IPv4 mapped into IPv6. Loopback is not
+ * included; ask `isLoopbackAddressForAuth` for that. Used ONLY behind the `trustLan` opt-in.
+ */
+export function isPrivateNetworkAddress(address) {
+    if (!address)
+        return false;
+    const a = address
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, '')
+        .replace(/%.*$/, ''); // an IPv6 zone id (fe80::1%en0)
+    const v4 = (a.startsWith('::ffff:') ? a.slice(7) : a).match(/^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/);
+    if (v4) {
+        const [first, second] = [Number(v4[1]), Number(v4[2])];
+        return (first === 10 ||
+            (first === 172 && second >= 16 && second <= 31) ||
+            (first === 192 && second === 168));
+    }
+    if (!a.includes(':'))
+        return false;
+    const head = parseInt(a.split(':')[0] || '0', 16);
+    return (head & 0xfe00) === 0xfc00 || (head & 0xffc0) === 0xfe80;
+}
 /*
 Was this request proxied (i.e. did it arrive through something in front of us)?
 

package/dist/doc-system/site/dev-server.js

@@ -1899,6 +1899,8 @@ export async function devServer(config, opts = {}) {
                 // A share link's session may browse and may not save (asked AFTER validity, which
                 // is the call-order `cookieMayWrite` documents).
                 sessionMayWrite: cookieMayWrite(auth, session),
+                trustLan: config.trustLan === true,
+                proxied: isProxiedRequest(request.headers),
             }) &&
                 /*
                 CSRF (#90). The direct path is peer-address-only, so without this any page the
@@ -1908,7 +1910,9 @@ export async function devServer(config, opts = {}) {
                 */
                 csrfOk(request, viaTunnel);
             if (!authorized) {
-                console.warn(`⚠️  refused ${request.method} /__docstore/source from ${peer ?? 'unknown'} — ` + `no session (use \`${TUNNEL_LINK_CMD}\` for an edit link).`);
+                console.warn(`⚠️  refused ${request.method} /__docstore/source from ${peer ?? 'unknown'} — ` +
+                    `no session (use \`${TUNNEL_LINK_CMD}\` for an edit link` +
+                    `${config.trustLan ? '' : ', or set trustLan: true for LAN devices'}).`);
                 return new Response('not authorized to edit source', {
                     status: 403,
                     headers: { 'Content-Type': 'text/plain; charset=utf-8' },
@@ -2225,6 +2229,14 @@ export async function devServer(config, opts = {}) {
         process.exit(code);
     };
     console.log(`Listening on https://localhost:${PORT}`);
+    // trustLan widens who may write; say so every launch, never silently (#227).
+    if (config.trustLan && config.editableSources) {
+        console.warn(`⚠️  trustLan: any device on a private network that can reach this machine may read and ` +
+            `edit source. Use it on a network you control.`);
+    }
+    else if (config.trustLan) {
+        console.warn(`⚠️  trustLan does nothing without editableSources: true (there is no source endpoint to trust).`);
+    }
     if (SINK_PATH) {
         console.log(`Debug sink: POST /__debug-sink  ->  tail -f ${SINK_PATH}`);
     }

package/dist/doc-system/site/docs.d.ts

@@ -22,6 +22,18 @@ export interface Doc {
      * pre-rendered public page — so "drafts don't ship" was false twice over.
      */
     hidden?: boolean;
+    /**
+     * This doc is the site root (`/`) instead of README, which then gets `/readme/`. Set by the
+     * site's `home` option, or by the doc's own `{"home": true}`. At most one doc may be home.
+     */
+    home?: boolean;
+    /**
+     * `false` drops the site's header bar on this page, as `layout: "full-screen"` drops the
+     * nav: for an app page with its own toolbar, above all as an installed PWA, where the bar
+     * is the only thing between the app and the whole screen. The page links back to the docs
+     * its own way; the builder adds nothing. Unset means the header shows.
+     */
+    header?: boolean;
     /**
      * Which book(s) this doc binds into. A name, a list of names, or `'none'` to keep it
      * on the site and out of every book. Unset means the default book; `'default'` names
@@ -91,6 +103,8 @@ export interface ExtractDocsOptions {
     paths: string[];
     ignore?: string[];
     output?: string;
+    /** the doc served at `/` instead of README, by slug or filename (the site's `home`) */
+    home?: string;
 }
 /**
  * The title a markdown file implies, when nothing declares one.

package/dist/doc-system/site/docs.js

@@ -1,97 +1,43 @@
 /*#
 # docs
 
-Utility for extracting documentation from markdown files and inline comments in source code.
-
-> `docs.ts` is intended to be run directly using `bun`. You can transpile it to javascript if you
-want to run it using node.
-
-This is used by the `doc-browser` component to build searchable, navigable documentation
-from your project's source files.
+`extractDocs` collects documentation from markdown files and `/*#` comment blocks in source
+code into one corpus, the `docs.json` that the [doc-browser](/doc-browser/) and the static
+site render. `tosijs-ui/site` runs it for you; call it yourself only to build a corpus
+outside that pipeline. It reads files, so it runs under bun or node.
 
 ## Usage
 
-    import { extractDocs } from 'docs'
-
-    extractDocs({
-      paths: ['src', 'README.md'],
-      ignore: ['node_modules', 'dist', 'build']
-      path: 'public/docs.json'
-    })
-
-## API
-
-### `extractDocs(options)`
-
-Scans directories for markdown files and source code comments.
-
-**Options:**
-- `paths`: Array of directory paths or file paths to scan
-- `ignore`: Array of directory names to ignore (default: ['node_modules', 'dist'])
-- `output`: if provided, path to write json result.
-
-**Returns:** Array of `Doc` objects
-
-### `Doc` object structure
-
-    {
-      text: string,        // Markdown content
-      title: string,       // First heading or filename
-      filename: string,    // Just the filename
-      path: string,        // Full file path
-      pin?: 'top' | 'bottom'  // Optional pinning for sort order
-    }
-
-## Documentation Format
-
-### Markdown files
-
-Any `.md` file will be included in its entirety.
-
-### Source code comments
+```typescript
+import { extractDocs } from 'tosijs-ui/site'
 
-Multi-line comments that start with `/*#` will be extracted as markdown:
+const docs = extractDocs({
+  paths: ['src', 'README.md'],
+  output: 'public/docs.json',
+})
+```
 
-    /*#
-    # My Component
+## `extractDocs(options)`
 
-    This is documentation for my component.
+- `paths`: directories to scan, and individual files (list root `.md` files explicitly)
+- `ignore`: directory names to skip (default `['node_modules', 'dist', 'build']`)
+- `output`: if given, the path the corpus is written to as JSON
+- `home`: the doc served at `/` instead of README, by slug or filename
 
-    ```html
-    <my-component></my-component>
-    ```
-    ```js
-    console.log('hello world')
-    ```
-    ```css
-    my-componet {
-      color: blue
-    }
-    ```
-    *‎/
-
-    export class MyComponent extends Component {
-      // implementation
-    }
-    ...
-
-The [doc-browser](/?doc-browser.ts) will render the output as a test-bed project with documentation and live examples.
+Returns an array of `Doc` objects: `text` (the markdown), `title`, `filename`, `path`, and
+whatever metadata the doc declares (`pin`, `order`, `parent`, `layout`, `description`, …).
 
-### Metadata
+## What is collected
 
-You can include JSON metadata in comments to control sorting:
+- **`.md` files**, whole. YAML frontmatter is read and removed.
+- **`/*#` … `*‎/` blocks** in `.ts`, `.tjs`, `.js` and `.css` files, as markdown. The first heading
+  is the page title. A block counts only when `/*#` starts a line.
+- **Files whose name starts with `_`** are skipped: use the prefix for drafts and fragments.
 
-html:
-    <!--{ "pin": "bottom" }-->
-
-ts, js, css:
-    /*{ "pin": "bottom" }*‎/
-
-This pins the document to the top or bottom of the navigation list. Within a
-pin bucket, add `"order"` (a number, lower first; default 500) to rank items —
-e.g. `{ "pin": "top", "order": 1 }` above `{ "pin": "top", "order": 2 }`.
+Metadata blocks (`<!--{ … }-->` in markdown, `/*{ … }*‎/` in code), nav order, sections and
+which code fences run live are described under [Doc format](/doc-site-system/#doc-format).
 */
-/*{"pin":"bottom","parent":"Appendices"}*/
+/*{ "parent": "Documentation System", "order": 60 }*/
 // TODO CLI options
 import * as fs from 'fs';
 import * as path from 'path';
@@ -208,6 +154,14 @@ export function parseFrontmatter(content) {
             else if (val)
                 console.error(`unknown layout ${JSON.stringify(val)} in frontmatter`);
         }
+        else if (key === 'header') {
+            if (/^(false|no|0)$/i.test(val))
+                data.header = false;
+        }
+        else if (key === 'home') {
+            if (/^(true|yes|1)$/i.test(val))
+                data.home = true;
+        }
     }
     if (!matched)
         return { data: {}, body: content }; // a bare `---`, not frontmatter
@@ -513,7 +467,7 @@ walked) {
     return markdownFiles.sort(pinnedSort);
 }
 export function extractDocs(options) {
-    const { paths, ignore = ['node_modules', 'dist', 'build'], output } = options;
+    const { paths, ignore = ['node_modules', 'dist', 'build'], output, home, } = options;
     const walked = new Set();
     const found = findMarkdownFiles(paths, ignore, new Set(DEFAULT_DOC_IGNORES), walked);
     /*
@@ -529,7 +483,18 @@ export function extractDocs(options) {
     Filtering at extraction makes it structural: hidden docs do not exist as far as the
     rest of the pipeline is concerned. Descendants of a hidden doc go with it.
     */
+    if (home != null)
+        markHome(found, home);
+    const homes = found.filter((doc) => doc.home);
+    if (homes.length > 1) {
+        throw new Error(`more than one doc is the home page: ${homes
+            .map((doc) => doc.path)
+            .join(', ')}. Mark one, with the site's \`home\` option or {"home": true}.`);
+    }
     const docs = withoutHidden(found, buildSlugMap(found));
+    if (homes.length === 1 && !docs.includes(homes[0])) {
+        throw new Error(`the home page ${homes[0].path} is hidden, so the site would have no root page.`);
+    }
     /*
     Insets and conditional text are resolved HERE, for the same reason hidden docs are dropped
     here: the corpus is the thing that ships, so anything assembled later is assembled by each
@@ -550,6 +515,21 @@ export function extractDocs(options) {
     }
     return docs;
 }
+/*
+The site's `home` option names the root doc by slug or filename. Matched against the slugs
+the corpus would have with README as root, which are the names an author sees in the nav
+today. Naming nothing fails the build: a site whose root is not the page its config asks for
+is the silent-failure class this system refuses.
+*/
+function markHome(docs, home) {
+    const slugs = buildSlugMap(docs.map(({ filename }) => ({ filename })));
+    const wanted = home.replace(/^\/+|\/+$/g, '');
+    const match = docs.filter((doc) => doc.filename === wanted || slugs[doc.filename] === wanted);
+    if (match.length !== 1) {
+        throw new Error(`site option home: "${home}" names ${match.length === 0 ? 'no doc' : `${match.length} docs`}. Use a page's slug (as in its URL) or its filename.`);
+    }
+    match[0].home = true;
+}
 export function saveDocsJSON(docs, outputPath) {
     const jsonData = JSON.stringify(docs, null, 2);
     fs.writeFileSync(outputPath, jsonData, 'utf8');

package/dist/doc-system/site/epub.js

@@ -620,7 +620,8 @@ export async function buildEpub(config, opts = {}) {
     docs and anything marked `book: "none"`, so a doc that belongs to no volume cannot leak
     into the default one just by not naming a book.
     */
-    const volumes = partitionByBook(corpus, buildSlugMap(corpus));
+    const siteSlugs = buildSlugMap(corpus);
+    const volumes = partitionByBook(corpus, siteSlugs);
     const visible = volumes.get(opts.bookTarget ?? DEFAULT_BOOK) ?? [];
     /*
     A volume with no chapters is a failure, not a book.
@@ -659,7 +660,10 @@ export async function buildEpub(config, opts = {}) {
     }
     // Curate/reorder for the book (a no-op when config.book is absent).
     const docs = selectBookDocs(placed, config.book);
-    const slugMap = buildSlugMap(docs);
+    // Slugs come from the whole published corpus, as the site's do: computed from this book's
+    // subset, README would take the root whenever the site's `home` doc is outside the book,
+    // and the book's links would disagree with the site's URLs.
+    const slugMap = siteSlugs;
     const roots = buildNavTree(docs, slugMap);
     const fileFor = (d) => `${slugMap[d.filename] || 'index'}.xhtml`;
     // slug → chapter filename, for the docs actually IN this book — the target set for

package/dist/doc-system/site/generate-site.js

@@ -15,7 +15,7 @@ import { highlightHtml } from '../highlight.js';
 import { buildSlugMap, pathForSlug, rewriteDocLinks, withBase, } from '../routing.js';
 import { buildNavTree, navOpenPath } from '../nav-tree.js';
 import { renderDocMarkdown, docDescription, } from '../render.js';
-import { deadInPageAnchors, misconfigured } from './build-warnings.js';
+import { bareNameLinks, deadInPageAnchors, misconfigured, } from './build-warnings.js';
 const escapeAttr = (s) => s
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -127,9 +127,8 @@ async function pageHtml(doc, config, slugMap, configAttr) {
     flicker the nav-hydration fix chased in 1.7.3. An attribute in the served markup means the
     first paint is already correct, and the doc-browser keeps it in step on SPA navigation.
     */
-    const layoutAttr = doc.layout
-        ? ` data-layout="${escapeAttr(doc.layout)}"`
-        : '';
+    const layoutAttr = (doc.layout ? ` data-layout="${escapeAttr(doc.layout)}"` : '') +
+        (doc.header === false ? ' data-no-header' : '');
     // ONE rule, shared with the doc-browser's hydration path — see doc-title.ts. Writing
     // it twice is what made the title change on hydration (issue #6).
     const title = pageTitle(doc, projectName);
@@ -311,10 +310,16 @@ export async function generateSite(config) {
     // ./generate-css.ts; pages here just <link> to it.
     let count = 0;
     const deadAnchors = [];
+    const bareLinks = [];
     for (const doc of docs) {
         const slug = slugMap[doc.filename];
         const dir = slug === '' ? outputDir : `${outputDir}/${slug}`;
-        const dead = deadInPageAnchors(renderDocMarkdown(doc.text));
+        const rendered = renderDocMarkdown(doc.text);
+        const dead = deadInPageAnchors(rendered);
+        // On the root page (`/`) a bare name resolves to `/name`, which works; elsewhere it does not.
+        const bare = slug === '' ? [] : bareNameLinks(rendered);
+        if (bare.length)
+            bareLinks.push(`    ${doc.path || doc.filename}: ${bare.join(', ')}`);
         if (dead.length)
             deadAnchors.push(`    ${doc.path || doc.filename}: ${dead
                 .map((d) => `#${d}`)
@@ -326,6 +331,11 @@ export async function generateSite(config) {
         }
         count += 1;
     }
+    if (bareLinks.length) {
+        misconfigured(config.strict, `\n⚠️  Links written as a bare page name. Every page is served at /slug/, so these\n` +
+            `    resolve under the page they are on and reach nothing; write /name/ instead:\n` +
+            `${bareLinks.join('\n')}\n`);
+    }
     if (deadAnchors.length) {
         misconfigured(config.strict, `\n⚠️  In-page links that point at nothing on their page. A heading's id is its text,\n` +
             `    lowercased, punctuation dropped, spaces as "-" (a repeat gets -1, -2, …):\n` +

package/dist/doc-system/site/orchestrator.js

@@ -640,6 +640,7 @@ export async function buildSite(config, opts = {}) {
                     ...(config.ignoreDocPaths ?? []),
                 ],
                 output: DOCS_JSON,
+                home: config.home,
             });
             extract();
             /*

package/dist/doc-system/site/site-config.d.ts

@@ -53,6 +53,13 @@ export interface SiteConfig {
      * files explicitly, e.g. ['src', 'README.md', 'Building-Apps.md'].
      */
     docPaths?: string[];
+    /**
+     * The page served at the site root (`/`), by slug or filename, e.g. `home: 'host'` for a
+     * site that is an app. Default: README. README then has its own page at `/readme/`, and
+     * the nav, canonical links, sitemap, llms.txt and books follow. The build fails if it
+     * names no page. A doc can also claim the root itself with `{"home": true}`.
+     */
+    home?: string;
     /**
      * Directories to skip while scanning `docPaths` — by basename (skipped wherever it
      * appears) or by path (skipped only at that location). Added to the built-in
@@ -603,6 +610,24 @@ export interface SiteConfig {
      * are confined to the repo root as correctness hygiene. Off by default; opt in.
      */
     editableSources?: boolean;
+    /**
+     * Trust the local network for reading and editing source (#227). With `editableSources` on,
+     * a browser on another device on your LAN (a phone, a headset) can open and save source
+     * directly, as one at this keyboard can, instead of needing the tunnel and an invite link.
+     * That is "Edit page source"; a live example's "Save to source" is still offered only on
+     * `localhost`.
+     *
+     * Trusted: a direct peer at a private address (RFC 1918 IPv4, IPv6 unique-local or
+     * link-local). Never trusted: tunnel traffic (it needs a session as before) or a request
+     * carrying forwarding headers. Writes still have to come from the dev server's own origin,
+     * so a page another site serves cannot write through a LAN browser.
+     *
+     * What it means: ANYONE on the network can edit your working tree. Turn it on for a network
+     * you control, never on shared wifi. And a reverse proxy on your LAN that forwards outside
+     * traffic WITHOUT forwarding headers would make that traffic look like a LAN peer. Agent
+     * driving, invite links, builds and test reports stay this machine only. Off by default.
+     */
+    trustLan?: boolean;
     /**
      * Give a coding agent (Claude) eyes + hands on your running dev page via
      * [haltija](https://github.com/tonioloewald/haltija). When on, the dev server

package/dist/editable-rect.js

@@ -53,13 +53,11 @@ preview.addEventListener('change', event => console.log(event))
   background: transparent;
   box-shadow: none;
 }
-
-.previw button
 ```
 
 ## Snapping
 
-When `EditableRect.snapToGrid === true` or the shift-key is depresseed, position will snap to `EditableRect.gridSize` pixels (default = 8).
+When `EditableRect.snapToGrid === true` or the shift-key is depressed, position will snap to `EditableRect.gridSize` pixels (default = 8).
 
 Similarly `EditableRect.snapAngle === true` or the shift-key will snap rotation to increments of `EditableRect.angleSize` degrees (default = 15).
 

package/dist/highlight-block.js

@@ -1,3 +1,4 @@
+/*{ "parent": "Documentation System", "order": 70 }*/
 /*#
 # highlight-block
 
@@ -30,16 +31,8 @@ and an unknown language renders as plain, readable code rather than failing.
 **Colours work out of the box, anywhere.** The element injects its token palette on first use,
 so a `<tosi-highlight>` on an ordinary page is coloured without importing anything.
 
-That was not always true, and the way it failed is worth knowing if you are debugging
-something similar: this package ships **no CSS files at all** — every style is a `StyleSheet()`
-call — and the palette used to live inside the doc-system stylesheet. So a standalone element
-produced perfectly correct `<span class="token …">` markup rendering in flat black, and this
-very paragraph told you to "import the doc-system CSS", which was not an import that existed.
-
-There are **two palettes** — a light set (the default) and a dark set under `.darkmode` — each
-contrast-checked against the `--code-bg` it actually sits on. Not one recomputed from the
-other: a light-mode default derived from dark-mode literals is unreadable, which is how this
-shipped failing WCAG AA on every token type.
+There are **two palettes**, a light set (the default) and a dark set under `.darkmode`, each
+contrast-checked against the `--code-bg` it sits on (see [highlight-styles](/highlight-styles/)).
 
 Every colour is a `varDefault`, so retheme one token type without touching the rest:
 

package/dist/icon-rules.d.ts

@@ -3,6 +3,16 @@ export interface IconRule {
     prefix: string | RegExp;
     apply: (baseName: string, match: RegExpMatchArray | string, parts: ElementPart[]) => Element | string | null;
 }
+/**
+ * Style suffixes on a registered icon (`checkCircle90r`), split, or null. Such a name is
+ * that icon styled, and it wins over a composition rule (#3295): `checkCircle90r` is
+ * `checkCircle` turned, not the `check` rule over `circle90r`. Both the DOM renderer and
+ * `iconSvg` resolve in that order by asking this.
+ */
+export declare function suffixedIcon(name: string): {
+    baseName: string;
+    tokens: string[];
+} | null;
 /** A registered icon, or style suffixes on one (`chevronRight50o`). */
 export declare function canResolve(name: string): boolean;
 /**
@@ -11,7 +21,13 @@ export declare function canResolve(name: string): boolean;
  */
 export declare const spinRule: IconRule;
 export declare const iconRules: IconRule[];
-/** The icon a rule would apply to in `name`, or null if the rule does not match it. */
+/**
+ * The icon a rule would apply to in `name`, or null if the rule does not match it.
+ *
+ * A `:` makes the boundary explicit: `check:box` is the `check` rule applied to `box`, with
+ * no camelCase guess, so it never reads as an icon called `checkBox`. Everything before the
+ * first `:` must be the whole prefix (`spin90:loader`, `un:lock`).
+ */
 export declare function matchRule(rule: IconRule, name: string): {
     baseName: string;
     match: RegExpMatchArray | string;

package/dist/icon-rules.js

@@ -10,13 +10,21 @@ before the name is asked for.
 */
 import iconData from './icon-data.js';
 import { splitSuffixes } from './icon-suffixes.js';
+/**
+ * Style suffixes on a registered icon (`checkCircle90r`), split, or null. Such a name is
+ * that icon styled, and it wins over a composition rule (#3295): `checkCircle90r` is
+ * `checkCircle` turned, not the `check` rule over `circle90r`. Both the DOM renderer and
+ * `iconSvg` resolve in that order by asking this.
+ */
+export function suffixedIcon(name) {
+    const split = splitSuffixes(name);
+    return split != null && iconData[split.baseName]
+        ? split
+        : null;
+}
 /** A registered icon, or style suffixes on one (`chevronRight50o`). */
 export function canResolve(name) {
-    const data = iconData;
-    if (data[name])
-        return true;
-    const split = splitSuffixes(name);
-    return split != null && !!data[split.baseName];
+    return (!!iconData[name] || suffixedIcon(name) != null);
 }
 /**
  * `spinN<Icon>` animates, so it is drawn by the DOM renderer, which installs `apply` when
@@ -47,8 +55,27 @@ export const iconRules = [
         apply: (baseName) => `search80s30x30y$${baseName}50o`,
     },
 ];
-/** The icon a rule would apply to in `name`, or null if the rule does not match it. */
+/**
+ * The icon a rule would apply to in `name`, or null if the rule does not match it.
+ *
+ * A `:` makes the boundary explicit: `check:box` is the `check` rule applied to `box`, with
+ * no camelCase guess, so it never reads as an icon called `checkBox`. Everything before the
+ * first `:` must be the whole prefix (`spin90:loader`, `un:lock`).
+ */
 export function matchRule(rule, name) {
+    const colon = name.indexOf(':');
+    if (colon !== -1) {
+        const head = name.slice(0, colon);
+        const tail = name.slice(colon + 1);
+        if (!tail)
+            return null;
+        const baseName = tail[0].toLowerCase() + tail.slice(1);
+        if (rule.prefix instanceof RegExp) {
+            const m = head.match(new RegExp(rule.prefix.source + '$'));
+            return m && m.index === 0 ? { baseName, match: m } : null;
+        }
+        return head === rule.prefix ? { baseName, match: rule.prefix } : null;
+    }
     if (rule.prefix instanceof RegExp) {
         const m = name.match(new RegExp(rule.prefix.source + '(.+)$'));
         if (!m)

package/dist/icon-svg.js

@@ -1,4 +1,4 @@
-/*{"parent":"Appendices","order":600}*/
+/*{ "parent": "icons", "order": 20 }*/
 /*#
 # `iconSvg` — icon markup without a DOM
 
@@ -27,21 +27,17 @@ other style suffix (`check50o`), a redirect to a name that is not an icon, or a
 cycle. Render those with `icons.<name>()` where there is a DOM; the suffixes and rules are
 described on the [[icons]] page. Only a name that nothing would draw returns `undefined`.
 
-Deliberately a separate module from `icons.ts`: that one imports tosijs to build
-elements, so importing it drags in code that needs `HTMLElement` and throws in a build
-script — the exact context that wanted the markup in the first place. This module
-imports nothing but the data.
-
-Background: `defineIcons()` could write to the icon map but nothing could read it, and
-`icons.foo()` returns a DOM `SVGElement`. So a static-page generator, an ePub pass or a
-server-rendered template had no way to get markup except by parsing
-`src/icons/data/*.ts` out of the installed package — which is exactly what this project
-resorted to when putting its own logo on a generated page. There is nothing to protect:
-the map ships in the bundle either way.
+It needs no DOM, so it works in a build script, a static-page generator, an ePub pass or a
+server-rendered template, where `icons.<name>()` (which builds DOM elements) cannot run.
+*/
+/*
+Deliberately a separate module from `icons.ts`: that one imports tosijs to build elements, so
+importing it drags in code that needs `HTMLElement` and throws in a build script, the exact
+context that wanted the markup. This module imports nothing but the data and the grammars.
 */
 import iconData from './icon-data.js';
-import { splitSuffixes, suffixNumber } from './icon-suffixes.js';
-import { canResolve, ruleDraws } from './icon-rules.js';
+import { suffixNumber } from './icon-suffixes.js';
+import { canResolve, ruleDraws, suffixedIcon } from './icon-rules.js';
 const data = iconData;
 // Rotation and flip, the only suffixes the built-in redirects use (`chevronDown` is
 // `chevronRight90r`). Anything else needs the DOM renderer.
@@ -64,6 +60,9 @@ export function iconSvg(name) {
         return undefined;
     return resolve(name, key, new Set());
 }
+// How to call the creator for a name: `icons.lock()`, or `icons['check:box']()` for a name
+// that is not an identifier.
+const creatorCall = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? `icons.${name}()` : `icons['${name}']()`;
 function resolve(asked, name, seen) {
     const key = stripEscape(name);
     const value = data[key];
@@ -77,17 +76,15 @@ function resolve(asked, name, seen) {
         return resolve(asked, value, seen);
     }
     // The renderer's order for a name that is not registered: a stack, then suffixes on a
-    // registered icon (they win over a rule, #3295), then a rule.
-    const split = key.includes('$') ? null : splitSuffixes(key);
-    if (split &&
-        data[split.baseName] !== undefined &&
-        split.tokens.every(isGeometry)) {
+    // registered icon (suffixedIcon, #3295), then a rule.
+    const split = key.includes('$') ? null : suffixedIcon(key);
+    if (split && split.tokens.every(isGeometry)) {
         return transformed(asked, resolve(asked, split.baseName, seen), split.tokens);
     }
     const what = key === stripEscape(asked) ? `"${key}"` : `it resolves to "${key}", which`;
     if (isComposition(key)) {
         throw new Error(`iconSvg("${asked}"): ${what} is not a single SVG (a stack, a rule, or a style ` +
-            `suffix other than rotation or flip). Render it with icons.${stripEscape(asked)}() ` +
+            `suffix other than rotation or flip). Render it with ${creatorCall(stripEscape(asked))} ` +
             `where there is a DOM.`);
     }
     throw new Error(`iconSvg("${asked}"): it redirects to "${key}", which is not a registered icon`);