tosijs-ui 1.16.21 → 1.16.22

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 1.16.22
+
+Three site options asked for by adopters, and a review pass over the documentation.
+
+- **`home`: choose the page served at `/`.** `defineSiteConfig({ home: 'host' })` (a slug or
+  filename) makes that page the site root, for a site that is an app. README then has its own
+  page at `/readme/`, and the nav, canonical links, sitemap, `llms.txt` and books follow. A
+  doc can claim the root itself with `{"home": true}` (or `home: true` in YAML frontmatter).
+  The build fails when `home` names no page or a hidden one, or when two docs claim the root.
+  **README's URL and canonical link change** when you turn it on; Doc-Site System says so. An
+  ePub takes its slugs from the whole site, so README keeps `/readme/` in a book even when the
+  home doc is not in that book. closes #225
+- **`{"header": false}`: a page without the site header.** It removes the header bar on that
+  page, before hydration and after, and gives its space to the page. With
+  `layout: "full-screen"` the page has no site chrome at all, for an app page with its own
+  toolbar or an installed PWA. The page links back to the docs its own way. closes #226
+- **YAML frontmatter reads `header: false` and `home: true`**, as the JSON metadata block does.
+- **Doc-Site System documents `header: false` and `home`**, including that home moves
+  README's URL.
+- **The build warns (fails under `strict`) on a link written as a bare page name.**
+  `[valueRenderer](value-renderer)` resolves under the page it is on and reaches nothing;
+  three shipped that way here.
+- **`naturalCompare`, `naturalSorter` and `isBlank` are exported from the package root.**
+  The naturalCompare page imported `naturalCompare` from `'tosijs-ui'`, got `undefined`, and
+  showed the lexical sort it warns against.
+- **The documentation site is regrouped.** A new Documentation System section holds every
+  page about the doc system (adopting, One Source, Doc-Site System, doc-system, doc-browser,
+  docs, highlight-block, highlight-styles, the layout demos, kitchen sink). Icons moves under
+  Components, with Icon Composition, iconSvg and make-icon-data beneath it; naturalCompare
+  joins Helper Libraries; Appendices keeps migrating and release-notes.
+- **Documentation fixes.**
+  - The doc-browser and docs pages showed a CLI that does not exist, imports from the wrong
+    module and wrong option names. Both are rewritten against the real API.
+  - Three links (data-table → value-renderer, pocket-bar → icon-composition and popFloat)
+    reached nothing.
+  - Migrating: the ACE-era `theme`/`options` props warn and do nothing, rather than being
+    gone; the 1.11.0 edit-link note points to the 1.14.0 change; new notices for 1.16.17
+    (tjs-lang 0.14), 1.16.19 (`iconSvg` throws) and 1.16.21 (tosijs `^1.10.9`).
+  - Adopting and Doc-Site System: install `chokidar` with the build peers; display-only
+    fences use `:static`; a detached test block shows its results.
+  - Icons: the class added is `tosi-icon` (no `icon-chevron-down`); how icons are coloured
+    replaces the old icomoon paragraph.
+  - Live examples: `ide` mode is described as what it is today (it runs like `iframe`).
+  - Smaller: size-break's container-query intro, the iife size (~484KB gzip), code-editor's
+    mode list (`ajs`), a stray CSS line in editable-rect's example, the menu demo's link, and
+    typos across six pages.
+- `dist/iife.js` grows by about 0.2KB gzip.
+
+### Dev-server access: `trustLan` (opt-in)
+
+Who may read and write source through the dev server changed, but only for a project that
+sets the new option; with it unset the rules are exactly 1.16.21's.
+
+- **`trustLan`: LAN devices may read and edit source.** With `editableSources` on, a direct
+  peer at a private address (RFC 1918, IPv6 unique-local or link-local) may read and save
+  source as one at the dev machine can, so a phone or headset on the LAN uses "Edit page
+  source" without the tunnel (a live example's "Save to source" is still offered only on
+  `localhost`). closes #227
+- **What is never trusted:** tunnel traffic (it still needs a session), a request with
+  forwarding headers, and a write from any origin but the dev server's own. Agent driving,
+  invite links, builds and test reports stay this machine only; agent driving no longer
+  inherits the write rule's options, so LAN trust cannot widen it.
+- **Anyone on the network can then edit your working tree**, which includes code that runs on
+  this machine: use it on a network you control. The dev server prints a warning at every
+  launch while it is on, and says so when it is set without `editableSources` (it then does
+  nothing).
+- The edit and save alerts tell a LAN reader that invite links cannot help them, instead of
+  sending them round that loop.
+
+
 ## 1.16.21
 
 - **Expanding or collapsing a table row's detail no longer corrects `scrollTop` itself.**

package/README.md

@@ -14,7 +14,7 @@
   ></tosi-lottie>
 </center>
 
-Copyright ©2023-2025 Tonio Loewald
+Copyright ©2023-2026 Tonio Loewald
 
 > **Upgrading from an older version?** `<tosi-code>` changed editors in 1.7.0, and
 > 1.3.0 renamed everything from `xinjs-ui`. Both are covered in
@@ -53,7 +53,7 @@ The `tosijs-ui` iife build bundles `tosijs`, `tosijs-ui`, `marked` and — as of
 **CodeMirror** into a single minified javascript source file. You can access `xinjs` and
 `xinjsui` as globals which contain all the things exported by `tosijs` and `tosijs-ui`.
 
-> **Size (1.15):** ~468KB gzip, up from ~120KB in 1.6. Two things dominate it, and
+> **Size (1.16.21):** ~484KB gzip, up from ~120KB in 1.6. Two things dominate it, and
 > `bun build --format iife` cannot
 > code-split, so `<tosi-code>`'s lazy CodeMirror import is flattened into this bundle
 > whether or not the page uses an editor. **If you don't need `<tosi-code>`, use the ESM

package/bin/make-icon-data.js

@@ -86,7 +86,7 @@ byte-identical files, so it never shows up as spurious diff noise.
 > your prettier config, which it now honours) — not the output.
 */
 
-/*{ "parent": "Appendices" }*/
+/*{ "parent": "icons", "order": 30 }*/
 
 import fs from 'fs'
 import path from 'path'

package/dist/code-editor.js

@@ -6,7 +6,7 @@ A [CodeMirror 6](https://codemirror.net/) wrapper.
 Sometimes, it's nice to be able to just toss a code-editor in a web-page.
 
 `<tosi-code>`'s `value` is the code it contains. Its `mode` attribute sets the
-language (`javascript`, `typescript`, `tjs`, `css`, `html`, `markdown`).
+language (`javascript`, `typescript`, `tjs`, `ajs`, `css`, `html`, `markdown`).
 
 ```html
 <tosi-code style="width: 100%; height: 100%" mode="css">
@@ -69,8 +69,7 @@ CodeMirror is a **lazy chunk**: with a bundler (ESM), a page that never uses
 `<tosi-code>` doesn't load it. **This is not true of the IIFE** (`dist/iife.js`) —
 bun's IIFE format cannot code-split, so CodeMirror is inlined there. That is a
 deliberate trade: the doc-system's editor (and its save-to-source flow) is the
-point of the IIFE, so it carries the editor. It costs ~376KB gzipped, up from
-~118KB in 1.6.x.
+point of the IIFE, so it carries the editor; see the README for what the IIFE weighs.
 
 ## Migrating from the ACE editor (pre-1.7)
 

package/dist/data-table.js

@@ -205,7 +205,7 @@ export interface ColumnOptions {
 ## Column value types
 
 Give a column a `type` and it's formatted (and aligned) automatically — no hand-rolled
-`dataCell`. The `type` is a [`valueRenderer`](value-renderer) string:
+`dataCell`. The `type` is a [`valueRenderer`](/value-renderer/) string:
 
 ```
 [

package/dist/doc-browser.d.ts

@@ -38,6 +38,10 @@ export interface Doc {
     path: string;
     pin?: string;
     hidden?: boolean;
+    /** this doc is the site root instead of README (the site's `home` option) */
+    home?: boolean;
+    /** `false` drops the site header on this page (see the site `Doc.header`) */
+    header?: boolean;
     /** `'full-width'` drops the reading measure; `'full-screen'` also puts the nav away. */
     layout?: 'full-width' | 'full-screen';
     testStatus?: 'passed' | 'failed' | 'pending';

package/dist/doc-browser.js

@@ -1,26 +1,34 @@
 /*#
 # doc-browser
 
-The `tosijs-ui` library provides everything you need to create a self-documented testbed similar
-to the [tosijs-ui documentation site](https://ui.tosijs.net). It's like Storybook but much simpler
-to set up and maintain.
+`createDocBrowser()` renders a documentation corpus as a browsable, searchable testbed with
+live examples, like the [tosijs-ui documentation site](https://ui.tosijs.net). It's like
+Storybook but much simpler to set up and maintain.
+
+For a whole documentation site (static, pre-rendered pages, SEO, ePub, a dev server), use
+[`tosijs-ui/site`](/adopting-the-doc-system/) instead; it builds on this component. Reach for
+`createDocBrowser` directly to embed a doc browser in an app of your own.
 
 ## Quick Start
 
-### 1. Extract Documentation
+### 1. Extract the documentation
 
-Use the CLI tool to extract documentation from your source files:
+Run once at build time (it reads files, so it runs under bun or node, not in the browser):
 
-```bash
-npx tosijs-ui-docs --dirs src,README.md --output docs.json
-```
+```typescript
+import { extractDocs } from 'tosijs-ui/site'
 
-This scans for:
+extractDocs({
+  paths: ['src', 'README.md'],
+  output: 'docs.json',
+})
+```
 
-- `.md` files (uses entire content)
-- Multi-line comments starting with `/*#` in `.ts`, `.js`, `.css` files
+This collects every `.md` file and every `/*#` comment block in your sources. The format,
+metadata and which code fences run are described under
+[Doc format](/doc-site-system/#doc-format).
 
-### 2. Create Your Doc Browser
+### 2. Create your doc browser
 
 ```typescript
 import { createDocBrowser } from 'tosijs-ui/doc-browser'
@@ -40,20 +48,16 @@ const browser = createDocBrowser({
 document.body.append(browser)
 ```
 
-### 3. Add Live Examples in Your Docs
+### 3. Add live examples to your docs
 
-In your source files or markdown, use code fences. Any sequence of
-html, js, and css code examples will be turned in to a live, interactive
-example.
+Consecutive `html`, `css`, `js` (or `ts`, `tjs`) and `test` code fences become one live,
+editable example. `context` supplies the modules those examples import:
 
     /*#
     # My Component
 
     This component does amazing things!
 
-    ```html
-    <my-component></my-component>
-    ```
     ```js
     import { myComponent } from 'mylib'
     preview.append(myComponent({ value: 'Hello!' }))
@@ -65,94 +69,33 @@ example.
     ```
     *‎/
 
-    export class MyComponent extends Component {
-      // ...
-    }
-
-    export const myComponent = MyComponent.elementCreator({
-      tag: 'my-component'
-    })
-
-## Documentation Format
-
-### Inline Comments
-
-Start multi-line comments with `/*#` to mark them as documentation:
-
-```typescript
-/*#
-# Component Name
-
-Description and examples go here...
-*‎/
-```
-
-### Metadata
-
-Control sort order with JSON metadata:
-
-```
-<!--{ "pin": "bottom" }-->
-```
-
-or
-
-```
-/*{ "pin": "bottom" }*‎/
-```
-
-## Programmatic API
-
-```typescript
-import { extractDocs, saveDocsJSON } from 'tosijs-ui'
-
-const docs = extractDocs({
-  dirs: ['src', 'README.md'],
-  ignore: ['node_modules', 'dist'],
-})
-
-saveDocsJSON(docs, './docs.json')
-
-// Or use the docs directly
-import { createDocBrowser } from 'tosijs-ui/doc-browser'
-const browser = createDocBrowser({ docs, context: { mylib } })
-```
-
 ## createDocBrowser Options
 
 ```typescript
 interface DocBrowserOptions {
-  docs: Doc[] // Array of documentation objects
-  context?: Record<string, any> // Modules for live examples
-  projectName?: string // Display name
-  projectLinks?: ProjectLinks // Links to show in header
-  navSize?: number // Nav width (default: 200)
-  minSize?: number // Min width before compact (default: 600)
-}
-
-interface ProjectLinks {
-  github?: string
-  npm?: string
-  discord?: string
-  blog?: string
-  tosijs?: string
-  bundle?: string
-  cdn?: string
-  [key: string]: string | undefined
+  docs: Doc[] // the extracted corpus
+  context?: Record<string, any> // modules live examples can import
+  projectName?: string // display name
+  projectLinks?: ProjectLinks // links in the header
+  logo?: string // header logo
+  navSize?: number // nav width (default: 200)
+  minSize?: number // width below which the nav goes compact (default: 600)
+  routing?: 'query' | 'path' | 'memory' // see below (default: 'query')
+  initialRoute?: string // memory routing: the first page
+  onRouteChange?: (slug: string) => void // memory routing: page changes
+  navbarLinks?: LinkItem[] // icon links in the header bar
+  contentElement?: HTMLElement // adopt this element as the content area
 }
 ```
 
-## See Also
-
-The `tosijs-ui` demo is a complete working example. See:
-
-- `/tosijs-site.config.ts` - How this repo configures its doc site (`defineSiteConfig` / `tosijs-ui/site`)
-- `/src/doc-system/site/docs.ts` - The extraction tool (`extractDocs`, exported from `tosijs-ui/site`)
-- `/src/doc-browser.ts` - The createDocBrowser implementation
+`routing` picks how pages map to URLs. `'query'` links pages as `?filename`. `'path'` uses
+clean `/slug/` URLs, as the static site does. `'memory'` never touches the page's URL or
+history, for a browser embedded in another page: drive it with `initialRoute`,
+`onRouteChange` and the element's `navigate(slug)` method.
 */
-/*{"pin":"bottom","parent":"Appendices"}*/
+/*{ "parent": "Documentation System", "order": 50 }*/
 import { elements, vars, varDefault, bindings, touch, getListItem, debounce, tosi, StyleSheet, } from 'tosijs';
-import { buildSlugMap, pathForSlug, filenameForPath, } from './doc-system/routing.js';
+import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, } from './doc-system/routing.js';
 import { buildNavTree } from './doc-system/nav-tree.js';
 import { renderDocMarkdown } from './doc-system/render.js';
 import { pageTitle } from './doc-system/doc-title.js';
@@ -476,7 +419,7 @@ export function createDocBrowser(options) {
         }
         return null;
     };
-    const docName = filenameFromLocation() || docs[0]?.filename || 'README.md';
+    const docName = filenameFromLocation() || homeDoc(docs) || docs[0]?.filename || 'README.md';
     const currentDoc = docs.find((doc) => doc.filename === docName) || docs[0];
     // tosi() registers its top-level keys in a GLOBAL observable registry, so two
     // doc browsers on one page (e.g. a page whose live example embeds a nested
@@ -1053,6 +996,7 @@ export function createDocBrowser(options) {
                     layoutHost.setAttribute('data-layout', doc.layout);
                 else
                     layoutHost.removeAttribute('data-layout');
+                layoutHost.toggleAttribute('data-no-header', doc.header === false);
             }
             /*
             `full-screen` also collapses the nav, and that has to go through the COMPONENT rather than
@@ -1347,7 +1291,7 @@ export function createDocBrowser(options) {
             window.alert('This workspace needs an invite link before it can save.\n\n' +
                 'Run `tosijs-tunnel --link` on the machine hosting it, open the link once, ' +
                 'then try again. Your edit is still here.\n\n' +
-                'If you opened this over the LAN (a `.local` address), saving will keep failing however many links you redeem — reach the workspace through its tunnel URL instead.');
+                'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.');
         }
         else {
             // Genuinely no write endpoint (a deployed static site) — hand the file back.
@@ -1361,7 +1305,8 @@ export function createDocBrowser(options) {
         if (content === null) {
             window.alert(sourceUnauthorized
                 ? 'This workspace needs an invite link before you can edit.\n\n' +
-                    'Run `tosijs-tunnel --link` on the machine hosting it and open the link once.'
+                    'Run `tosijs-tunnel --link` on the machine hosting it and open the link once.\n\n' +
+                    'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.'
                 : `Could not load source for ${doc.path}`);
             return;
         }

package/dist/doc-system/doc-system-styles.js

@@ -159,6 +159,17 @@ export function docSystemStyleSpec(theme = {}) {
         'tosi-doc-system[data-layout="full-screen"] > .doc-nav.doc-nav, tosi-doc-system[data-layout="full-screen"] > .doc-navbar.doc-navbar': {
             display: 'none',
         },
+        /*
+        `header: false` — no header bar on this page (#226). One variable takes the bar's space
+        away everywhere it is reserved (the pre-hydration inset, the nav's top, the hydrated
+        column), and the bar itself is hidden before hydration (`::before`) and after (`header`).
+        */
+        'tosi-doc-system[data-no-header]': {
+            _headerHeight: '0px',
+        },
+        'tosi-doc-system[data-no-header]::before, tosi-doc-system[data-no-header] header': {
+            display: 'none',
+        },
         '.darkmode': {
             ...invertLuminance(colors),
             /*

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

@@ -55,7 +55,7 @@ A self-contained, controllable embed (e.g. docs in a floating panel):
 </tosi-doc-system>
 ```
 */
-/*{ "parent": "Appendices" }*/
+/*{ "parent": "Documentation System", "order": 40 }*/
 import { StyleSheet, elements, tosi, vars, withAttributes, } from 'tosijs';
 import * as tosijsModule from 'tosijs';
 import { createDocBrowser, } from '../doc-browser.js';

package/dist/doc-system/highlight-styles.js

@@ -1,17 +1,11 @@
+/*{ "parent": "Documentation System", "order": 80 }*/
 /*#
 # highlight-styles
 
-The syntax-highlighting token palette, on its own.
+The syntax-highlighting token palette, on its own. The package ships no CSS files (every
+style is a `StyleSheet()` call), so this is how token colours reach a page.
 
-It lives here rather than inside `docSystemStyleSpec` because the package ships **no CSS
-files at all** — every style is a `StyleSheet()` call — so before this existed, the only way
-to get token colours was to import the whole doc-site chrome. A standalone
-[`<tosi-highlight>`](/highlight-block/) on an ordinary page therefore produced perfectly
-correct `<span class="token …">` markup rendering in flat black, which is the one thing that
-component is for. The doc block even told you to "import the doc-system CSS", naming an
-import that did not exist.
-
-`<tosi-highlight>` now injects this itself on first use, so the standalone case needs nothing.
+[`<tosi-highlight>`](/highlight-block/) injects it on first use, so that needs nothing.
 Import it directly only if you are highlighting markup you produced some other way:
 
 ```typescript
@@ -27,14 +21,15 @@ by setting its variable:
 :root { --token-keyword: rebeccapurple; }
 ```
 
-Two palettes, not one recomputed from the other: a light default and a dark set under
-`.darkmode`. Deriving light from dark literals is how this shipped failing WCAG AA on every
-token type. Measured, both directions (AA needs 4.5:1): light on `#fdfdfd` worst **5.32:1**
-(comment); dark on `#020202` worst **6.01:1** (punctuation). `doc-system-styles.test.ts`
-asserts both, so they are checked rather than claimed.
-
+Two palettes: a light default and a dark set under `.darkmode`, each meeting WCAG AA
+(4.5:1) against its own background. Light on `#fdfdfd` is at worst **5.32:1** (comment); dark
+on `#020202` at worst **6.01:1** (punctuation). Tests check both.
+*/
+/*
 Dark uses DESCENDANT selectors rather than a nested `.darkmode` block, because the doc-system
 spec already has one and a duplicate key loses silently to the last writer instead of merging.
+Deriving the light palette from the dark literals is how this once shipped failing WCAG AA on
+every token type; doc-system-styles.test.ts asserts both palettes.
 */
 import { StyleSheet, varDefault } from 'tosijs';
 /** The `.token.*` rules — light default plus a dark set under `.darkmode`. */

package/dist/doc-system/routing.d.ts

@@ -1,6 +1,15 @@
 export interface DocLike {
     filename: string;
+    /** this doc is the site root (`/`) instead of README; see `homeDoc` */
+    home?: boolean;
 }
+/**
+ * The doc served at the site root: the one doc marked `home`, or README when none is.
+ * Marked by the build from the site's `home` option, or by a doc's own `{"home": true}`.
+ * The build refuses a corpus with more than one, so a second mark is ignored here rather
+ * than giving two docs the root.
+ */
+export declare function homeDoc(docs: DocLike[]): string | null;
 /**
  * Build a deterministic { filename -> slug } map for a set of docs.
  *

package/dist/doc-system/routing.js

@@ -11,10 +11,25 @@ function here is a pure, order-independent function of the docs array, so the tw
 sides always produce identical slugs.
 */
 const README = /^readme\.md$/i;
-/** filename without its final extension; README.md maps to '' (the site root) */
-function baseSlug(filename) {
-    if (README.test(filename))
+/**
+ * The doc served at the site root: the one doc marked `home`, or README when none is.
+ * Marked by the build from the site's `home` option, or by a doc's own `{"home": true}`.
+ * The build refuses a corpus with more than one, so a second mark is ignored here rather
+ * than giving two docs the root.
+ */
+export function homeDoc(docs) {
+    const marked = docs.filter((doc) => doc.home);
+    return marked.length === 1 ? marked[0].filename : null;
+}
+/**
+ * filename without its final extension. The home doc maps to '' (the site root); README
+ * does too unless another doc is home, and is then `readme`.
+ */
+function baseSlug(filename, home) {
+    if (filename === home)
         return '';
+    if (README.test(filename))
+        return home == null ? '' : 'readme';
     return filename.replace(/\.[^.]+$/, '');
 }
 /**
@@ -26,15 +41,16 @@ function baseSlug(filename) {
  * on array order.
  */
 export function buildSlugMap(docs) {
+    const home = homeDoc(docs);
     const counts = {};
     for (const doc of docs) {
-        const base = baseSlug(doc.filename);
+        const base = baseSlug(doc.filename, home);
         counts[base] = (counts[base] || 0) + 1;
     }
     const map = {};
     for (const doc of docs) {
-        const base = baseSlug(doc.filename);
-        // README ('' base) is unique by construction; never disambiguate it.
+        const base = baseSlug(doc.filename, home);
+        // The root ('' base) is unique by construction; never disambiguate it.
         map[doc.filename] =
             base !== '' && counts[base] > 1 ? doc.filename.replace(/\./g, '-') : base;
     }

package/dist/doc-system/site/build-warnings.d.ts

@@ -22,3 +22,13 @@ export declare function liveFenceLanguages(docs: Array<{
     text?: string;
 }>, policy?: ExamplePolicy): Set<string>;
 export declare function deadInPageAnchors(html: string): string[];
+/**
+ * Links in a RENDERED page written as a bare page name (`[valueRenderer](value-renderer)`).
+ *
+ * Every page is served at `/slug/`, so a relative `value-renderer` resolves to
+ * `/this-page/value-renderer`, which is never a page: the link is broken with or without
+ * script. It is the natural thing to write and reads correctly in the source, which is how
+ * three of them shipped. Only a name with no `.` and no `/` is reported, so a relative asset
+ * (`diagram.svg`, `img/x.png`) is left alone. The fix is the root-relative `/value-renderer/`.
+ */
+export declare function bareNameLinks(html: string): string[];

package/dist/doc-system/site/build-warnings.js

@@ -104,3 +104,27 @@ export function deadInPageAnchors(html) {
     }
     return [...dead];
 }
+/**
+ * Links in a RENDERED page written as a bare page name (`[valueRenderer](value-renderer)`).
+ *
+ * Every page is served at `/slug/`, so a relative `value-renderer` resolves to
+ * `/this-page/value-renderer`, which is never a page: the link is broken with or without
+ * script. It is the natural thing to write and reads correctly in the source, which is how
+ * three of them shipped. Only a name with no `.` and no `/` is reported, so a relative asset
+ * (`diagram.svg`, `img/x.png`) is left alone. The fix is the root-relative `/value-renderer/`.
+ */
+export function bareNameLinks(html) {
+    const found = new Set();
+    for (const tag of html.matchAll(START_TAG)) {
+        if (tag[1].toLowerCase() !== 'a')
+            continue;
+        for (const attr of tag[2].matchAll(ATTRIBUTE)) {
+            if (attr[1].toLowerCase() !== 'href')
+                continue;
+            const value = unescapeAttr(attr[2] ?? attr[3] ?? attr[4] ?? '');
+            if (/^[A-Za-z0-9_-]+\/?$/.test(value))
+                found.add(value);
+        }
+    }
+    return [...found];
+}

package/dist/doc-system/site/dev-auth.d.ts

@@ -287,6 +287,13 @@ export declare function mayWriteSource(opts: {
      * never be the permissive-by-accident case for anything but the status quo.
      */
     sessionMayWrite?: boolean;
+    /**
+     * The project opted in to trusting its LAN (`trustLan`, #227): a direct, unproxied peer at a
+     * private address counts as this machine. Off unless the caller says so.
+     */
+    trustLan?: boolean;
+    /** did the request carry forwarding headers? A proxied request is never LAN trust */
+    proxied?: boolean;
 }): boolean;
 /**
  * May the holder of this session token write?
@@ -329,6 +336,12 @@ export declare function mayDriveWithAgent(opts: {
  * dual-stack listener, and missing it would lock out the local machine on some setups.
  */
 export declare function isLoopbackAddressForAuth(address: string | undefined | null): boolean;
+/**
+ * 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 declare function isPrivateNetworkAddress(address: string | undefined | null): boolean;
 export declare function isProxiedRequest(headers: {
     get(name: string): string | null;
 }): boolean;

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)?