tosijs-ui 1.12.4 → 1.12.5

package/CHANGELOG.md

@@ -1,5 +1,376 @@
 # Changelog
 
+## 1.12.5
+
+### Fixed: 49 controls a screen reader announced as "button" and "edit text"
+
+Lighthouse scored the doc site 91 on accessibility, and the cause was entirely mechanical.
+`<tosi-table>` builds a column-options button that contains only an icon, and an editable cell
+that is an empty `<input>` — neither has any text to derive an accessible name from. On the
+data-table page alone that is 37 unnamed buttons and 12 unnamed fields. The doc-browser's search
+box made it worse in a quieter way: it had a `placeholder` and nothing else, on **every page of
+every site built with `tosijs-ui/site`**. A placeholder is not a label — it is an unreliable
+accessible name and it vanishes the moment anything is typed.
+
+The controls now carry a name: `title` on the column-options button, where the tooltip is a
+genuine win for sighted mouse users too, and `aria-label` on the cells and the search field,
+where a tooltip on every hover would just repeat the column header as noise.
+
+To be precise about what `title` buys, because its two halves land on different people: the
+**accessible name** is real and works — `title` feeds the accessible name computation, so
+VoiceOver on iOS/iPadOS announces these controls, as do NVDA and JAWS. The **visible tooltip** is
+mouse-only, and a screen-reader user was never relying on it.
+
+No visible label is added, deliberately. The vertical-more glyph is the standard overflow
+affordance and reads as one; spelling it out on every column header would be clutter that makes
+the header worse for everyone in order to restate what the icon already says. The defect was that
+the control had no name in the accessibility tree, and that is what is fixed.
+
+Localized tables get this through the existing `data-tosi-localized` directive rather than a
+`<tosi-localized>` child, because an `<input>` cannot contain a child element. Add
+**`Column Options`** to your localized strings; the editable cells reuse the column names you
+already localize, so an editable table wants those present even if you are happy with
+untranslated headers.
+
+The regression test is in `tests/a11y-names.pw.ts`, and its first version **passed with both
+fixes reverted** — it waited for `buttons.length > 2`, which the nav chrome satisfies on its own,
+and then asserted an empty list against a page that had not built the controls yet. `toEqual([])`
+is trivially true when there is nothing to check. Every assertion there now has a positive
+precondition that the things under test exist, and the mutation that removes the fixes fails it
+by name.
+
+Not fixed, and not ours: the two images without `alt` on the 3D page come from Babylon's own
+default loading screen.
+
+### Fixed: on a narrow screen, tapping a nav link left you looking at the nav
+
+A regression from 1.12.3's full-screen work, reported from a phone-width window. The sidebar
+fills the screen, you tap a link, the URL changes — and the nav stays up. The article you asked
+for never appears.
+
+Leaving full-screen had been written as the tidy mirror of entering it: `navVisible = true`. But
+that setter's show-the-nav branch writes `contentVisible = false`, and it ran on **every**
+navigation to a non-full-screen page — immediately after the nav click handler had set
+`contentVisible = true` to do precisely the thing the reader asked for. The layout code was
+overwriting a decision that belongs to the person reading.
+
+The two directions are asymmetric now, and that is the point rather than an oversight: entering
+full-screen states what it needs, and stepping out of it releases only what it claimed
+(`alwaysCompact`). Which pane is showing at a narrow width is not the layout's business.
+
+**Nothing in the test suite could have caught this.** Every layout test ran at 1400px, where
+normal mode shows the nav and the content together and `contentVisible` has no visible effect —
+the bug was invisible at every width the tests used. There are now narrow-viewport tests for
+both directions, and the mutation that restores the old line fails them.
+
+### `<tosi-sidenav>` no longer races a timer to hide its own load-time animation
+
+Its defaults are the compact arrangement — 50/50 columns, margin -100% — so the first layout pass
+moves it to wherever it actually belongs. With a transition live, that move _animates_: the
+sidebar visibly slides into place on load.
+
+The suppression was `setTimeout(…, 250)`, which is a race rather than a rule — it assumes the
+first successful layout pass lands within 250ms of the element upgrading. Measured here it lands
+~70ms after (chromium 236→297ms, webkit 213→291, firefox 229→304), leaving ~175ms spare, which
+is exactly why this never reproduced locally. But `handleResize` returns early while
+`offsetParent` is null, so on a bigger corpus or a slower device the first pass can be deferred
+past the window, and then the animation is visible.
+
+It now releases on the first pass that actually computes something, one frame later so the
+corrected values paint before transitions come back. No duration is correct for every page; a
+rule needs no number.
+
+**This does not eliminate the hydration flash, and it is worth being honest about the limit.** It
+removes one race. What remains is the interval between the element upgrading — at which point its
+shadow defaults apply — and the first layout pass correcting them: ~70ms here, invisible, but a
+real window in which the element is painted wrong rather than not painted. The principled next
+step is for the defaults to _be_ the common case, and it is written up in `TODO.md` rather than
+attempted blind, since the flash does not reproduce on this machine and changing paint defaults
+you cannot observe is how you trade a flash you cannot see for one you can.
+
+### Decided: a nav-toggle override does not survive Back
+
+Left open in 1.12.3 and now settled — **metadata wins on arrival**. A page declaring
+`layout: "full-screen"` is full-screen however you reach it: a link, Back, or a fresh load. The
+override is a transient viewing choice rather than a property of the document, and since the nav
+button is always offered on such a page, restoring it is one tap.
+
+Worth recording that the alternative was real. Browsers restore scroll position on Back, so "put
+the view back how I left it" is an established expectation, not an exotic one. It was rejected
+because the state would have to live in `history.state`, which makes the same URL behave
+differently arrived-at-by-Back than clicked — trading the current surprise for a new one — and
+adds state to a path that has none.
+
+No behaviour change; the tests that pinned it now say it is settled rather than pending.
+
+### The invite screen has a code box, so an installed PWA can let itself back in ([#75](https://github.com/tonioloewald/tosijs-ui/issues/75))
+
+The screen offered only a command to run _on the machine hosting the server_. The devices a
+tunnel exists for have no such keyboard — and an installed PWA has no address bar either, because
+iOS gives a Home Screen app its own cookie jar and its own launch URL. An unauthenticated launch
+was a black rectangle with no way out of it.
+
+It now offers the 7-character code box directly: the same affordance as the `dev.tosijs.net`
+landing page, moved to where it is actually needed. A plain GET form produces `/?t=CODE`, which is
+the path the link already takes, so this needed no new server code. The input disables
+autocapitalize, autocorrect and spellcheck, because the code is case-insensitive and a phone
+keyboard's help is noise; there is a viewport meta, because a code box you cannot hit is not much
+better than none.
+
+**What this deliberately does not attempt** is carrying a session across the install. The
+separate cookie jar is a privacy feature rather than a bug, and the issue's suggested "don't
+redirect" fix would bake a live credential into a home-screen icon — working once, then failing
+forever with no address bar to correct it. Seven characters is the better trade.
+
+### A leading metadata comment is no longer the page title ([#100](https://github.com/tonioloewald/tosijs-ui/issues/100))
+
+The title came from line one, literally. A file opening with its metadata block — the documented
+way to set `order` or `parent` — published under the title `<!--{ "order": 2 }-->`, while `order`
+itself parsed correctly. So the metadata visibly worked and the title visibly did not, which is a
+confusing pair to be handed. Hit while adding `CHANGELOG.md` and `Migration.md` to a doc site,
+which is precisely where a leading metadata comment is most natural.
+
+Leading HTML comments are skipped now, including ones that wrap across lines, and an
+unterminated comment yields no title rather than lifting text out of it — publishing something
+the author had deliberately hidden would be worse than an empty string. One rule, used by both
+call sites that previously had their own copy of the line.
+
+No URLs move: slugs derive from the filename, not the title, so an affected page gets a correct
+title at the address it already had.
+
+**The other half of that issue was already fixed**: `docPaths` entries have been in the dev
+server's watch set since #49, so editing a root `Migration.md` does trigger a rebuild.
+
+### `debugSink` — telemetry back from a page that is not on this machine ([#99](https://github.com/tonioloewald/tosijs-ui/issues/99))
+
+`haltijaDev` is localhost-gated for good reason: an injected drive-my-browser channel reachable
+from the network is RCE-adjacent. But that leaves a page served to a headset or a phone with no
+way to say **anything** — and in a WebXR session there is no console and `requestAnimationFrame`
+is suspended, so every usual readback path is gone at once. The remaining channel is a human
+reading an in-scene panel aloud.
+
+`debugSink: true` accepts `POST /__debug-sink` and appends one line per event to a JSONL file
+whose path it prints at startup, so an agent can `tail -f` it:
+
+```javascript
+navigator.sendBeacon('/__debug-sink', JSON.stringify({ t: Date.now(), tag, ...event }))
+```
+
+`sendBeacon` is the point — it needs no headers, reads no response, and survives the page going
+away.
+
+**Why this is reachable off-loopback when `/__docstore/source` is not.** It appends opaque bytes
+to a scratch file, outside the repo, that the build never reads and nothing serves back. No code
+runs; nothing is reconfigured. The source endpoint is remote code execution by design and stays
+gated. This is a log.
+
+Still **off by default**: an unauthenticated write endpoint on a LAN-reachable server should be a
+decision you made rather than one you inherited. Bounded so a looping page cannot fill a disk —
+bodies over 64 KB refused (413), the file stops at 32 MB (507). Newlines in a payload are
+escaped, because one event must be one line or `tail -f` shows a split event and the reader
+cannot tell.
+
+### The dev cert covers the machine's LAN IP ([#92](https://github.com/tonioloewald/tosijs-ui/issues/92))
+
+Every name the cert carried was useful only _on_ this machine, except `<host>.local` — which is
+precisely the one another device is most likely to fail to resolve. Reported from a Quest:
+`tosi.local` resolved to **IPv6 only**, including a link-local `fe80::…` a headset gets and
+cannot route, while the LAN IP worked. The host never sees it, because it resolves mDNS
+natively, so it fails only on the devices the name was added for.
+
+Private ranges only (10/8, 172.16/12, 192.168/16) — a public address on a dev cert would be a
+name this machine has no business claiming. A DHCP lease change moves the address and the cert
+does not follow; the script says so, and prints the URLs another device can use.
+
+Note this fixes the **name mismatch**, not the untrusted CA: mkcert's root still is not on the
+headset, so you either install it there or use the tunnel, which has a real certificate.
+
+### A dropped session says the server restarted, instead of blaming your cookies ([#114](https://github.com/tonioloewald/tosijs-ui/issues/114))
+
+Sessions live in memory and die with the process. That is the design, not an oversight: a
+credential should not outlive the thing that granted it, and nothing about a session — or the
+token exchanged for it — is ever written to disk. **That has not changed and will not.**
+
+What was wrong is that a cookie from a previous run and a cookie the server had never seen
+produced the _identical_ screen. So a reader whose dev server had restarted was told "invite
+links expire", and reasonably concluded their cookie was expiring — the one explanation the
+evidence ruled out. The reporter's own words: the misleading failure "is the part I would most
+want fixed".
+
+The cookie now carries a per-process boot id (`<bootId>.<token>`), so the next process can tell a
+cookie it _issued_ from one it has never seen. Both are still refused, identically; only the
+sentence differs:
+
+> **The dev server restarted, so your session ended with it.** Sessions are held in memory on
+> purpose — they never outlive the process that issued them, and they are never written to disk.
+> Your browser still holds the cookie; there is simply nothing on this side to match it to.
+
+The prefix is not a credential and admits nobody: a cookie with the right run id and a wrong
+token is refused exactly as before, and there is a test asserting that. An absent or malformed
+cookie is _not_ reported as a restart — claiming one we cannot evidence would be its own lie.
+
+### A bundle that references an unserved sourcemap now says so at build time ([#103](https://github.com/tonioloewald/tosijs-ui/issues/103))
+
+`--sourcemap=linked` appends a `sourceMappingURL` comment, so devtools fetches that file on every
+load. When the map is not in the served root the fetch fails — in exactly the session where
+someone is reading the console carefully for something else. It cost the reporter a wrong
+hypothesis while chasing a slow load.
+
+The uglier half was already fixed by #116 in this same release: the SPA fallback used to answer
+`.map` requests with the **HTML shell**, so devtools received a web page where a JSON map should
+be. Missing assets 404 now.
+
+The remaining half is a build-time warning naming the file and where it was expected. It checks
+what is **served**, not what was built — those differ whenever `bundleOutDir` is set, and the
+copy across is best-effort by design, so trusting the step is what let this ship. It warns rather
+than fails: a map is a debugging convenience and no site should fail to build without one.
+
+The check is a pure, tested function rather than an inline block, because the branch it lives in
+is one **this repo's own build never takes** — our bundle comes from `bin/dev.ts`, not from
+`buildSite`. That is exactly why the bug reached an adopter instead of us.
+
+### `resolveUnder` asserts path containment instead of inheriting it ([#96](https://github.com/tonioloewald/tosijs-ui/issues/96))
+
+Defence in depth: there is no live traversal, and the reporter checked the classes carefully —
+`/../../../etc/passwd`, percent-encoded and double-encoded forms all stay inside the served root
+today. But they stay inside for two reasons the static handler does not own: the WHATWG URL
+parser collapses `../` before `.pathname` is read, and `.pathname` is never the raw request line.
+Both are properties of the **caller**, so a future call with a path from a config value, a
+manifest entry or a header inherits nothing. The asserted version already lived ten lines away
+in the same file.
+
+Now an exported, tested predicate — a test that went through the server would prove nothing,
+since the URL parser makes a violation unreachable from outside.
+
+### `bun run stop` — stop THIS project's dev server, not every one on the machine ([#117](https://github.com/tonioloewald/tosijs-ui/issues/117))
+
+There was no way to stop a dev server, so what everyone reached for was
+`pkill -f 'bun bin/dev.ts'` — which matches **every** dev server on the machine, because every
+project on this pipeline runs an identical command line. A sibling checkout, a worktree or
+another agent's session died to a command that reads as "restart mine". Observed five times in
+one working day, twice while a tunnel link was in use by a remote reviewer.
+
+The record needed for this already existed: the build lock stores `pid`, `port` and `root`,
+per-project, with staleness decided by liveness rather than age. It needed a reader and a
+command. `bun run stop` (or `bun bin/dev.ts --stop`) signals that pid and nothing else, and says
+plainly when nothing is running.
+
+### The dev server can no longer die silently ([#91](https://github.com/tonioloewald/tosijs-ui/issues/91))
+
+Reported after a ~9.4h run: `pgrep` said running, `curl` got nothing, the last log line was a
+**successful** build, and there was no error, signal or exit anywhere. Every diagnostic a person
+would reach for answered "fine"; it was found the next day because a human said the site was
+down.
+
+Worth correcting the report's own diagnosis, because it does not survive the evidence: the idle
+path **announces itself** before exiting, and no such line was logged — so the idle timeout is
+not what stopped that listener. What did is still unknown, which is exactly why the fix targets
+the symptom rather than a cause.
+
+The health tick now probes the server's own listener (`GET /__alive`, a bare 204 that
+deliberately does **not** count as activity — a self-check that did would hold the idle timer
+open forever). Two consecutive failures and it exits non-zero with an explanation. A process that
+cannot serve has no value, and the one useful thing left to it is to stop claiming to be alive.
+
+### `tosijs-tunnel --link` stops printing links that cannot work ([#94](https://github.com/tonioloewald/tosijs-ui/issues/94))
+
+`--link` asks the dev server for a token, which succeeds whether or not a tunnel exists. The URL
+is well-formed and the token is real — it just answers 503, because nothing is listening
+upstream. Printed with exit 0 and no comment, that is indistinguishable from the far side being
+down.
+
+It still prints the link, since you may be about to start the tunnel, but it now says so and
+exits non-zero, so a script treating 0 as "a usable link was produced" is telling the truth.
+
+### Doc tests survive a context key with a slash in it ([#111](https://github.com/tonioloewald/tosijs-ui/issues/111), [#112](https://github.com/tonioloewald/tosijs-ui/issues/112), [#109](https://github.com/tonioloewald/tosijs-ui/issues/109))
+
+Context keys become **function parameter names** — the runner builds each block as
+`new Fn(...contextKeys, body)`. `test-harness.ts` carried its own copy of the rule that turns a
+key into an identifier, `key.replace(/-/g, '')`, which strips hyphens and leaves slashes and
+`@`. So an ordinary specifier like `'tosijs-3d/demo-utils'` became the parameter name
+`tosijs3d/demoutils`, and **every test in that file died before one of them ran** with V8's
+`Arg string terminates parameters early`. The examples on the same page rendered fine, because
+they went through the shared sanitiser — so nothing looked wrong except a red badge.
+
+One implementation now, in `code-transform.ts`, used by all five call sites. It also handles
+what the shared version had never needed to: a leading digit (`'3d-tools'`), a reserved word
+(`'class'`), and a key that reduces to nothing.
+
+**Two keys that reduce to the same identifier now throw, by name.** Quietly suffixing the second
+would leave one module bound to a name no rewritten import references — undefined at runtime with
+nothing to read. The message says which two keys and what to do:
+
+```
+example context keys "tosijs-3d" and "tosijs/3d" both reduce to the identifier "tosijs3d",
+so an import from one of them could not be told from the other. Rename one of the context keys.
+```
+
+There is also a structural test asserting **nothing outside `code-transform.ts` sanitises a
+context key**. That is the one that would have caught this: every unit test of the shared helper
+passes with the divergent copy restored, because they exercise the helper rather than the call
+site — which is exactly how the bug survived.
+
+### A missing asset 404s instead of impersonating a page ([#116](https://github.com/tonioloewald/tosijs-ui/issues/116))
+
+The dev server fell back to the SPA shell for **any** unknown path, so a missing
+`waterbump.png` answered `200 text/html`. Babylon's `Texture` fetched it, failed to decode a web
+page as an image, and substituted its checkerboard — a missing asset presented as a _styling
+choice_, and was complimented before it was diagnosed.
+
+Unknown **routes** still get the shell, because client-side routing depends on it. The
+distinguishing signal is a dot in the last path segment: an extension was asked for, so a file
+was meant. `/v1.2/guide` is still a route; `/thing.png` is not. The 404 names the path, because
+a bare "File not found" sends people to the wrong layer — the reporter went through their
+texture pipeline before suspecting the server.
+
+### `staticDirs` are watched, so a replaced asset is not served stale ([#110](https://github.com/tonioloewald/tosijs-ui/issues/110))
+
+`buildSite` copies `staticDirs` into the output on every build, but nothing watched them — so
+re-exporting a GLB over `static/model.glb` left the previous copy served indefinitely, with no
+error and no hint. Both files exist and only their contents differ, which is the hardest version
+of stale to see, and the workaround people find is touching a source file to provoke a rebuild.
+
+Same shape as #49, where `docPaths` was the omission. Verified end to end: a replaced static file
+is now picked up in about half a second.
+
+### A lone custom element is no longer wrapped in a paragraph ([#115](https://github.com/tonioloewald/tosijs-ui/issues/115))
+
+Reported by tosijs-3d: a doc page whose entire content is one custom element — the case
+`layout: "full-screen"` exists for — got an element that would not fill. marked classifies raw
+HTML by tag name and cannot know whether an unknown tag is block or inline, so
+`<my-editor></my-editor>` alone on a line came out as `<p><my-editor></my-editor></p>`. That
+paragraph is auto-height, so `height: 100%` resolved against a **33px** box inside an 842px
+content area.
+
+Measured before and after on the same page: 33px, then **842 of 842** on all three engines. The
+comment promising "a definite height, so a child asking for `height: 100%` gets one" is finally
+true rather than aspirational.
+
+The unwrap is deliberately narrow, since a heuristic here earns its own bugs: it fires only when
+a paragraph's entire content is a single element whose tag name contains a hyphen — a custom
+element, the one case marked provably cannot classify. `<p><img></p>`, `<p><em>text</em></p>`
+and `<p>see <my-thing></my-thing> here</p>` are all left exactly as they are, and mutation
+testing covers both directions — unwrapping everything fails three tests, unwrapping nothing
+fails one.
+
+### The inline doc tier runs at two widths now
+
+The same gap, one level down: the doc-test runner's iframe was hardcoded to 800x600, so **every
+inline `test` block had only ever run wide**. Its size is now overridable, and the Playwright
+doc-test spec runs the whole tier a second time at 390x844.
+
+An iframe is a real viewport, so this is not a simulation — verified that
+`matchMedia('(max-width: 600px)')` matches inside a 390px frame and not a 1200px one, and that
+the override reaches the runner (390px frame, 386 inner; 800/796 without it).
+
+**Widths only, deliberately.** Touch cannot be emulated from inside a page: an iframe inherits
+the host's input characteristics, so `(pointer: coarse)` stays false and `maxTouchPoints` stays 0
+however small the frame is. `navigator.maxTouchPoints` _can_ be redefined, and doing so would be
+worse than skipping it — the property would lie while the media queries told the truth, so a test
+could pass against a page behaving as desktop. Touch belongs to a Playwright context
+(`hasTouch`, `devices[…]`); noted in `TODO.md` as worth its own spec, since everything
+touch-shaped here is currently tested only with a mouse.
+
 ## 1.12.4
 
 ### `.tjs` source files are documented again ([#108](https://github.com/tonioloewald/tosijs-ui/issues/108))

package/bin/tunnel.ts

@@ -191,6 +191,32 @@ if (has('link')) {
     `\n🔗 Edit link:\n   ${url}\n` +
       (code ? `\n   code:  ${code}   (case-insensitive)\n` : '')
   )
+
+  /*
+  A link nobody can reach is worse than no link.
+
+  `--link` asks the dev server for a token, which succeeds whether or not a tunnel exists — the
+  URL is well-formed and the token is real, it just resolves to a 503 from the reverse proxy
+  because nothing is listening upstream. Printed with exit 0 and no comment, that is
+  indistinguishable from the far side being down, and the reporter lost a chunk of an afternoon
+  to the difference (#94).
+
+  Checked AFTER printing, deliberately: the link is still the thing you asked for, and you may
+  be about to start the tunnel. What changes is that the output says so and the exit code agrees
+  — a script that treats 0 as "a usable link was produced" is now telling the truth.
+
+  `running()` is the same predicate `--status` uses, matching this project's own forward by its
+  exact ports and host rather than by an argv substring.
+  */
+  const forwards = await running()
+  if (forwards.length === 0) {
+    console.error(
+      `⚠️  No tunnel is running, so that link will answer 503.\n` +
+        `    The token is real — nothing is listening on the far side yet.\n` +
+        `    Start one with \`tosijs-tunnel\` (or \`bun run tunnel\`), then use the link.\n`
+    )
+    process.exit(1)
+  }
   process.exit(0)
 }
 

package/dist/data-table.d.ts

@@ -341,6 +341,7 @@ export declare class TosiTable extends WebComponent {
     sortByColumn: (columnOptions: ColumnOptions, direction?: "ascending" | "descending" | "auto") => void;
     popColumnMenu: (target: HTMLElement, options: ColumnOptions) => void;
     get captionSpan(): ElementCreator;
+    labelAttrs(key: string, attr?: string): Record<string, string>;
     get visibleRows(): any[];
     get visibleSelectedRows(): any[];
     get selectedRows(): any[];

package/dist/data-table.js

@@ -343,6 +343,7 @@ const table = tosiTable({
         return button(
           {
             class: 'td actions-btn',
+            title: 'Row actions',
             onClick(e) { e.stopPropagation() },
             onMouseup(e) { e.stopPropagation() },
           },
@@ -979,8 +980,11 @@ You'll need to make sure your localized strings include:
 - Unpin
 - Left
 - Right
+- Column Options
 
-As well as any column names you want localized.
+As well as any column names you want localized — these are also used as the accessible name
+(`aria-label`) of each editable cell, so an editable table wants them present even if you are
+happy with the untranslated headers.
 */
 /*{ "parent": "Components" }*/
 import { Component as WebComponent, elements, vars, varDefault, tosiValue, getListItem, getListBinding, tosi, } from 'tosijs';
@@ -1875,6 +1879,7 @@ export class TosiTable extends WebComponent {
             role: 'gridcell',
             tabindex: -1,
             ariaColindex: String(colIndex + 1),
+            ...this.labelAttrs(typeof col.name === 'string' ? col.name : col.prop || '', 'aria-label'),
             style,
             onMouseup: stop,
             onTouchend: stop,
@@ -2051,6 +2056,7 @@ export class TosiTable extends WebComponent {
         const menuButton = !(this.nosort && this.nohide)
             ? button({
                 class: 'menu-trigger',
+                ...this.labelAttrs('Column Options'),
                 onClick(event) {
                     popColumnMenu(event.target, col);
                     event.stopPropagation();
@@ -2854,6 +2860,40 @@ export class TosiTable extends WebComponent {
     get captionSpan() {
         return this.localized ? tosiLocalized : span;
     }
+    /*
+    An accessible NAME for a control whose visible content carries none: the column menu is an
+    icon alone, and an editable cell is an empty input. A screen reader announced them as bare
+    "button" and "edit text" — 49 of them on the data-table doc page.
+  
+    `title` for the menu button rather than `aria-label`, because title counts toward the
+    accessible name AND shows a tooltip, so it serves sighted mouse users too. The cells get
+    `aria-label` instead: a tooltip on every cell hover, repeating the column name the header
+    already displays, is noise.
+  
+    The two halves of `title` reach different people. The accessible NAME works — it is part of
+    the accessible name computation, so VoiceOver on iOS/iPadOS announces it, as do NVDA and
+    JAWS. The VISIBLE tooltip is mouse-only, and a screen-reader user was never relying on it.
+  
+    No visible label, by design: the vertical-more glyph is the standard overflow affordance and
+    is read as one, so labelling it on every column header would be clutter that restates what
+    the icon already says. The defect being fixed is an empty accessibility tree, not an unclear
+    UI.
+  
+    The `data-tosi-localized` directive, rather than a `<tosi-localized>` child, because it
+    re-applies on locale change and needs no child element — an `<input>` cannot contain one.
+    It is filtered to mutations of the data attribute itself, so writing the target attribute
+    here does not re-enter the observer.
+    */
+    labelAttrs(key, attr = 'title') {
+        if (!key)
+            return {};
+        return this.localized
+            ? {
+                [attr]: localize(key),
+                'data-tosi-localized': JSON.stringify({ [attr]: key }),
+            }
+            : { [attr]: key };
+    }
     get visibleRows() {
         return tosiValue(this.rowData.visible);
     }

package/dist/doc-browser.js

@@ -547,6 +547,11 @@ export function createDocBrowser(options) {
     const searchField = input({
         slot: 'nav',
         placeholder: 'search',
+        // A placeholder is not a label: it is not a reliable accessible name, and it
+        // disappears the moment anything is typed. This is the only text input in the
+        // doc-browser chrome, so it was the one unnamed field on every page of every
+        // site built with `tosijs-ui/site`.
+        'aria-label': 'Search documentation',
         type: 'search',
         style: {
             width: 'calc(100% - 10px)',
@@ -625,9 +630,28 @@ export function createDocBrowser(options) {
             return;
         if (appliedFullScreen === wantsFullScreen)
             return;
-        // The same one control the nav button uses — the layout is just asking for the nav to be
-        // away, and the sidenav decides how that is achieved.
-        sidenav.navVisible = !wantsFullScreen;
+        /*
+        ASYMMETRIC on purpose, and the symmetric version was a real regression.
+    
+        Entering full-screen asks for the nav to be away, and `navVisible` is the right control:
+        the sidenav decides how that is achieved at the current width.
+    
+        LEAVING it must only undo `alwaysCompact`. Writing `navVisible = true` looks like the tidy
+        mirror image, and it clobbers `contentVisible` — which on a narrow screen is owned by the
+        person reading. Tapping a nav link there is supposed to switch you to the content; the nav
+        click handler sets `contentVisible = true` to do exactly that, and this ran afterwards on
+        the same navigation and set it straight back to false. The nav stayed up and the article
+        never appeared: reported as "touching a link in the sidebar doesn't switch to content
+        anymore", and correctly blamed on the full-screen work.
+    
+        So: full-screen states what it needs, and stepping out of it states only what it is
+        releasing. Whether the nav or the content is showing at a narrow width is not this code's
+        business.
+        */
+        if (wantsFullScreen)
+            sidenav.navVisible = false;
+        else
+            sidenav.alwaysCompact = false;
         appliedFullScreen = wantsFullScreen;
         refreshNavToggle();
     };
@@ -1681,14 +1705,30 @@ export function createDocBrowser(options) {
             return;
         }
         const currentFilename = String(app.currentDoc.filename);
-        // Create a hidden iframe that loads the full page. Keep its real 800x600
-        // layout size (layout-dependent example tests need it) but park it
-        // off-screen rather than rely on opacity:0 over the visible page — Chromium
-        // (and haltija on top of it) still composites a 0-opacity layer at 0,0,
-        // which flashes as the frame navigates page to page.
+        /*
+        Create a hidden iframe that loads the full page. Keep a real layout size — layout-dependent
+        example tests need one — but park it off-screen rather than rely on opacity:0 over the
+        visible page: Chromium (and haltija on top of it) still composites a 0-opacity layer at 0,0,
+        which flashes as the frame navigates page to page.
+    
+        THE SIZE IS OVERRIDABLE, because 800x600 was the only width the inline tier had ever run at.
+        A doc-system layout regression at phone width shipped in 1.12.3 and was found by a reader,
+        not by the suite: every test ran wide, where the two panes show together and the bug is
+        invisible. An iframe is a real viewport — `matchMedia` and element sizing answer to its
+        dimensions, verified — so re-running the tier narrow costs nothing but the size.
+    
+        Only dimensions, deliberately. Touch cannot be faked from inside a page: an iframe inherits
+        the host's input characteristics, so `(pointer: coarse)` stays false and `maxTouchPoints`
+        stays 0 however small the frame is. `navigator.maxTouchPoints` can be redefined, and doing so
+        would be worse than useless — it lies to code that reads the property while the media queries
+        still say fine-pointer, so tests would pass on a page behaving as desktop. Touch emulation
+        belongs to the Playwright lane, which can set it per context.
+        */
+        const vp = globalThis.__tosiTestViewport;
+        const vpWidth = Number(vp?.width) > 0 ? Number(vp?.width) : 800;
+        const vpHeight = Number(vp?.height) > 0 ? Number(vp?.height) : 600;
         const testFrame = document.createElement('iframe');
-        testFrame.style.cssText =
-            'position: fixed; left: -10000px; top: 0; width: 800px; height: 600px; opacity: 0; pointer-events: none;';
+        testFrame.style.cssText = `position: fixed; left: -10000px; top: 0; width: ${vpWidth}px; height: ${vpHeight}px; opacity: 0; pointer-events: none;`;
         document.body.appendChild(testFrame);
         // Listen for test results posted from the iframe
         const messageHandler = (event) => {

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

@@ -3,7 +3,7 @@ export interface ExampleBake {
     js: string;
 }
 export type ExampleBakes = Map<string, ExampleBake>;
-/** Render a doc's markdown text to HTML (synchronous, default marked options). */
+export declare function unwrapLoneCustomElements(html: string): string;
 export declare function renderDocMarkdown(text: string, opts?: {
     bakes?: ExampleBakes;
 }): string;

package/dist/doc-system/render.js

@@ -154,10 +154,37 @@ docMarked.use({
     ],
 });
 /** Render a doc's markdown text to HTML (synchronous, default marked options). */
+/*
+Markdown wraps a lone CUSTOM ELEMENT in a paragraph, and that paragraph is the bug.
+
+marked classifies raw HTML by tag name, and it cannot know whether an unknown tag is block or
+inline — so `<my-thing></my-thing>` alone on a line comes out as `<p><my-thing></my-thing></p>`.
+The paragraph is auto-height, so a page whose whole content is one embedded app gets an element
+whose `height: 100%` resolves against a 33px box (tosijs-ui#115, measured: `p` 33px inside a
+842px `.doc-content`). `layout: "full-screen"` exists precisely for that page, and the promise it
+makes was not being kept.
+
+The unwrap is deliberately NARROW, because a heuristic here earns its own bugs. It fires only
+when a paragraph's entire content is a single element whose tag name contains a hyphen — i.e. a
+custom element, the one case marked provably cannot classify. `<p><img></p>` and
+`<p><em>text</em></p>` are left exactly alone: those are real paragraphs, and a `<p>` around them
+is what the author asked for.
+*/
+const LONE_CUSTOM_ELEMENT = /<p>\s*(<([a-z][a-z0-9]*-[a-z0-9-]*)\b[\s\S]*?<\/\2>)\s*<\/p>/gi;
+export function unwrapLoneCustomElements(html) {
+    return html.replace(LONE_CUSTOM_ELEMENT, (whole, inner) => {
+        /*
+        Only when the element is the paragraph's WHOLE content. The regex already anchors both ends,
+        but a nested same-tag structure could let the lazy match close early and leave a tail — so
+        the result is checked for a stray closing tag rather than trusted.
+        */
+        return inner.includes('</p>') ? whole : inner;
+    });
+}
 export function renderDocMarkdown(text, opts = {}) {
     currentBakes = opts.bakes;
     try {
-        return docMarked.parse(text);
+        return unwrapLoneCustomElements(docMarked.parse(text));
     }
     finally {
         currentBakes = undefined;

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

@@ -31,6 +31,22 @@ export declare function lockDecision(existing: LockHolder | null, self: {
 /** The message the refused build prints. Names the holder, and what to do about it. */
 export declare function describeHolder(holder: LockHolder): string;
 export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Who, if anyone, holds this project's lock right now — or `null` if nobody live does.
+ *
+ * Exported so a `--stop` can target THIS project's dev server by pid instead of by argv
+ * pattern. `pkill -f 'bun bin/site.ts'` matches every dev server on the machine, because every
+ * project on this pipeline runs an identical command line — so a sibling checkout, a worktree
+ * or another agent's session dies to a command that reads as "restart mine" (tosijs-ui#117).
+ * Observed five times in one working day, twice while a tunnel link was in use by a remote
+ * reviewer.
+ *
+ * The record already existed for the build lock; only a reader and a command were missing.
+ */
+export declare function currentHolder(root?: string, opts?: {
+    dir?: string;
+    isAlive?: (pid: number) => boolean;
+}): LockHolder | null;
 export interface AcquiredLock {
     ok: boolean;
     holder?: LockHolder;