tosijs-ui 1.16.28 → 1.16.29

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.16.29
+
+### Doc system
+
+- **A wikilink can name a page by its title.** `[[The feature registry]]` now reaches the page
+  at `/registry/`. Before, a target was only ever slugified, so it went to
+  `/the-feature-registry/` and 404'd. The slug (file name) still wins when a page has one, so
+  no link that worked changes target. A title two pages share reaches neither.
+  Reported by tosijs-3d-ensemble (#234).
+- **The build reports a wikilink that reaches no doc page**, naming the file and the target,
+  and fails under `strict`. One site had nine of these, live 404s from as far back as its 0.3,
+  and no build had said a word. **If you build with `strict: true`:** a wikilink to something
+  that is not a doc page, such as a hand-written page in your static folder, now fails the
+  build even though the link works. Write it as an ordinary `[label](/path/)`.
+- **The test-status widget sits in the header bar.** It was fixed at the bottom left over the
+  page, so a full-page component's last list row lost clicks to it (#233). A page with
+  `{"header": false}` still floats it there, having nowhere else to put it.
+
+### Tunnel
+
+- **The "needs an invite link" page offers the lasting link too.** When the dev server takes
+  the preview box's global keys, it now names `tosijs-tunnel --link --global` beside the
+  per-visit `--link`. That link keeps the browser in for 30 days across restarts (#232).
+
 ## 1.16.28
 
 ### Tunnel

package/dist/doc-browser.js

@@ -95,7 +95,7 @@ history, for a browser embedded in another page: drive it with `initialRoute`,
 */
 /*{ "parent": "Documentation System", "order": 50 }*/
 import { elements, vars, varDefault, bindings, touch, getListItem, debounce, tosi, StyleSheet, } from 'tosijs';
-import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, } from './doc-system/routing.js';
+import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, wikilinkTargets, } 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';
@@ -202,21 +202,28 @@ const testIndicatorStyleSpec = {
         background: testColor.fail,
         animation: 'test-pulse 2s ease-in-out infinite',
     },
-    // Floating widget - position and colors only, inherits button structure.
-    // Bottom-LEFT: bottom-right is where the injected haltija dev widget sits, and it
-    // was overlaying this.
+    /*
+    The widget sits in the header bar, not over the page (GitHub #233).
+  
+    It used to be `position: fixed` at the bottom left, on top of whatever the page drew there:
+    a full-page component's list ran under it and a click on its last row landed on the widget
+    instead. Only a page with no header (`{"header": false}`) still floats it, because there is
+    nowhere else to put it. Bottom-LEFT, because the haltija dev widget takes bottom-right.
+    */
     '.test-widget': {
         _testBg: testColor.running,
         _testFg: testTextColor.running,
-        position: 'fixed',
-        bottom: vars.spacing,
-        left: vars.spacing,
-        zIndex: '1000',
         background: vars.testBg,
         // Paired with the background, not fixed to white — see testTextColor above.
         color: vars.testFg,
         gap: vars.spacing50,
     },
+    '.test-widget.-floating': {
+        position: 'fixed',
+        bottom: vars.spacing,
+        left: vars.spacing,
+        zIndex: '1000',
+    },
     '.test-widget[hidden]': { display: 'none' },
     '.test-widget.-running': {
         _testBg: testColor.running,
@@ -368,6 +375,7 @@ export function createDocBrowser(options) {
     // while letting <tosi-doc-system> drive clean `/slug/` URLs off the same docs.
     // Both path and memory routing key off slugs; only legacy query routing doesn't.
     const slugMap = routing === 'query' ? {} : buildSlugMap(docs);
+    const wikilinks = wikilinkTargets(docs);
     const slugFor = (filename) => slugMap[filename] ?? filename;
     const filenameForSlug = (slug) => {
         for (const d of docs)
@@ -974,6 +982,7 @@ export function createDocBrowser(options) {
             // without loading the tjs transpiler. See self-contained-examples-plan.md.
             docContent.innerHTML = renderDocMarkdown(doc.text, {
                 bakes: doc.bakes ? new Map(doc.bakes) : undefined,
+                wikilinks,
             });
         }
         /*
@@ -1029,6 +1038,7 @@ export function createDocBrowser(options) {
             // to follow the doc, so this does not ride on that path succeeding.
             refreshNavToggle();
         }
+        placeTestWidget(doc);
         rewriteContentLinks();
         // Stamp each example with its source file (for the source↔doc map). doc.path
         // is the extracted file (.md, or a source file with doc comments).
@@ -1262,7 +1272,7 @@ export function createDocBrowser(options) {
             return;
         editUI.view = view;
         if (view === 'preview') {
-            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path));
+            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks });
             rewriteContentLinks();
             LiveExample.insertExamples(docContent, context, editUI.doc.path || undefined);
         }
@@ -1615,6 +1625,21 @@ export function createDocBrowser(options) {
             height: '100%',
         },
     }, docContent)));
+    // Test status widget
+    const testWidget = button({
+        class: 'test-widget',
+        hidden: true,
+        onClick: showTestMenu,
+    }, span({ part: 'label' }, 'Tests'), span({ class: 'count', part: 'count' }, '0'));
+    const headerBar = container.querySelector('header');
+    // In the header unless this doc hides the header; see `.test-widget` in the styles.
+    const placeTestWidget = (doc) => {
+        const floating = doc.header === false;
+        testWidget.classList.toggle('-floating', floating);
+        const home = floating ? container : headerBar;
+        if (testWidget.parentElement !== home)
+            home.appendChild(testWidget);
+    };
     // Render the landing doc (adopts pre-rendered HTML when hydrating).
     showDoc(currentDoc);
     // Inject test indicator styles
@@ -1622,13 +1647,6 @@ export function createDocBrowser(options) {
     // Header brand-mark sizing (icon / <img> / inline-<svg>), one CSS var each.
     StyleSheet('doc-logo-mark', logoMarkStyleSpec);
     StyleSheet('doc-nav-search', navSearchStyleSpec);
-    // Floating widget for test status
-    const testWidget = button({
-        class: 'test-widget',
-        hidden: true,
-        onClick: showTestMenu,
-    }, span({ part: 'label' }, 'Tests'), span({ class: 'count', part: 'count' }, '0'));
-    container.appendChild(testWidget);
     /*
     The far end has something to tell you.
   

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

@@ -7,7 +7,7 @@ Node-only APIs — so it bundles into the iife. Live examples are pretty-printed
 force-wrapped code listings, not executed.
 */
 import { renderDocMarkdown } from './render.js';
-import { buildSlugMap } from './routing.js';
+import { buildSlugMap, wikilinkTargets } from './routing.js';
 import { buildNavTree } from './nav-tree.js';
 import { bookTextOf } from './book-target.js';
 // Clean book typography; force-wraps code so listings never overflow a page.
@@ -149,10 +149,13 @@ function tocHtml(nodes) {
 export function buildBookHtml(docs, opts) {
     const visible = docs.filter((d) => !d.hidden);
     const slugMap = buildSlugMap(visible);
+    const wikilinks = wikilinkTargets(visible);
     const roots = buildNavTree(visible, slugMap);
     const css = opts.css ?? `${DEFAULT_BOOK_CSS}\n${PRINT_CSS}`;
     const chapters = flatten(roots)
-        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)))}\n</section>`)
+        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)), {
+        wikilinks,
+    })}\n</section>`)
         .join('\n');
     return `<!DOCTYPE html>
 <html lang="${opts.lang ?? 'en'}">

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

@@ -6,6 +6,8 @@ export type ExampleBakes = Map<string, ExampleBake>;
 export declare function unwrapLoneCustomElements(html: string): string;
 export declare function renderDocMarkdown(text: string, opts?: {
     bakes?: ExampleBakes;
+    /** the corpus's `wikilinkTargets`; without it a `[[target]]` is slugified as written */
+    wikilinks?: Map<string, string>;
 }): string;
 /**
  * Derive a clean <meta name="description"> from a doc's first prose paragraph.

package/dist/doc-system/render.js

@@ -11,8 +11,10 @@ give that example a stable anchor — see the docMarked renderer below.
 import { Marked, Renderer } from 'marked';
 import { parseFenceInfo } from './example-policy.js';
 import { HeadingIds, headingSlug } from './heading-id.js';
+import { pathForSlug, slugify } from './routing.js';
 const baseRenderer = new Renderer();
 let currentBakes;
+let currentWikilinks;
 // Per-parse, reset in `preprocess` below (same pattern as the footnote state).
 let headingIds = new HeadingIds();
 const docMarked = new Marked();
@@ -69,12 +71,6 @@ docMarked.use({
 // Enabled by default because each activates ONLY on its own syntax ([[…]] /
 // [^id]) — a doc that doesn't use them renders byte-identically (tosijs-ui's own
 // docs use neither). marked core supports neither; both are common in prose.
-function slugify(s) {
-    return s
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
-}
 function escapeHtml(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
@@ -112,7 +108,9 @@ docMarked.use({
     extensions: [
         {
             // [[slug]] / [[slug|label]] → link to /slug/. Not matched inside code spans
-            // (Marked tokenizes those first). Resolves by slugifying the target.
+            // (Marked tokenizes those first). Given the corpus's `wikilinkTargets`, a target is
+            // looked up there (by slug, then title) and one that reaches no page is marked
+            // `-missing` for the build to report; without them it is slugified as written.
             name: 'wikilink',
             level: 'inline',
             start(src) {
@@ -130,7 +128,12 @@ docMarked.use({
                 };
             },
             renderer(token) {
-                return `<a href="/${slugify(token.target)}/" class="wikilink">${escapeHtml(token.label)}</a>`;
+                const key = slugify(token.target);
+                const slug = currentWikilinks ? currentWikilinks.get(key) : key;
+                const missing = slug === undefined
+                    ? ` -missing" data-target="${escapeAttr(token.target)}`
+                    : '';
+                return `<a href="${pathForSlug(slug ?? key)}" class="wikilink${missing}">${escapeHtml(token.label)}</a>`;
             },
         },
         {
@@ -205,11 +208,13 @@ export function unwrapLoneCustomElements(html) {
 }
 export function renderDocMarkdown(text, opts = {}) {
     currentBakes = opts.bakes;
+    currentWikilinks = opts.wikilinks;
     try {
         return unwrapLoneCustomElements(docMarked.parse(text));
     }
     finally {
         currentBakes = undefined;
+        currentWikilinks = undefined;
     }
 }
 /**

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

@@ -19,6 +19,18 @@ export declare function homeDoc(docs: DocLike[]): string | null;
  * on array order.
  */
 export declare function buildSlugMap(docs: DocLike[]): Record<string, string>;
+/**
+ * What each `[[target]]` in a corpus can reach: { slugify(target) -> slug }.
+ *
+ * A page is reached by its slug, and also by its title when no page has that slug and no
+ * other page has the same title (GitHub #234). Authors write a page's TITLE —
+ * `[[The feature registry]]` — while the page lives at its file name, `/registry/`; before
+ * this, every such link went to `/the-feature-registry/` and 404'd without a word. A slug
+ * always wins over a title, so no link that already worked changes target.
+ */
+export declare function wikilinkTargets(docs: Array<DocLike & {
+    title?: string;
+}>): Map<string, string>;
 /** site-root-relative path for a slug: '' -> '/', 'button' -> '/button/' */
 export declare function pathForSlug(slug: string): string;
 /**

package/dist/doc-system/routing.js

@@ -56,6 +56,36 @@ export function buildSlugMap(docs) {
     }
     return map;
 }
+/**
+ * What each `[[target]]` in a corpus can reach: { slugify(target) -> slug }.
+ *
+ * A page is reached by its slug, and also by its title when no page has that slug and no
+ * other page has the same title (GitHub #234). Authors write a page's TITLE —
+ * `[[The feature registry]]` — while the page lives at its file name, `/registry/`; before
+ * this, every such link went to `/the-feature-registry/` and 404'd without a word. A slug
+ * always wins over a title, so no link that already worked changes target.
+ */
+export function wikilinkTargets(docs) {
+    const slugs = buildSlugMap(docs);
+    const targets = new Map();
+    for (const doc of docs) {
+        const slug = slugs[doc.filename];
+        if (slug !== '')
+            targets.set(slugify(slug), slug);
+    }
+    const byTitle = new Map();
+    for (const doc of docs) {
+        const key = doc.title ? slugify(doc.title) : '';
+        if (!key || targets.has(key))
+            continue;
+        // Two pages with one title: neither is reachable by it, so the link is reported.
+        byTitle.set(key, byTitle.has(key) ? null : slugs[doc.filename]);
+    }
+    for (const [key, slug] of byTitle)
+        if (slug !== null)
+            targets.set(key, slug);
+    return targets;
+}
 /** site-root-relative path for a slug: '' -> '/', 'button' -> '/button/' */
 export function pathForSlug(slug) {
     return slug === '' ? '/' : `/${slug}/`;

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

@@ -32,3 +32,11 @@ export declare function deadInPageAnchors(html: string): string[];
  * (`diagram.svg`, `img/x.png`) is left alone. The fix is the root-relative `/value-renderer/`.
  */
 export declare function bareNameLinks(html: string): string[];
+/**
+ * The `[[wikilinks]]` in a RENDERED page that reach no page, as their authors wrote them.
+ *
+ * The renderer marks one `-missing` (with its target in `data-target`) when it was given the
+ * corpus's `wikilinkTargets` and neither a slug nor a title matched. Nine of these sat in one
+ * site for five releases, every one a live 404, because nothing said so (GitHub #234).
+ */
+export declare function missingWikilinks(html: string): string[];

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

@@ -128,3 +128,30 @@ export function bareNameLinks(html) {
     }
     return [...found];
 }
+/**
+ * The `[[wikilinks]]` in a RENDERED page that reach no page, as their authors wrote them.
+ *
+ * The renderer marks one `-missing` (with its target in `data-target`) when it was given the
+ * corpus's `wikilinkTargets` and neither a slug nor a title matched. Nine of these sat in one
+ * site for five releases, every one a live 404, because nothing said so (GitHub #234).
+ */
+export function missingWikilinks(html) {
+    const found = new Set();
+    for (const tag of html.matchAll(START_TAG)) {
+        if (tag[1].toLowerCase() !== 'a')
+            continue;
+        let missing = false;
+        let target = '';
+        for (const attr of tag[2].matchAll(ATTRIBUTE)) {
+            const key = attr[1].toLowerCase();
+            const value = unescapeAttr(attr[2] ?? attr[3] ?? attr[4] ?? '');
+            if (key === 'class')
+                missing = value.split(/\s+/).includes('-missing');
+            else if (key === 'data-target')
+                target = value;
+        }
+        if (missing && target)
+            found.add(target);
+    }
+    return [...found];
+}

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

@@ -1904,7 +1904,7 @@ export async function devServer(config, opts = {}) {
                 sentence differs, and that sentence was the entire report.
                 */
                 const rejection = sessionRejection(readCookie(request.headers.get('cookie'), SESSION_COOKIE), Date.now());
-                return new Response(invitePageHtml(rejection, TUNNEL_LINK_CMD), {
+                return new Response(invitePageHtml(rejection, TUNNEL_LINK_CMD, globalKeys.keys.edit ? `${TUNNEL_LINK_CMD} --global` : undefined), {
                     status: 401,
                     headers: {
                         'Content-Type': 'text/html; charset=utf-8',

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

@@ -18,7 +18,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { renderDocMarkdown } from '../render.js';
 import { highlightHtml } from '../highlight.js';
-import { buildSlugMap, pathForSlug, resolveParent, slugForPath, withBase, } from '../routing.js';
+import { buildSlugMap, pathForSlug, resolveParent, slugForPath, withBase, wikilinkTargets, } from '../routing.js';
 import { buildNavTree } from '../nav-tree.js';
 import { partitionByBook, placeInBook, bookTextOf, DEFAULT_BOOK, } from '../book-target.js';
 import { COVER_MEDIA_TYPES, coverStem, epubVolumeIdentity, } from './epub-volumes.js';
@@ -621,6 +621,7 @@ export async function buildEpub(config, opts = {}) {
     into the default one just by not naming a book.
     */
     const siteSlugs = buildSlugMap(corpus);
+    const wikilinks = wikilinkTargets(corpus);
     const volumes = partitionByBook(corpus, siteSlugs);
     const visible = volumes.get(opts.bookTarget ?? DEFAULT_BOOK) ?? [];
     /*
@@ -750,7 +751,7 @@ export async function buildEpub(config, opts = {}) {
         `injectExampleLinks` matches on the `language-*` class, never on the code text, so
         highlighting cannot break the "Run this example live" links.
         */
-        await highlightHtml(renderDocMarkdown(stripDocMeta(bookTextOf(doc))), 'none'), bookFiles, slugMap, config.basePath);
+        await highlightHtml(renderDocMarkdown(stripDocMeta(bookTextOf(doc)), { wikilinks }), 'none'), bookFiles, slugMap, config.basePath);
         // happy-dom occasionally throws on exotic content (e.g. an internal selector
         // bug); fall back to the regex pass for that doc rather than aborting.
         let bodyHtml;

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

@@ -12,10 +12,10 @@ component (src/doc-system/*) so static and hydrated output agree.
 */
 import { pageTitle } from '../doc-title.js';
 import { highlightHtml } from '../highlight.js';
-import { buildSlugMap, pathForSlug, rewriteDocLinks, withBase, } from '../routing.js';
+import { buildSlugMap, pathForSlug, rewriteDocLinks, withBase, wikilinkTargets, } from '../routing.js';
 import { buildNavTree, navOpenPath } from '../nav-tree.js';
 import { renderDocMarkdown, docDescription, } from '../render.js';
-import { bareNameLinks, deadInPageAnchors, misconfigured, } from './build-warnings.js';
+import { bareNameLinks, deadInPageAnchors, missingWikilinks, misconfigured, } from './build-warnings.js';
 const escapeAttr = (s) => s
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -111,7 +111,7 @@ export function relativeUrl(depth, p) {
     const rel = '../'.repeat(depth) + p.slice(1);
     return rel === '' ? './' : rel;
 }
-async function pageHtml(doc, config, slugMap, configAttr) {
+async function pageHtml(doc, config, slugMap, configAttr, wikilinks) {
     const { projectName = '', baseUrl = '', lang = 'en', favicon = '/favicon.svg', docsUrl = '/docs.json', scriptUrl = '/iife.js', hydrateUrl, stylesUrl = '/doc-system.css', assetStamp, docsStamp, localizedUrl = '/localized-strings.txt', basePath, headExtra = '', bakes, } = config;
     // Functional URLs are emitted relative to THIS page's depth so the build is
     // mount-agnostic (issue #25); metadata URLs below stay absolute via withBase.
@@ -142,7 +142,10 @@ async function pageHtml(doc, config, slugMap, configAttr) {
     // Rewrite legacy `?filename` content links to clean `/slug/` paths so the
     // static HTML is correct for no-JS readers and crawlers (the doc-browser also
     // does this client-side after hydration).
-    const body = rewriteDocLinks(await highlightHtml(renderDocMarkdown(doc.text, { bakes: bakes?.get(doc.filename) }), 
+    const body = rewriteDocLinks(await highlightHtml(renderDocMarkdown(doc.text, {
+        bakes: bakes?.get(doc.filename),
+        wikilinks,
+    }), 
     // The SAME policy the client will apply, so the build and the browser agree about
     // which blocks are live examples and which are static code to highlight.
     config.liveExamples ?? 'auto'), (filename) => slugMap[filename] !== undefined
@@ -289,6 +292,7 @@ export function withStamp(url, stamp) {
 export async function generateSite(config) {
     const { docs, outputDir } = config;
     const slugMap = buildSlugMap(docs);
+    const wikilinks = wikilinkTargets(docs);
     // Surface any slug collisions (the slug map disambiguates them, but a warning
     // tells the maintainer two docs share a base name).
     const seen = new Map();
@@ -311,26 +315,38 @@ export async function generateSite(config) {
     let count = 0;
     const deadAnchors = [];
     const bareLinks = [];
+    const danglingWikilinks = [];
     for (const doc of docs) {
         const slug = slugMap[doc.filename];
         const dir = slug === '' ? outputDir : `${outputDir}/${slug}`;
-        const rendered = renderDocMarkdown(doc.text);
+        const rendered = renderDocMarkdown(doc.text, { wikilinks });
         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);
+        const dangling = missingWikilinks(rendered);
+        if (dangling.length)
+            danglingWikilinks.push(`    ${doc.path || doc.filename}: ${dangling
+                .map((t) => `[[${t}]]`)
+                .join(', ')}`);
         if (bare.length)
             bareLinks.push(`    ${doc.path || doc.filename}: ${bare.join(', ')}`);
         if (dead.length)
             deadAnchors.push(`    ${doc.path || doc.filename}: ${dead
                 .map((d) => `#${d}`)
                 .join(', ')}`);
-        await Bun.write(`${dir}/index.html`, await pageHtml(doc, config, slugMap, configAttr));
+        await Bun.write(`${dir}/index.html`, await pageHtml(doc, config, slugMap, configAttr, wikilinks));
         // The page's own source, for readers that want text rather than a page.
         if (hasMarkdownPage(doc, config)) {
             await Bun.write(`${dir}/index.md`, doc.text.trimEnd() + '\n');
         }
         count += 1;
     }
+    if (danglingWikilinks.length) {
+        misconfigured(config.strict, `\n⚠️  Wikilinks that reach no doc page. A target matches a page's slug (its file name)\n` +
+            `    or its title; write [[slug|label]] to link one by file name, and an ordinary\n` +
+            `    [label](/path/) for anything that is not a doc page (a static file or app):\n` +
+            `${danglingWikilinks.join('\n')}\n`);
+    }
     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` +

package/dist/doc-system/site/invite-page.d.ts

@@ -17,4 +17,10 @@ export type SessionRejection = 'none' | 'stale' | 'unknown';
  * installed app captures it would bake a credential into a home-screen icon that works once and
  * then fails forever, with no address bar to correct it. Eight characters is the better trade.
  */
-export declare function invitePageHtml(rejection: SessionRejection, linkCommand: string): string;
+export declare function invitePageHtml(rejection: SessionRejection, linkCommand: string, 
+/**
+ * The command for a link that keeps the browser in for good, when this server takes the
+ * preview box's global keys. Without it the page offered only per-visit links, and a reader
+ * whose key cookie had lapsed read that as the daily-link problem coming back (#232).
+ */
+lastingCommand?: string): string;

package/dist/doc-system/site/invite-page.js

@@ -1,6 +1,8 @@
 /*
 The screen someone sees when their session is not good enough.
 */
+import { GLOBAL_KEY_COOKIE_MAX_AGE_S } from './dev-auth.js';
+const LASTING_DAYS = Math.round(GLOBAL_KEY_COOKIE_MAX_AGE_S / 86400);
 /**
  * Why they are here, said plainly.
  *
@@ -36,7 +38,13 @@ function explain(rejection) {
  * installed app captures it would bake a credential into a home-screen icon that works once and
  * then fails forever, with no address bar to correct it. Eight characters is the better trade.
  */
-export function invitePageHtml(rejection, linkCommand) {
+export function invitePageHtml(rejection, linkCommand, 
+/**
+ * The command for a link that keeps the browser in for good, when this server takes the
+ * preview box's global keys. Without it the page offered only per-visit links, and a reader
+ * whose key cookie had lapsed read that as the daily-link problem coming back (#232).
+ */
+lastingCommand) {
     return (`<!doctype html><meta charset=utf-8>` +
         `<title>Link required</title>` +
         `<meta name="viewport" content="width=device-width,initial-scale=1">` +
@@ -62,5 +70,10 @@ export function invitePageHtml(rejection, linkCommand) {
         `border:0;border-radius:6px;background:#0064d2;color:#fff">Open</button>` +
         `</form>` +
         `<p style="opacity:.7">Or, at the machine running the server:</p>` +
-        `<p><code>${linkCommand}</code></p>`);
+        `<p><code>${linkCommand}</code></p>` +
+        (lastingCommand
+            ? `<p style="opacity:.7">For a link that keeps this browser in every workspace on the ` +
+                `preview box, across restarts, for ${LASTING_DAYS} days:</p>` +
+                `<p><code>${lastingCommand}</code></p>`
+            : ''));
 }