tosijs-ui 1.7.1 → 1.7.3

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 1.7.3
+
+- **New `<tosi-pocket-bar>` component.** A "pocket buttonbar": a single translucent icon at
+  rest that expands into a bar of slotted icon-button controls on hover/tap, then collapses
+  again. `direction` (the full `FloatPosition` vocabulary, `auto` by default) determines both
+  layout and growth direction; the handle stays put and toggles the bar; touch counts as hover.
+  Built as a thin wrapper around `positionFloat`.
+- **The live-example toolbar is now a pocket bar**, pinned to the top-right of the preview (so
+  it never sits over the code editors in side-by-side mode). The collapsed handle carries the
+  example's pass/fail color, "run tests" is a checkbox that greys when off, and the bar stays
+  visible when the example is maximized.
+- **Build system is fragility-tolerant.** An *unsupported import* in a live example (a bare
+  specifier the runtime can't resolve) now downgrades that block to display-only with a warning
+  instead of failing the whole build; genuine syntax errors still fail the build.
+- **Removed a render-skip anti-pattern** from `<tosi-segmented>`, `<tosi-color>`, and
+  `<tosi-form>`. They previously depended on `render()` being *skipped* after interaction via a
+  `valueChanged` flag — fragile timing that broke under tosijs's parts changes. Renders are now
+  idempotent: they skip only *provably-redundant* writes by comparing values (colors compared
+  **parsed**, so a `#rrggbb ↔ rgba()` round-trip no longer clobbers the caret/selection in the
+  field being edited).
+- **Code editor background is now a neutral off-white** (off-black in dark mode) instead of a
+  brand-tinted color — both the default `<tosi-code>` and live examples.
+- **Fix: nav flickered on refresh / reflowed on hydration.** The static no-JS nav relied on the
+  browser's native `<details>` collapse (`::details-content { content-visibility: hidden }`),
+  which Chromium applies lazily and non-deterministically on first paint — a closed section
+  could render at full height for a frame before snapping shut. Closed sections now collapse
+  synchronously via `display: none` (still opening on a no-JS `<summary>` toggle). Enforced by
+  `tests/hydration.pw.ts`.
+- **Moved the doc-browser test-counter widget to the bottom-left** so it no longer sits under
+  the haltija dev overlay.
+- **tosijs bumped to `^1.7.8`**, which fixes the `this.parts` proxy crossing into nested
+  component instances (tosijs#20 — surfaced by the self-hosting doc demo, where clicking "edit"
+  on one example opened the editor in the wrong one) and change-handler value staleness
+  (tosijs#21).
+
+## 1.7.2
+
+- **Fix: doc sites are now mount-point-agnostic** (issue #25). The build baked `basePath` into
+  every functional URL (nav/content links, `scriptUrl`, `stylesUrl`, favicon, `docsUrl`), so a
+  build was locked to one mount — adding a custom domain to a GitHub project page flipped the
+  live site to the root while `docs/` still pointed at `/repo`, 404ing every asset into a bare,
+  unstyled shell with no warning. Functional URLs are now emitted **relative to each page**, so
+  one build works at `/repo`, a custom-domain root, or a moved mount with no rebuild. *Metadata*
+  URLs (`canonical`, `og:url`, `og:image`, `sitemap.xml`) stay absolute via `baseUrl`+`basePath`
+  — so `basePath` now only affects metadata, never the page's assets. (The hydrated SPA's own
+  nav/`pushState` and `__TJS_LOCAL_BASE` remain root-relative — tracked in #16.)
+- **Fix: the haltija dev channel loaded once per background-test iframe.** The doc-browser's
+  background test runner loads every page-with-tests in a hidden iframe, each served the injected
+  dev-channel loader — so `dev.js` was imported N times into throwaway frames. The loader is now
+  gated to the top window (`self===top`).
+- **Live examples get a rounded, padded card.** `.preview` gains `padding` (breathing room around
+  rendered content) and its first child's top margin is dropped; the inset border moves to the
+  example's `:host` with a `border-radius`, so the whole example (preview + editors) reads as one
+  bordered card. CodeMirror tooltips render fixed-positioned so autocomplete isn't clipped by the
+  card's `overflow: hidden`.
+- **Removed the "blueprint loading" doc page.** It documented tosijs's own
+  `<xin-loader>`/`<xin-blueprint>` elements (no tosijs-ui component), so it belongs in tosijs's
+  docs. The generic `blueprint` icon stays.
+
 ## 1.7.1
 
 - **Fix: components looked wrong in the doc site's dark mode** (e.g. `<tosi-table>` stayed

package/dist/code-editor-cm.js

@@ -10,7 +10,7 @@ Languages here are the always-available set (js/ts/css/html/markdown). First-cla
 tjs (highlighting + runtime-value autocomplete via tjs-lang's editors/codemirror) is
 layered in separately and only when tjs-lang is installed.
 */
-import { EditorView, keymap, lineNumbers, highlightActiveLineGutter, highlightSpecialChars, drawSelection, dropCursor, rectangularSelection, crosshairCursor, highlightActiveLine, } from '@codemirror/view';
+import { EditorView, keymap, lineNumbers, highlightActiveLineGutter, highlightSpecialChars, drawSelection, dropCursor, rectangularSelection, crosshairCursor, highlightActiveLine, tooltips, } from '@codemirror/view';
 import { EditorState, Compartment, Annotation, Transaction, } from '@codemirror/state';
 import { indentWithTab, history, defaultKeymap, historyKeymap, undo, redo, undoDepth, redoDepth, } from '@codemirror/commands';
 import { indentUnit, foldGutter, foldKeymap, indentOnInput, syntaxHighlighting, defaultHighlightStyle, bracketMatching, } from '@codemirror/language';
@@ -129,6 +129,10 @@ const editorTheme = EditorView.theme({
 function baseExtensions() {
     return [
         editorTheme,
+        // Render autocomplete / hover tooltips in a fixed layer so they escape the
+        // live-example's `:host { overflow: hidden }` (the rounded card clip) instead
+        // of being cut off at the editor's bottom edge in a short example.
+        tooltips({ position: 'fixed' }),
         lineNumbers(),
         highlightActiveLineGutter(),
         highlightSpecialChars(),

package/dist/color-input.d.ts

@@ -33,7 +33,6 @@ declare class ColorInput extends Component<ColorParts> {
         };
     };
     content: HTMLInputElement[];
-    private valueChanged;
     update: (event: Event) => void;
     connectedCallback(): void;
     render(): void;

package/dist/color-input.js

@@ -71,7 +71,6 @@ class ColorInput extends Component {
         }),
         input({ title: 'css color spec', part: 'css' }),
     ];
-    valueChanged = false;
     update = (event) => {
         const { rgb, alpha, css } = this.parts;
         if (event.type === 'input') {
@@ -86,7 +85,6 @@ class ColorInput extends Component {
         }
         rgb.style.opacity = String(this.color.a);
         this.value = this.color.rgba;
-        this.valueChanged = true;
     };
     connectedCallback() {
         super.connectedCallback();
@@ -96,16 +94,32 @@ class ColorInput extends Component {
         css.addEventListener('change', this.update);
     }
     render() {
-        if (this.valueChanged) {
-            this.valueChanged = false;
-            return;
-        }
         const { rgb, alpha, css } = this.parts;
         this.color = Color.fromCss(this.value);
-        rgb.value = this.color.html.substring(0, 7);
-        rgb.style.opacity = String(this.color.a);
-        alpha.value = String(this.color.a);
-        css.value = this.color.html;
+        const rgba = this.color.rgba;
+        const alphaStr = String(this.color.a);
+        // Idempotent: only WRITE an input whose value doesn't already represent this
+        // colour. Compare the PARSED colour, not the string — `#rrggbb` and `rgba(...)`
+        // are the same colour, so a string compare (or a blind write) would clobber the
+        // caret / selection and re-round-trip the user's format on the field they're
+        // editing, every render. Skipping provably-redundant work is right; a `valueChanged`
+        // timing flag to decide it was the fragile part (broke under tosijs 1.7.7).
+        const sameColor = (v) => {
+            try {
+                return Color.fromCss(v).rgba === rgba;
+            }
+            catch {
+                return false;
+            }
+        };
+        if (!sameColor(rgb.value))
+            rgb.value = this.color.html.substring(0, 7);
+        if (rgb.style.opacity !== alphaStr)
+            rgb.style.opacity = alphaStr;
+        if (alpha.value !== alphaStr)
+            alpha.value = alphaStr;
+        if (!sameColor(css.value))
+            css.value = this.color.html;
     }
 }
 export const colorInput = ColorInput.elementCreator();

package/dist/doc-browser.js

@@ -206,12 +206,14 @@ const testIndicatorStyleSpec = {
         background: testColor.fail,
         animation: 'test-pulse 2s ease-in-out infinite',
     },
-    // Floating widget - position and colors only, inherits button structure
+    // 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.
     '.test-widget': {
         _testBg: testColor.running,
         position: 'fixed',
         bottom: vars.spacing,
-        right: vars.spacing,
+        left: vars.spacing,
         zIndex: '1000',
         background: vars.testBg,
         color: 'white',

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

@@ -8,6 +8,8 @@ export interface DocSystemTheme {
     text?: string;
     buttonBg?: string;
     inputBg?: string;
+    /** code-editor surface (`--code-bg`); neutral off-white by default, not brand-tinted. */
+    codeBg?: string;
 }
 /** Compute the full set of `:root` color variables from a few base colors. */
 export declare function docSystemColors(theme?: DocSystemTheme): XinStyleRule;

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

@@ -34,7 +34,9 @@ export function docSystemColors(theme = {}) {
         _placeholderColor: brandColor.opacity(0.4),
         _brandTextColor: brandColor.rotate(30).brighten(0.9),
         _insetBg: brandColor.rotate(45).brighten(0.8),
-        _codeBg: brandColor.rotate(-15).desaturate(0.5).brighten(0.9),
+        // Neutral off-white (not brand-tinted); dark mode inverts its luminance to
+        // off-black, so the editor surface stays a clean neutral in both themes.
+        _codeBg: theme.codeBg ?? '#fdfdfd',
         _linkColor: brandColor.rotate(-30).darken(0.5),
         _shadowColor: '#0004',
         _menuBg: '#fafafa',
@@ -476,6 +478,18 @@ export function docSystemStyleSpec(theme = {}) {
         '.doc-nav details > ul': {
             paddingLeft: vars.spacing,
         },
+        // Collapse a closed section's list SYNCHRONOUSLY. The UA collapses <details>
+        // via `::details-content { content-visibility: hidden }`, which is applied
+        // lazily and — for this static tree — non-deterministically on first paint:
+        // sometimes the closed section is still laid out at full height for a frame
+        // before it snaps shut. That frame is a visible flicker on refresh, and it made
+        // the "nav does not move on hydration" test measure a 36px row that hydration
+        // then collapses to 0. An explicit display:none collapses it in the first layout
+        // pass with no content-visibility race, and still opens on a no-JS <summary>
+        // toggle (the UA adds [open], so this rule stops matching).
+        '.doc-nav details:not([open]) > ul': {
+            display: 'none',
+        },
         // <summary> is the section header (its triangle toggles; the link navigates).
         '.doc-nav summary': {
             cursor: 'pointer',

package/dist/doc-system/site/check-examples-cli.js

@@ -20,8 +20,9 @@ the bundle step, the ePub step, and generate-css; see the Bun.build note in
 orchestrator.ts.
 
   bun check-examples-cli.ts <docs.json> [contextKey ...]
-  → writes ExampleProblem[] as JSON to stdout; exit 0 whether or not problems were
-    found (a problem is data, not a crash — only a real failure exits non-zero).
+  → writes { problems, warnings, bakes } as JSON to stdout; exit 0 whether or not
+    problems were found (a problem is data, not a crash — only a real failure exits
+    non-zero). The parent fails the build on `problems`, warns on `warnings`.
 
 Build-time only. Never import this from browser code.
 */
@@ -36,7 +37,7 @@ const contextKeys = process.argv.slice(3);
 // non-context imports validate as dynamic `<prefix><spec>` imports rather than failing.
 const importPrefix = process.env.TOSI_IMPORT_PREFIX || undefined;
 const corpus = JSON.parse(await Bun.file(docsJson).text());
-const { problems, bakes } = await checkExamples(corpus, {
+const { problems, warnings, bakes } = await checkExamples(corpus, {
     ...(contextKeys.length ? { contextKeys } : {}),
     ...(importPrefix ? { importPrefix } : {}),
 });
@@ -45,6 +46,7 @@ const { problems, bakes } = await checkExamples(corpus, {
 // Maps can't JSON-roundtrip, so bakes go over as [filename, [source, {dialect,js}][]][].
 process.stdout.write(JSON.stringify({
     problems,
+    warnings,
     bakes: Array.from(bakes.entries()).map(([filename, docBakes]) => [
         filename,
         Array.from(docBakes.entries()),

package/dist/doc-system/site/check-examples.d.ts

@@ -8,7 +8,20 @@ export interface ExampleProblem {
     snippet: string;
 }
 export interface ExampleCheck {
+    /**
+     * Blocks that failed to build for a real reason (a tjs/TS syntax error, a
+     * transpile failure). These FAIL the build — broken code shouldn't ship.
+     */
     problems: ExampleProblem[];
+    /**
+     * Blocks that reference a package the environment can't provide (a non-context
+     * import, no import-resolver). The code isn't broken, it just can't run here —
+     * almost always illustrative code that should be tagged `typescript` (display-
+     * only) rather than `ts`. These WARN and are treated as display-only; they do
+     * NOT fail the build. (Enable `importResolver`, or tag the block display-only,
+     * to silence the warning.)
+     */
+    warnings: ExampleProblem[];
     /**
      * Build-time transpiled JS for `tjs` blocks, grouped by doc filename, each keyed
      * by exact source text. The renderer embeds a doc's bakes as hidden scripts (so

package/dist/doc-system/site/check-examples.js

@@ -4,17 +4,25 @@ Build-time transpile check for live examples.
 Every executable code block in the corpus (`js` / `tjs` / `ts` / `test`) is put
 through the SAME front half of the runtime pipeline the live-example component
 uses — `rewriteImports` → the tjs-lang transform → `new AsyncFunction(...)` — so a
-block that can't build (a tjs/TS syntax error, an unsupported import, or
-illustrative config mistakenly tagged with an executable language like `ts`
-instead of the display-only `typescript`) fails the build *at authoring time*,
-on every page, instead of silently rendering an error only when someone opens
-that page. `html` / `css` and display-only languages (`typescript`, `json`, …)
-are not executed, so they're skipped.
+block that can't build is caught *at authoring time*, on every page, instead of
+silently rendering an error only when someone opens that page. The two outcomes
+are graded differently (this is the point):
+
+  - a real **syntax / transpile error** is broken code → a `problem` that FAILS
+    the build;
+  - an **unsupported import** (a non-context package, no import-resolver) is fine
+    code the doc environment just can't run → a `warning`: the block is treated as
+    display-only and the build survives. It's almost always illustrative code that
+    should have been tagged `typescript` instead of `ts` — a mistagging shouldn't
+    take the whole build down with it.
+
+`html` / `css` and display-only languages (`typescript`, `json`, …) are not
+executed, so they're skipped.
 
 Build-time only (bun). Never import from browser code.
 */
 import { marked } from 'marked';
-import { rewriteImports, AsyncFunction, loadTransform, } from '../../live-example/code-transform';
+import { rewriteImports, AsyncFunction, loadTransform, UnsupportedImportError, } from '../../live-example/code-transform';
 // The default live-example context (matches the IIFE globals the pages provide).
 // A project that sets a custom `context` on its <tosi-doc-system> can pass its
 // own keys; these are the tosijs-ui defaults.
@@ -58,6 +66,7 @@ function collectCodeTokens(text) {
 export async function checkExamples(docs, opts = {}) {
     const contextKeys = opts.contextKeys ?? DEFAULT_CONTEXT_KEYS;
     const problems = [];
+    const warnings = [];
     const bakes = new Map();
     for (const doc of docs) {
         for (const block of collectCodeTokens(doc.text)) {
@@ -97,17 +106,24 @@ export async function checkExamples(docs, opts = {}) {
                 }
             }
             catch (err) {
-                problems.push({
+                const entry = {
                     filename: doc.filename,
                     title: doc.title,
                     lang: block.lang,
                     error: err.message || String(err),
                     snippet: block.text.split('\n').slice(0, 3).join('\n'),
-                });
+                };
+                // An unsupported import means the block references deps the environment
+                // can't provide — not broken code. Warn (display-only), don't fail the
+                // build. A real syntax/transpile error is a genuine problem.
+                if (err instanceof UnsupportedImportError)
+                    warnings.push(entry);
+                else
+                    problems.push(entry);
             }
         }
     }
-    return { problems, bakes };
+    return { problems, warnings, bakes };
 }
 /** Format problems for a build log. */
 export function formatExampleProblems(problems) {

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

@@ -28,6 +28,17 @@ export declare function resolveIdleMs(configHours: number | undefined, envHours:
  * off. Only an explicit non-positive number disables the ceiling.
  */
 export declare function resolveLimitMb(configMb: number | undefined, envMb: string | undefined): number;
+/**
+ * The localhost-gated haltija dev-channel loader injected into served HTML at
+ * serve time (never bundled, never in the built output).
+ *
+ * `self===top` keeps it in the TOP window only. The doc-browser's background test
+ * runner loads every page-with-tests in a hidden iframe (`?_testMode=1`), each
+ * served this same HTML — without the guard, haltija's `dev.js` gets imported
+ * once per test page (N redundant loads in throwaway frames). An agent only ever
+ * drives the top page, so nested frames never need the channel.
+ */
+export declare function haltijaLoaderSnippet(httpsPort: number): string;
 export declare function devServer(config: SiteConfig, opts?: {
     test?: boolean;
     build?: () => unknown | Promise<unknown>;

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

@@ -78,6 +78,20 @@ export function resolveLimitMb(configMb, envMb) {
     const mb = Number.isFinite(raw) ? raw : DEFAULT_LIMIT_MB;
     return mb > 0 ? mb : 0;
 }
+/**
+ * The localhost-gated haltija dev-channel loader injected into served HTML at
+ * serve time (never bundled, never in the built output).
+ *
+ * `self===top` keeps it in the TOP window only. The doc-browser's background test
+ * runner loads every page-with-tests in a hidden iframe (`?_testMode=1`), each
+ * served this same HTML — without the guard, haltija's `dev.js` gets imported
+ * once per test page (N redundant loads in throwaway frames). An agent only ever
+ * drives the top page, so nested frames never need the channel.
+ */
+export function haltijaLoaderSnippet(httpsPort) {
+    return (`<script>self===top&&/^localhost$|^127\\./.test(location.hostname)` +
+        `&&import('https://localhost:${httpsPort}/dev.js')</script>`);
+}
 /**
  * Reclaim the port we are about to bind, from the process LISTENING on it.
  *
@@ -259,8 +273,7 @@ export async function devServer(config, opts = {}) {
         (config.haltijaDev === true ||
             process.env.HALTIJA_DEV === '1' ||
             process.env.HALTIJA_DEV === 'true');
-    const HALTIJA_SNIPPET = `<script>/^localhost$|^127\\./.test(location.hostname)` +
-        `&&import('https://localhost:${HALTIJA_HTTPS_PORT}/dev.js')</script>`;
+    const HALTIJA_SNIPPET = haltijaLoaderSnippet(HALTIJA_HTTPS_PORT);
     let testReportResolve;
     // Source read/write for in-browser "edit page source" (config.editableSources).
     // Local dev only — your machine, your files — so the lone guard is correctness:

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

@@ -56,4 +56,22 @@ export interface GenerateSiteConfig {
     /** extra lines injected into every <head> (favicon, analytics, etc.) */
     headExtra?: string;
 }
+/**
+ * Depth of a page below the site root: 0 for the root index (served at the mount
+ * root), 1 for every `/slug/` page. The generator only ever emits a flat `/slug/`
+ * tree (see `pathForSlug`), so a non-root page is always exactly one directory deep.
+ */
+export declare function pageDepth(slug: string): number;
+/**
+ * Rewrite a root-relative *functional* URL (asset ref, nav / content link) to be
+ * relative to a page at `depth`, so ONE build works at ANY mount point — a GitHub
+ * project page under `/repo`, a custom-domain root, or a moved mount — with no
+ * `basePath` rebuild. Relative URLs resolve against wherever the page is actually
+ * served, so `basePath` is deliberately NOT applied here: a page at `/repo/x/`
+ * gets `../styles.css` → `/repo/styles.css`, the same page at `/x/` gets it at
+ * `/styles.css`. External (`https://…`, `//…`) and already-relative refs pass
+ * through untouched. (Metadata URLs still use `withBase` — they need the absolute
+ * origin.) See issue #25; the runtime/SPA-navigation half is issue #16.
+ */
+export declare function relativeUrl(depth: number, p: string): string;
 export declare function generateSite(config: GenerateSiteConfig): Promise<number>;

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

@@ -27,11 +27,11 @@ const escapeText = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace
  * <details> on the path to `currentFilename` opened. `currentFilename` gets
  * aria-current. Crawlable + no-JS: every node is a real <a>.
  */
-function navHtml(docs, slugMap, currentFilename, basePath) {
+function navHtml(docs, slugMap, currentFilename, depth) {
     const roots = buildNavTree(docs, slugMap);
     const open = navOpenPath(roots, currentFilename);
     const renderNode = (node, indent) => {
-        const href = withBase(basePath, pathForSlug(node.slug));
+        const href = relativeUrl(depth, pathForSlug(node.slug));
         const current = node.doc.filename === currentFilename;
         // `doc-link` is what the HYDRATED nav emits, and the shared nav CSS is written
         // against it. Emitting a bare <a> here forced a second, hand-copied rule set under
@@ -78,16 +78,48 @@ function absUrl(baseUrl, pathOrUrl) {
 /**
  * Prefix a root-relative path with basePath. No-op for '/', empty, protocol-
  * relative (`//…`), or absolute (`https://…`) URLs.
+ *
+ * Used ONLY for *metadata* URLs now (canonical, og:url, og:image, sitemap) — they
+ * legitimately need the real absolute origin+path. *Functional* URLs go through
+ * `relativeUrl` instead, so the artifact is mount-agnostic. See `relativeUrl`.
  */
 function withBase(basePath, p) {
     if (!p || !basePath || basePath === '/' || /^(https?:)?\/\//.test(p))
         return p;
     return basePath.replace(/\/$/, '') + (p.startsWith('/') ? p : '/' + p);
 }
+/**
+ * Depth of a page below the site root: 0 for the root index (served at the mount
+ * root), 1 for every `/slug/` page. The generator only ever emits a flat `/slug/`
+ * tree (see `pathForSlug`), so a non-root page is always exactly one directory deep.
+ */
+export function pageDepth(slug) {
+    return slug === '' ? 0 : 1;
+}
+/**
+ * Rewrite a root-relative *functional* URL (asset ref, nav / content link) to be
+ * relative to a page at `depth`, so ONE build works at ANY mount point — a GitHub
+ * project page under `/repo`, a custom-domain root, or a moved mount — with no
+ * `basePath` rebuild. Relative URLs resolve against wherever the page is actually
+ * served, so `basePath` is deliberately NOT applied here: a page at `/repo/x/`
+ * gets `../styles.css` → `/repo/styles.css`, the same page at `/x/` gets it at
+ * `/styles.css`. External (`https://…`, `//…`) and already-relative refs pass
+ * through untouched. (Metadata URLs still use `withBase` — they need the absolute
+ * origin.) See issue #25; the runtime/SPA-navigation half is issue #16.
+ */
+export function relativeUrl(depth, p) {
+    if (!p || /^(https?:)?\/\//.test(p) || !p.startsWith('/'))
+        return p;
+    const rel = '../'.repeat(depth) + p.slice(1);
+    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;
+    // 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] ?? '');
     const localizedAttr = config.localizedStrings
-        ? ` localized="${escapeAttr(withBase(basePath, localizedUrl))}"`
+        ? ` localized="${escapeAttr(relativeUrl(depth, localizedUrl))}"`
         : '';
     // 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).
@@ -103,9 +135,9 @@ function pageHtml(doc, config, slugMap, configAttr) {
     // static HTML is correct for no-JS readers and crawlers (the doc-browser also
     // does this client-side after hydration).
     const body = rewriteDocLinks(renderDocMarkdown(doc.text, { bakes: bakes?.get(doc.filename) }), (filename) => slugMap[filename] !== undefined
-        ? withBase(basePath, pathForSlug(slugMap[filename]))
+        ? relativeUrl(depth, pathForSlug(slugMap[filename]))
         : null);
-    const nav = navHtml(config.docs, slugMap, doc.filename, basePath);
+    const nav = navHtml(config.docs, slugMap, doc.filename, depth);
     const navbar = linkListHtml('doc-navbar', config.navbarLinks);
     const jsonLd = baseUrl
         ? jsonLdScript({
@@ -126,7 +158,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(withBase(basePath, stylesUrl))}" data-tosi-doc-system />`,
+        `  <link rel="stylesheet" href="${escapeAttr(relativeUrl(depth, stylesUrl))}" data-tosi-doc-system />`,
         `  <title>${escapeText(title)}</title>`,
         description
             ? `  <meta name="description" content="${escapeAttr(description)}" />`
@@ -155,7 +187,7 @@ function pageHtml(doc, config, slugMap, configAttr) {
             ? `  <meta name="twitter:image" content="${escapeAttr(imageAbs)}" />`
             : '',
         jsonLd,
-        `  <link rel="icon" href="${escapeAttr(withBase(basePath, favicon))}" />`,
+        `  <link rel="icon" href="${escapeAttr(relativeUrl(depth, favicon))}" />`,
         headExtra,
     ]
         .filter(Boolean)
@@ -189,7 +221,7 @@ function pageHtml(doc, config, slugMap, configAttr) {
 ${head}
 </head>
 <body>
-  <tosi-doc-system docs="${escapeAttr(withBase(basePath, docsUrl))}" config="${configAttr}"${localizedAttr}>
+  <tosi-doc-system docs="${escapeAttr(relativeUrl(depth, docsUrl))}" config="${configAttr}"${localizedAttr}>
   <article class="doc-content">
 ${body}
   </article>
@@ -197,8 +229,8 @@ ${nav}
 ${navbar}
   </tosi-doc-system>
   ${hydrateUrl
-        ? `<script type="module" src="${escapeAttr(withBase(basePath, hydrateUrl))}"></script>`
-        : `<script src="${escapeAttr(withBase(basePath, scriptUrl))}"></script>`}
+        ? `<script type="module" src="${escapeAttr(relativeUrl(depth, hydrateUrl))}"></script>`
+        : `<script src="${escapeAttr(relativeUrl(depth, scriptUrl))}"></script>`}
 </body>
 </html>
 `;

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

@@ -132,6 +132,7 @@ async function checkExamplesInChild(docsJson, importPrefix) {
         const payload = JSON.parse(out);
         return {
             problems: payload.problems,
+            warnings: payload.warnings ?? [],
             bakes: new Map(payload.bakes.map(([file, e]) => [file, new Map(e)])),
         };
     }
@@ -239,14 +240,26 @@ export async function buildSite(config) {
         : undefined;
     let exampleBakes;
     if (config.checkExamples !== false) {
-        const { problems, bakes } = await checkExamplesInChild(DOCS_JSON, resolverPrefix);
+        const { problems, warnings, bakes } = await checkExamplesInChild(DOCS_JSON, resolverPrefix);
         exampleBakes = bakes;
+        // Unsupported imports don't fail the build — the code isn't broken, it just
+        // can't run in the doc environment (almost always illustrative code that
+        // should be tagged `typescript`). Warn loudly, treat the block as display-only,
+        // and keep going. Only real syntax/transpile errors below are fatal.
+        if (warnings.length) {
+            console.warn(`⚠️  doc-site build: ${warnings.length} live example block(s) can't run ` +
+                `here and were left as display-only:\n\n` +
+                formatExampleProblems(warnings) +
+                `\n\nTag each with a display-only language like \`typescript\` (instead of` +
+                ` \`js\`/\`ts\`) to silence this, or enable \`importResolver\` to import` +
+                ` other packages.\n`);
+        }
         if (problems.length) {
             throw new Error(`doc-site build: ${problems.length} live example(s) failed to build:\n\n` +
                 formatExampleProblems(problems) +
                 `\n\nFix the code, or — if a block is illustrative and not meant to run —` +
                 ` tag it with a display-only language like \`typescript\` instead of` +
-                ` \`js\`/\`ts\`. (Disable with checkExamples: false.)`);
+                ` \`js\`/\`ts\`. (Disable all checking with checkExamples: false.)`);
         }
     }
     // Copy static-asset dirs into the web root.

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

@@ -88,9 +88,16 @@ export interface SiteConfig {
     domain?: string;
     /**
      * URL prefix the site is served under, default '/'. Set to '/<repo>' for a
-     * GitHub project page without a custom domain; every absolute URL the
-     * generator emits (links, canonical, sitemap, scriptUrl, stylesUrl) is
-     * rewritten under it.
+     * GitHub project page without a custom domain.
+     *
+     * As of the mount-agnostic build (issue #25), `basePath` only affects
+     * *metadata* URLs — `canonical`, `og:url`, `og:image`, and `sitemap.xml` —
+     * which need the real absolute served path for SEO. *Functional* URLs (nav /
+     * content links, `scriptUrl`, `stylesUrl`, favicon, `docsUrl`) are emitted
+     * **relative to each page**, so one build works at `/repo`, at a custom-domain
+     * root, or a moved mount with no rebuild. You still want `basePath` correct so
+     * search engines see canonical URLs at the real path; getting it wrong now only
+     * mis-states metadata, it no longer 404s the page's assets.
      */
     basePath?: string;
     /**

package/dist/form.d.ts

@@ -45,7 +45,6 @@ export declare class TosiField extends XinComponent {
     };
     value: any;
     content: HTMLLabelElement;
-    private valueChanged;
     handleChange: () => void;
     connectedCallback(): void;
     render(): void;