tosijs-ui 1.12.7 → 1.12.8

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 1.12.8
+
+### Diffs: pick a side by clicking it, and see what actually changed
+
+Two things, and they apply to **both** diff views — the resolvable one and the read-only one
+used by `<tosi-code>`'s review overlay and the doc-browser's before-save screen.
+
+**Clicking a coloured line picks that side**, equivalent to its button. The line is what a
+reader is already looking at and pointing at; reaching for a small button to say "this one"
+when the thing is under the cursor was friction with nothing behind it. Dragging to select
+text does **not** change anything — those lines are also what you copy from, and without that
+guard, selecting a line to copy it would silently flip the resolution and rewrite the value.
+
+**Within a changed line, the words that actually differ are marked** more strongly than the
+line around them. A whole-line wash says "something here changed", which for a one-word edit
+throws away most of the signal — so the line colour tells you which side you are on, and the
+run tells you what moved. `diffTokens(before, after)` and `tokenRunsForLines(lines)` are
+exported if you want that data without the DOM.
+
+Word runs, not characters: a character diff of `sat` → `sprawled` marks the shared `s` and
+produces confetti. Whitespace and punctuation are tokens so the runs **reassemble each input
+exactly** — a diff viewer that silently drops a space misrepresents the text it exists to show
+— and whitespace between two changed words is absorbed into the change, or `sat on` renders as
+two boxes with a hole punched between them. Lines over 400 tokens fall back to whole-line
+marking rather than locking a tab on a minified bundle pasted into a diff.
+
+The read-only view keeps its line order exactly. Pairing is computed per run of consecutive
+changed lines, so an interleaved edit is marked correctly without the reordering that the
+resolvable view's block grouping does.
+
+`tokenRunsForLines` returns a **dense** array — one entry per input line, `undefined` where a
+line has no runs. Worth stating because the obvious implementation (`new Array(n)`) is sparse,
+and `map`/`forEach` silently skip holes: fine for the indexed read it was written for, a trap
+for anyone iterating it.
+
+### Generated asset URLs are build-stamped
+
+`/doc-system.css` and the hydration bundle are now emitted with a `?v=` stamp taken from the
+same build identity that writes `/version.json`, so a page cannot claim one build while
+loading another's cached bundle. Stale filenames going stale is not hypothetical — it happened
+on this project's own doc site and cost a round of "is this a layout regression?" before
+turning out to be a cached bundle, with a hard reload as the fix nobody thinks to try.
+
+A query rather than content-hashed filenames, deliberately: `docs/` is committed in this repo
+and its siblings, so hashing would add and delete a file on every build and put churn in every
+diff.
+
+**The stamp is the project's own version**, so it moves once per release — the granularity at
+which a published site actually changes — and a rebuild between releases is byte-identical. The
+first attempt derived it from the commit, which was precise and unusable: it re-stamped all 68
+generated pages on every commit, and because the test lanes build too, it did not terminate
+(commit → build → 68 dirty → commit → build). The honest tradeoff of the version, stated rather
+than left to be discovered: two builds of the same version with different code share a stamp, so
+a mid-version redeploy can still serve a cached bundle. That is exactly the previous state — no
+worse — and it closes the case that actually bit, a cached bundle surviving _across_ releases.
+
+Cross-origin URLs are left alone — `scriptUrl` may point at a CDN, and busting someone else's
+cache was never the point — as are URLs that already carry a query or fragment.
+
+Consumers of `tosijs-ui/site` get this automatically; `generateSite` also takes an explicit
+`assetStamp` if you are driving it directly. Leave it unset and the output is unchanged.
+
 ## 1.12.7
 
 ### Live-example and doc-test failures now tell you where

package/dist/diff.d.ts

@@ -39,6 +39,32 @@ export declare function resolveDiff(blocks: DiffBlock[], choices: DiffResolution
  * in `after`), in display order.
  */
 export declare function diffLines(before: string, after: string): DiffLine[];
+/** A run of text within a changed line, flagged if it is part of what actually differs. */
+export interface TokenRun {
+    text: string;
+    changed: boolean;
+}
+/**
+ * Word-level diff of two lines, as runs that reassemble each input exactly.
+ *
+ * Returns everything flagged `changed` when the lines are too long to diff cheaply, or when
+ * they share nothing — in both cases the containing line highlight already says it.
+ */
+export declare function diffTokens(before: string, after: string): {
+    removed: TokenRun[];
+    added: TokenRun[];
+};
+/**
+ * Token runs for each line of a FLAT line diff, pairing within each run of changed lines
+ * without reordering anything.
+ *
+ * The resolvable view groups changes into blocks, which reorders an interleaved edit
+ * (`-a +A -b +B` becomes `-a -b +A +B`) — better to resolve, but a changed rendering. The
+ * read-only view must keep its order exactly, and it turns out it does not have to give
+ * anything up for that: pairing is computed per run of consecutive non-context lines, and the
+ * lines are still emitted where they already were. Same marking, same order.
+ */
+export declare function tokenRunsForLines(lines: DiffLine[]): Array<TokenRun[] | undefined>;
 interface DiffParts extends PartsMap {
     body: HTMLElement;
 }
@@ -68,6 +94,11 @@ export declare class TosiDiff extends Component<DiffParts> {
             whiteSpace: string;
             wordBreak: string;
         };
+        '.diff-line .line-text': {
+            minWidth: string;
+            whiteSpace: string;
+            wordBreak: string;
+        };
         '.diff-line .marker': {
             textAlign: string;
             userSelect: string;
@@ -111,6 +142,22 @@ export declare class TosiDiff extends Component<DiffParts> {
             background: string;
             color: string;
         };
+        '.diff-line .text.changed': {
+            borderRadius: string;
+            padding: string;
+        };
+        '.diff-add .text.changed': {
+            background: string;
+        };
+        '.diff-remove .text.changed': {
+            background: string;
+        };
+        '.diff-line[data-choice]': {
+            cursor: string;
+        };
+        '.diff-line[data-choice]:hover': {
+            filter: string;
+        };
         '.diff-line.not-chosen': {
             opacity: string;
             textDecoration: string;

package/dist/diff.js

@@ -78,6 +78,18 @@ test('rejecting everything yields the original text exactly', () => {
 })
 ```
 
+**Click the coloured text itself** to pick a side — the line is the affordance, so reaching for
+a small button to say "this one" when the thing is right under the cursor is friction with
+nothing behind it. Dragging to select text does *not* change anything: those lines are also
+what you copy from.
+
+Within a changed line, **the words that actually differ** are marked more strongly than the line
+around them. A whole-line wash says "something here changed", which for a one-word edit throws
+away most of the signal — so the line colour tells you which side you are on, and the run tells
+you what moved. `diffTokens(before, after)` is exported if you want that data directly; its runs
+reassemble each input exactly, and it falls back to marking the whole line for lines too long to
+diff cheaply.
+
 The unit of decision is a **change block**, not a line: a multi-line edit is one choice,
 because accepting half of one produces text neither side wrote. Two more exports give you
 the same model without the DOM — `diffBlocks(diffLines(a, b))` for the blocks, and
@@ -184,6 +196,156 @@ export function diffLines(before, after) {
     }
     return out;
 }
+/*
+Tokens, not characters.
+
+A character-level diff of "sat" → "sprawled" marks the shared `s` and produces confetti; word
+runs give a highlight a reader can actually use. Whitespace and punctuation are their own
+tokens so the runs REASSEMBLE the original line exactly — a diff viewer that silently drops a
+space is worse than one that highlights nothing, and the tests assert that reconstruction.
+*/
+const TOKENS = /(\s+|[A-Za-z0-9_$]+|[^\sA-Za-z0-9_$]+)/g;
+/*
+Above this many tokens on either side, skip the intra-line pass and mark the whole line.
+
+The LCS below is O(n·m), and a minified bundle pasted into a diff is one line with tens of
+thousands of tokens — which would lock the tab to draw a highlight nobody can read at that
+size anyway. Bailing keeps the WHOLE-line rendering, which is the previous behaviour, so the
+cap degrades rather than breaks.
+*/
+const MAX_TOKENS = 400;
+/**
+ * Word-level diff of two lines, as runs that reassemble each input exactly.
+ *
+ * Returns everything flagged `changed` when the lines are too long to diff cheaply, or when
+ * they share nothing — in both cases the containing line highlight already says it.
+ */
+export function diffTokens(before, after) {
+    const a = before.match(TOKENS) ?? [];
+    const b = after.match(TOKENS) ?? [];
+    const whole = () => ({
+        removed: before ? [{ text: before, changed: true }] : [],
+        added: after ? [{ text: after, changed: true }] : [],
+    });
+    if (a.length > MAX_TOKENS || b.length > MAX_TOKENS)
+        return whole();
+    const m = a.length;
+    const n = b.length;
+    const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = m - 1; i >= 0; i -= 1) {
+        for (let j = n - 1; j >= 0; j -= 1) {
+            lcs[i][j] =
+                a[i] === b[j]
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const removed = [];
+    const added = [];
+    // Coalesce adjacent tokens of the same kind so the DOM is runs, not one span per word.
+    const push = (out, text, changed) => {
+        const last = out[out.length - 1];
+        if (last && last.changed === changed)
+            last.text += text;
+        else
+            out.push({ text, changed });
+    };
+    let i = 0;
+    let j = 0;
+    while (i < m && j < n) {
+        if (a[i] === b[j]) {
+            push(removed, a[i], false);
+            push(added, b[j], false);
+            i += 1;
+            j += 1;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            push(removed, a[i], true);
+            i += 1;
+        }
+        else {
+            push(added, b[j], true);
+            j += 1;
+        }
+    }
+    while (i < m)
+        push(removed, a[i++], true);
+    while (j < n)
+        push(added, b[j++], true);
+    return { removed: bridgeGaps(removed), added: bridgeGaps(added) };
+}
+/*
+A space BETWEEN two changed words belongs to the change.
+
+`sat on` → `sprawled across` shares its inner space, so the LCS calls it common and the
+highlight comes out as two boxes with a hole punched between them — which reads as two
+unrelated edits rather than one phrase. Whitespace flanked by changed runs on both sides is
+absorbed, and the runs re-coalesce so it renders as a single span.
+*/
+function bridgeGaps(runs) {
+    for (let k = 1; k < runs.length - 1; k += 1) {
+        if (!runs[k].changed &&
+            /^\s+$/.test(runs[k].text) &&
+            runs[k - 1].changed &&
+            runs[k + 1].changed) {
+            runs[k].changed = true;
+        }
+    }
+    const out = [];
+    for (const run of runs) {
+        const last = out[out.length - 1];
+        if (last && last.changed === run.changed)
+            last.text += run.text;
+        else
+            out.push({ ...run });
+    }
+    return out;
+}
+/**
+ * Token runs for each line of a FLAT line diff, pairing within each run of changed lines
+ * without reordering anything.
+ *
+ * The resolvable view groups changes into blocks, which reorders an interleaved edit
+ * (`-a +A -b +B` becomes `-a -b +A +B`) — better to resolve, but a changed rendering. The
+ * read-only view must keep its order exactly, and it turns out it does not have to give
+ * anything up for that: pairing is computed per run of consecutive non-context lines, and the
+ * lines are still emitted where they already were. Same marking, same order.
+ */
+export function tokenRunsForLines(lines) {
+    /*
+    `.fill(undefined)` makes this DENSE. A bare `new Array(n)` is sparse, and `map`/`forEach`
+    silently skip holes — fine for the indexed read this function was written for, a trap for
+    anyone who iterates the result, which an exported function invites.
+    */
+    const out = new Array(lines.length).fill(undefined);
+    let i = 0;
+    while (i < lines.length) {
+        if (lines[i].op === 'context') {
+            i += 1;
+            continue;
+        }
+        let j = i;
+        while (j < lines.length && lines[j].op !== 'context')
+            j += 1;
+        const removes = [];
+        const adds = [];
+        for (let k = i; k < j; k += 1) {
+            ;
+            (lines[k].op === 'remove' ? removes : adds).push(k);
+        }
+        // k-th removed line against the k-th added line; surplus on either side is wholly
+        // added or removed, which the line highlight already says.
+        for (let k = 0; k < Math.min(removes.length, adds.length); k += 1) {
+            const before = lines[removes[k]].text;
+            const after = lines[adds[k]].text;
+            const { removed, added } = diffTokens(before, after);
+            out[removes[k]] = removed;
+            out[adds[k]] = added;
+        }
+        i = j;
+    }
+    return out;
+}
 const MARKER = { context: ' ', add: '+', remove: '-' };
 export class TosiDiff extends Component {
     static preferredTagName = 'tosi-diff';
@@ -234,6 +396,11 @@ export class TosiDiff extends Component {
             whiteSpace: 'pre-wrap',
             wordBreak: 'break-word',
         },
+        '.diff-line .line-text': {
+            minWidth: '0',
+            whiteSpace: 'pre-wrap',
+            wordBreak: 'break-word',
+        },
         '.diff-line .marker': {
             textAlign: 'center',
             userSelect: 'none',
@@ -293,6 +460,31 @@ export class TosiDiff extends Component {
             */
             color: varDefault.tosiDiffChoiceSelectedColor(varDefault.tosiAccentText('#fff')),
         },
+        /*
+        The runs that ACTUALLY differ, distinct from the line that contains them.
+    
+        A whole-line wash says "something here changed" — which for a one-word edit is most of the
+        signal thrown away. These are a second, stronger tint of the SAME hue, so the two read as
+        one system rather than two, and they sit on top of the line colour rather than replacing
+        it: the line still says which side you are on, the run says what moved.
+        */
+        '.diff-line .text.changed': {
+            borderRadius: varDefault.tosiDiffRunRadius('2px'),
+            padding: '0 1px',
+        },
+        '.diff-add .text.changed': {
+            background: varDefault.tosiDiffAddRunBg('color-mix(in srgb, #22c55e 38%, transparent)'),
+        },
+        '.diff-remove .text.changed': {
+            background: varDefault.tosiDiffRemoveRunBg('color-mix(in srgb, #ef4444 38%, transparent)'),
+        },
+        // The coloured lines pick a side, so say so on hover.
+        '.diff-line[data-choice]': {
+            cursor: 'pointer',
+        },
+        '.diff-line[data-choice]:hover': {
+            filter: 'brightness(1.06)',
+        },
         '.diff-line.not-chosen': {
             opacity: '0.4',
             textDecoration: 'line-through',
@@ -371,13 +563,29 @@ export class TosiDiff extends Component {
         only one of the two that survives the boundary, which makes it the right tool here even
         though `target.closest()` is the correct idiom for a light-DOM component.
         */
-        const button = event
+        const picked = event
             .composedPath()
-            .find((node) => node instanceof HTMLElement && node.matches('button[data-hunk]'));
-        if (button === undefined)
+            .find((node) => node instanceof HTMLElement &&
+            node.matches('[data-hunk][data-choice]'));
+        if (picked === undefined)
+            return;
+        /*
+        A click that ENDS A SELECTION is not a choice.
+    
+        The coloured lines are now clickable, and they are also the text someone drags across to
+        copy — so without this, selecting a line to copy it silently flips the resolution and
+        rewrites the value. Checked against the shadow root's own selection where available:
+        `document.getSelection()` reports collapsed for a selection made inside a shadow tree.
+        */
+        const root = this.shadowRoot;
+        const selection = root?.getSelection?.() ?? document.getSelection();
+        if (selection &&
+            !selection.isCollapsed &&
+            selection.toString().length > 0) {
             return;
-        const index = Number(button.dataset.hunk);
-        const choice = button.dataset.choice;
+        }
+        const index = Number(picked.dataset.hunk);
+        const choice = picked.dataset.choice;
         const choices = this.resolutions;
         if (choices[index] === choice)
             return;
@@ -385,10 +593,36 @@ export class TosiDiff extends Component {
         this.queueRender();
         this.dispatchEvent(new Event('change'));
     };
-    lineElement(op, text, chosen = true) {
-        return div({ class: `diff-line diff-${op}${chosen ? '' : ' not-chosen'}` }, span({ class: 'marker' }, MARKER[op]), 
+    lineElement(op, text, chosen = true, runs, hunk) {
+        /*
+        `data-hunk`/`data-choice` on the LINE as well as the buttons, so clicking the coloured
+        text picks that side. The line IS the affordance — it is what the reader is already
+        looking at, and reaching for a small button to say "this one" when the thing is right
+        there under the cursor is friction with nothing behind it.
+        */
+        const pickable = hunk !== undefined && (op === 'add' || op === 'remove')
+            ? {
+                'data-hunk': String(hunk),
+                'data-choice': op === 'remove' ? 'original' : 'modified',
+            }
+            : {};
+        /*
+        ONE grid child for the text, always — the runs go INSIDE it.
+    
+        `.diff-line` is `grid-template-columns: 1.5em 1fr`, so emitting a span per run put the
+        surplus into implicit ROWS: every word stacked vertically down the 1.5em marker column,
+        one character wide. Same failure as #102, where a mismatch between track count and cell
+        count auto-placed the extras into content-sized implicit tracks. A wrapper pins the text
+        to column two no matter how many runs it contains.
+        */
         // Non-breaking fallback so empty lines keep their row height.
-        span({ class: 'text' }, text === '' ? ' ' : text));
+        const body = runs !== undefined && runs.length > 0
+            ? runs.map((run) => span({ class: run.changed ? 'text changed' : 'text' }, run.text))
+            : [span({ class: 'text' }, text === '' ? ' ' : text)];
+        return div({
+            class: `diff-line diff-${op}${chosen ? '' : ' not-chosen'}`,
+            ...pickable,
+        }, span({ class: 'marker' }, MARKER[op]), span({ class: 'line-text' }, ...body));
     }
     render() {
         super.render();
@@ -400,7 +634,14 @@ export class TosiDiff extends Component {
         */
         if (!this.resolvable) {
             const lines = diffLines(this.original, this.modified);
-            this.parts.body.replaceChildren(...lines.map((line) => this.lineElement(line.op, line.text)));
+            /*
+            Intra-line marking applies here too. It was withheld at first on the "additive means
+            additive" rule, but that rule was about the BLOCK GROUPING, which reorders an interleaved
+            edit — marking reorders nothing. The lines, their order and their count are untouched;
+            the only difference is that the words which actually differ are now marked inside them.
+            */
+            const runs = tokenRunsForLines(lines);
+            this.parts.body.replaceChildren(...lines.map((line, k) => this.lineElement(line.op, line.text, true, runs[k])));
             return;
         }
         let changeIndex = -1;
@@ -420,7 +661,18 @@ export class TosiDiff extends Component {
                 'data-choice': value,
                 ariaPressed: String(choice === value),
             }, label);
-            return div({ class: 'diff-hunk', onClick: this.choose }, div({ class: 'diff-choices' }, pick(this.originalLabel, 'original'), pick(this.modifiedLabel, 'modified')), ...block.removed.map((text) => this.lineElement('remove', text, choice === 'original')), ...block.added.map((text) => this.lineElement('add', text, choice === 'modified')));
+            return div({ class: 'diff-hunk', onClick: this.choose }, div({ class: 'diff-choices' }, pick(this.originalLabel, 'original'), pick(this.modifiedLabel, 'modified')), 
+            /*
+            Pair the two sides INDEX-WISE for the intra-line pass. An edit to one line is the
+            overwhelmingly common shape, and a pair is the only case where "what actually
+            changed" is a meaningful question — where the counts differ, the surplus lines are
+            wholly added or removed, which the line highlight already says.
+            */
+            ...block.removed.map((text, k) => this.lineElement('remove', text, choice === 'original', block.added[k] === undefined
+                ? undefined
+                : diffTokens(text, block.added[k]).removed, index)), ...block.added.map((text, k) => this.lineElement('add', text, choice === 'modified', block.removed[k] === undefined
+                ? undefined
+                : diffTokens(block.removed[k], text).added, index)));
         }));
     }
 }

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

@@ -38,6 +38,20 @@ export interface GenerateSiteConfig {
     docsUrl?: string;
     /** path to the IIFE bundle script (default /iife.js) — the CDN/classic-script path */
     scriptUrl?: string;
+    /**
+     * Cache-busting stamp appended to generated asset URLs as `?v=`.
+     *
+     * Stable filenames go stale: a CDN or browser cache can serve yesterday's `hydrate.js`
+     * against today's HTML, and the site then looks broken in a way that reproduces nowhere
+     * else — the fix being a hard reload nobody thinks to try. Content-hashed FILENAMES would
+     * also solve it, and are the wrong trade here: `docs/` is committed in this repo and its
+     * siblings, so hashing would add and delete a file on every build and put churn in every
+     * diff. A query keeps the filenames stable.
+     *
+     * Must be DETERMINISTIC per commit, not per build, for the same reason — see build-stamp.ts.
+     * Left unset, nothing is appended and the output is exactly as before.
+     */
+    assetStamp?: string;
     /**
      * path to an ESM hydration bundle. When set, pages load THIS as a
      * `<script type="module">` instead of the classic IIFE `scriptUrl`, so
@@ -76,4 +90,5 @@ export declare function pageDepth(slug: string): number;
  * origin.) See issue #25; the runtime/SPA-navigation half is issue #16.
  */
 export declare function relativeUrl(depth: number, p: string): string;
+export declare function withStamp(url: string, stamp?: string): string;
 export declare function generateSite(config: GenerateSiteConfig): Promise<number>;

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

@@ -114,7 +114,7 @@ export function relativeUrl(depth, p) {
     return rel === '' ? './' : rel;
 }
 function pageHtml(doc, config, slugMap, configAttr) {
-    const { projectName = '', baseUrl = '', lang = 'en', favicon = '/favicon.svg', docsUrl = '/docs.json', scriptUrl = '/iife.js', hydrateUrl, stylesUrl = '/doc-system.css', localizedUrl = '/localized-strings.txt', basePath, headExtra = '', bakes, } = config;
+    const { projectName = '', baseUrl = '', lang = 'en', favicon = '/favicon.svg', docsUrl = '/docs.json', scriptUrl = '/iife.js', hydrateUrl, stylesUrl = '/doc-system.css', assetStamp, 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.
     const depth = pageDepth(slugMap[doc.filename] ?? '');
@@ -169,7 +169,7 @@ function pageHtml(doc, config, slugMap, configAttr) {
         '  <link rel="preconnect" href="https://fonts.googleapis.com" />',
         '  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />',
         // Burned-in theme: styles the page with no JS and with zero flash on hydration.
-        `  <link rel="stylesheet" href="${escapeAttr(relativeUrl(depth, stylesUrl))}" data-tosi-doc-system />`,
+        `  <link rel="stylesheet" href="${escapeAttr(withStamp(relativeUrl(depth, stylesUrl), assetStamp))}" data-tosi-doc-system />`,
         `  <title>${escapeText(title)}</title>`,
         description
             ? `  <meta name="description" content="${escapeAttr(description)}" />`
@@ -240,12 +240,28 @@ ${nav}
 ${navbar}
   </tosi-doc-system>
   ${hydrateUrl
-        ? `<script type="module" src="${escapeAttr(relativeUrl(depth, hydrateUrl))}"></script>`
-        : `<script src="${escapeAttr(relativeUrl(depth, scriptUrl))}"></script>`}
+        ? `<script type="module" src="${escapeAttr(withStamp(relativeUrl(depth, hydrateUrl), assetStamp))}"></script>`
+        : `<script src="${escapeAttr(withStamp(relativeUrl(depth, scriptUrl), assetStamp))}"></script>`}
 </body>
 </html>
 `;
 }
+/*
+Append the build stamp to a SAME-ORIGIN asset URL.
+
+Only same-origin: `scriptUrl` may legitimately point at a CDN, and appending a query to
+someone else's URL can miss their cache key or, worse, be rejected. A URL that already carries
+a query is left alone — the caller has said something deliberate about it.
+*/
+export function withStamp(url, stamp) {
+    if (!stamp)
+        return url;
+    if (url.includes('?') || url.includes('#'))
+        return url;
+    if (/^[a-z][a-z0-9+.-]*:|^\/\//i.test(url))
+        return url;
+    return `${url}?v=${encodeURIComponent(stamp)}`;
+}
 export async function generateSite(config) {
     const { docs, outputDir } = config;
     const slugMap = buildSlugMap(docs);

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

@@ -789,34 +789,10 @@ export async function buildSite(config, opts = {}) {
             // Generate the static, pre-rendered doc site (one /slug/index.html per doc).
             // Runs after the static-asset copy so the generated index.html (README) wins,
             // and after the bundle copy so every page's <script src> resolves.
-            const docs = JSON.parse(await Bun.file(DOCS_JSON).text());
-            const pageCount = await generateSite({
-                docs,
-                outputDir: PUBLIC,
-                projectName: config.name,
-                description: config.description,
-                baseUrl: config.baseUrl,
-                lang: config.lang,
-                projectLinks: config.projectLinks,
-                logo: config.logo,
-                navbarLinks: config.navbarLinks,
-                localizedStrings: config.localizedStrings,
-                favicon: config.favicon,
-                ogImage: config.ogImage,
-                // When set, pages load this as a `<script type="module">` (editor lazy-split)
-                // instead of the classic IIFE. See the ESM hydration bundle above.
-                hydrateUrl: hydrateName ? `/${hydrateName}` : undefined,
-                bakes: exampleBakes,
-                headExtra: [config.headExtra, tjsHead, importResolverHead]
-                    .filter(Boolean)
-                    .join('') || undefined,
-                scriptUrl: config.scriptUrl,
-                basePath: config.basePath,
-            });
             // Build identity at /version.json — "what am I looking at?" for any deployed copy.
             // Deterministic (commit-derived, no wall clock) so a committed outputDir doesn't
             // churn on every build. See build-stamp.ts.
-            await Bun.write(`${PUBLIC}/version.json`, serializeBuildStamp(await gatherBuildStamp({
+            const buildStamp = await gatherBuildStamp({
                 // Read package.json rather than importing the generated src/version.ts —
                 // that import put a generated file in `bun --watch`'s module graph while
                 // prebuild rewrote it every build, i.e. a rebuild loop (899 restarts in
@@ -838,7 +814,70 @@ export async function buildSite(config, opts = {}) {
                     .then((p) => p.version ?? 'unknown')
                     .catch(() => 'unknown'),
                 site: config.name,
-            })));
+            });
+            /*
+            One stamp, two uses: `/version.json` answers "what am I looking at?", and the same value
+            busts asset caches as `?v=`. Derived once so they cannot disagree — a page claiming one
+            build while loading another's bundle is the exact confusion this is meant to end.
+      
+            Commit-derived, so a rebuild at the same commit produces byte-identical output and a
+            committed `docs/` does not churn. Falls back to the generator version when git is
+            unavailable (a consumer may not be in a repo at all), which still busts on upgrade.
+            */
+            /*
+            Stamp from the PROJECT'S VERSION, not its commit.
+      
+            A commit-derived stamp re-stamps every generated page on every commit, and `docs/` is
+            committed here and in the sibling projects — so a 68-file diff appeared on each build,
+            and it did not terminate: the test lanes build too, so commit → build → dirty → commit.
+            That is the same non-terminating loop this repo already documents for release
+            annotations, and it is worse than the staleness it was added to fix.
+      
+            A version changes once per release, which is the granularity a published site actually
+            changes at, and it leaves a rebuild byte-identical between releases.
+      
+            The tradeoff, stated rather than discovered later: two builds of the SAME version with
+            different code carry the same stamp, so a mid-version redeploy can still serve a cached
+            bundle. That is no worse than having no stamp at all, which was the previous state, and
+            it closes the case that actually bit — a cached bundle surviving across releases.
+      
+            Read from the CONSUMER's cwd, deliberately: this must be the version of the site being
+            built, not tosijs-ui's. (`generator` is read from this module's own package.json for the
+            opposite reason — see the note below.) Falls back to the generator version, then the
+            commit, so a project without a version still gets something that moves.
+            */
+            const assetStamp = (await Bun.file(`${process.cwd()}/package.json`)
+                .json()
+                .then((p) => p.version)
+                .catch(() => undefined)) ??
+                buildStamp.generator ??
+                buildStamp.commit;
+            const docs = JSON.parse(await Bun.file(DOCS_JSON).text());
+            const pageCount = await generateSite({
+                docs,
+                outputDir: PUBLIC,
+                projectName: config.name,
+                description: config.description,
+                baseUrl: config.baseUrl,
+                lang: config.lang,
+                projectLinks: config.projectLinks,
+                logo: config.logo,
+                navbarLinks: config.navbarLinks,
+                localizedStrings: config.localizedStrings,
+                favicon: config.favicon,
+                ogImage: config.ogImage,
+                // When set, pages load this as a `<script type="module">` (editor lazy-split)
+                // instead of the classic IIFE. See the ESM hydration bundle above.
+                hydrateUrl: hydrateName ? `/${hydrateName}` : undefined,
+                bakes: exampleBakes,
+                headExtra: [config.headExtra, tjsHead, importResolverHead]
+                    .filter(Boolean)
+                    .join('') || undefined,
+                scriptUrl: config.scriptUrl,
+                basePath: config.basePath,
+                assetStamp,
+            });
+            await Bun.write(`${PUBLIC}/version.json`, serializeBuildStamp(buildStamp));
             // Burn the theme into a static stylesheet (separate subprocess — see
             // generate-css.ts). Resolve the sibling relative to THIS module so it works
             // both in-repo (.ts) and when shipped (compiled .js).