@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/libexec/tokens.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""The Lanes design tokens: ONE table, rendered seven ways. The sidebar imports `sgr_table`; `--kdl`, `--css`, `--sh`,
+`--md`, `--js` and `--ghostty-dark|--ghostty-light` write the Zellij theme, the phone CSS, the viewer's shell variables,
+the docs table, the phone's terminal palette and the optional Ghostty palette files between markers; `--check` fails
+when any committed block differs. Spec: docs/superpowers/specs/2026-10-03-lanes-cockpit-design.md.
+No third-party code; importable with no side effects."""
+import difflib
+import os
+import sys
+from pathlib import Path
+
+ROLES = ('surface', 'surface-raised', 'line', 'accent-wash', 'accent-line', 'press', 'chip',
+         'ink', 'ink-dim', 'ink-faint', 'accent', 'on-accent', 'on-accent-urgent',
+         'tone-urgent', 'tone-attention', 'tone-working', 'tone-done', 'scrim', 'shadow')
+TOKENS = {
+    'dark': {'surface': '#101318', 'surface-raised': '#191e25', 'line': '#2c333d', 'accent-wash': '#1a2721',
+             'accent-line': '#4b6955', 'press': '#26332c', 'chip': '#ffffff0f', 'ink': '#edf1f5', 'ink-dim': '#9ca7b5',
+             'ink-faint': '#6b7683', 'accent': '#b4e3bf', 'on-accent': '#101318', 'on-accent-urgent': '#7a1a12',
+             'tone-urgent': '#f28b7d', 'tone-attention': '#e5b84a', 'tone-working': '#7fb3f2', 'tone-done': '#6fd39a',
+             'scrim': '#000000a6', 'shadow': '0 -16px 80px #0007'},
+    'light': {'surface': '#f3f5f2', 'surface-raised': '#ffffff', 'line': '#d5ded6', 'accent-wash': '#e5f0e6',
+              'accent-line': '#acc9b4', 'press': '#d8e9db', 'chip': '#edf3ec', 'ink': '#17241b', 'ink-dim': '#56616d',
+              'ink-faint': '#7f8a96', 'accent': '#2f6b45', 'on-accent': '#ffffff', 'on-accent-urgent': '#ffd3cc',
+              'tone-urgent': '#b7322a', 'tone-attention': '#8a5a00', 'tone-working': '#2456a8', 'tone-done': '#1b7142',
+              'scrim': '#1a222b80', 'shadow': '0 -16px 80px #0003'},
+}
+# 16-colour fallback: the user's own palette resolves these. Selection is achromatic (bold) there, dim is bright-black.
+ANSI16 = {'ink': '39', 'ink-dim': '90', 'ink-faint': '90', 'accent': '1;39',
+          'tone-urgent': '31', 'tone-attention': '33', 'tone-working': '34', 'tone-done': '32'}
+# Lane-identity palette for the two places that DEFINE a palette: Zellij's `web_client { theme {} }` (the phone's
+# xterm.js; dark only, see _web_client) and the optional Ghostty file. A Zellij theme's legacy `black…white` keys are
+# NOT one of them (DEF-1413). The TUI itself keeps 38;5;N. Slots 1-4 are the four tones. Every slot >= 4.5:1.
+PALETTE16 = {
+    'dark': ['#7d8896', '#f28b7d', '#6fd39a', '#e5b84a', '#7fb3f2', '#c9a6ff', '#6fd6d0', '#9ca7b5',
+             '#8a95a3', '#ff9d96', '#8fe0a3', '#f7cf7f', '#a5cbff', '#dcc6ff', '#9ae6e0', '#edf1f5'],
+    'light': ['#3b4a42', '#b7322a', '#1b7142', '#8a5a00', '#2456a8', '#7a3fb8', '#0f7b7b', '#56616d',
+              '#5f6d66', '#c2332a', '#1b7a38', '#8f5a00', '#2860c4', '#8a4dc8', '#0f7272', '#17241b'],
+}
+# key -> (unicode, ascii twin, tone). Position disambiguates: agent glyphs in column 2, stream glyphs in column 33.
+AGENT_GLYPHS = {'needs_approval': ('◆', '!', 'tone-urgent'), 'needs_input': ('◇', '?', 'tone-attention'),
+                'working': ('▸', '>', 'tone-working'), 'done': ('✓', 'v', 'tone-done'),
+                'errored': ('✗', 'X', 'tone-urgent'), 'shell': ('_', '_', 'ink-dim'), 'idle': ('·', '.', 'ink-dim')}
+GLYPHS = {'active': ('●', '*', 'tone-done'), 'quiet': ('○', 'o', 'ink-dim'), 'missing': ('✗', 'x', 'tone-urgent'),
+          'absent': ('–', '-', 'ink-dim'), 'dead': ('!', '!', 'tone-urgent'), 'helper': ('·', '.', 'ink-dim'),
+          'unknown': ('?', '?', 'ink-dim')}
+MARKS = {'cursor': ('▌', '|', 'accent'), 'viewing': ('›', '=', 'accent'), 'viewport-b': ('²', '2', 'accent'),
+         'viewport-c': ('³', '3', 'accent'), 'viewer': ('·', '.', 'ink-dim'), 'truncation': ('…', '~', 'ink'),
+         'close': ('×', 'x', 'tone-urgent'), 'new': ('+', '+', 'tone-done'), 'rule': ('─', '-', 'ink-faint'),
+         'more': ('⋮', ':', 'ink-dim'), 'warning': ('⚠', '!', 'tone-attention'), 'upload': ('↑', '^', 'ink-dim'),
+         'armed': ('↓', 'v', 'tone-done'), 'enter': ('⏎', 'Enter', 'ink-dim'), 'caret': ('█', '_', 'tone-working'),
+         'stale': ('?', '?', 'ink-dim'), 'lead': ('›', '>', 'ink'),
+         # Tone-less punctuation (spec §3 completeness rule): every ` · ` and every quote the sidebar draws is a lookup, so
+         # LANES_GLYPHS=ascii yields a seven-bit frame. `sep` shares `-` with `rule` on purpose: neither carries state.
+         'sep': ('·', '-', 'ink-dim'), 'quote-open': ('‘', "'", 'ink'), 'quote-close': ('’', "'", 'ink'),
+         'ok': ('✓', 'OK', 'tone-done'), 'fail': ('✗', 'X', 'tone-urgent')}
+ECONOMY_TAIL = {'starving': ('⚠', '!', 'tone-attention'), 'downgraded': ('↓', 'v', 'tone-attention'), 'paid': ('$', '$', 'ink-dim')}
+MOBILE_AGENT_LABELS = {'needs_approval': 'Needs approval', 'needs_input': 'Needs you', 'working': 'Working',
+                       'done': 'Done', 'errored': 'Error', 'shell': 'Shell', 'idle': 'Idle'}
+PAINTED = tuple(ANSI16)   # the roles the TUI ever emits
+
+
+def luminance(hexval):
+    r, g, b = (int(hexval[i:i + 2], 16) / 255 for i in (1, 3, 5))
+    lin = [c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4 for c in (r, g, b)]
+    return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]
+
+
+def contrast(fg, bg):
+    hi, lo = sorted((luminance(fg), luminance(bg)), reverse=True)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+def rgb(hexval):
+    return tuple(int(hexval[i:i + 2], 16) for i in (1, 3, 5))
+
+
+def sgr_table(mode, variant):
+    """Complete escape per painted role. `mode` truecolor|16|none; `variant` dark|light. Resolved ONCE per process."""
+    table = {'bold': '\033[1m', 'reset': '\033[0m'}
+    dim16 = '\033[2m' if os.environ.get('LANES_DIM') == '2' else '\033[90m'
+    for role in PAINTED:
+        if mode == 'none':
+            table[role] = '\033[1m' if role == 'accent' else ''
+        elif mode == '16':
+            table[role] = dim16 if role in ('ink-dim', 'ink-faint') else f'\033[{ANSI16[role]}m'
+        else:
+            table[role] = ('\033[1m' if role == 'accent' else '') + '\033[38;2;%d;%d;%dm' % rgb(TOKENS[variant][role])
+    return table
+
+
+def glyph_set(mode):
+    """mode unicode|ascii|emoji -> {table name: {key: glyph}}; emoji differs from unicode only in the icon column."""
+    index = 1 if mode == 'ascii' else 0
+    return {name: {k: v[index] for k, v in table.items()}
+            for name, table in (('agent', AGENT_GLYPHS), ('stream', GLYPHS), ('marks', MARKS), ('economy', ECONOMY_TAIL))}
+
+
+def tone_of(table, key):
+    return table[key][2]
+
+
+# ------------------------------------------------------------------ renderers
+COMPONENTS = ('text_unselected', 'text_selected', 'ribbon_selected', 'ribbon_unselected', 'table_title', 'table_cell_selected',
+              'table_cell_unselected', 'list_selected', 'list_unselected', 'frame_selected', 'frame_highlight',
+              'exit_code_success', 'exit_code_error')
+
+
+def _component(t, base, background, emphasis):
+    e = emphasis
+    return f'base "{t[base]}"; background "{t[background]}"; emphasis_0 "{t[e[0]]}"; emphasis_1 "{t[e[1]]}"; emphasis_2 "{t[e[2]]}"; emphasis_3 "{t[e[3]]}";'
+
+
+def _theme(name, variant):
+    t, p = TOKENS[variant], PALETTE16[variant]
+    text = ('tone-attention', 'tone-done', 'accent', 'tone-working')
+    comps = {
+        'text_unselected': ('ink', 'surface', text), 'text_selected': ('ink', 'accent-wash', text),
+        'ribbon_selected': ('on-accent', 'accent', ('on-accent-urgent', 'on-accent', 'on-accent', 'on-accent')),
+        'ribbon_unselected': ('ink-dim', 'surface-raised', ('tone-urgent', 'ink', 'tone-attention', 'tone-working')),
+        'table_title': ('accent', 'surface', text), 'table_cell_selected': ('ink', 'accent-wash', text),
+        'table_cell_unselected': ('ink', 'surface', text), 'list_selected': ('ink', 'accent-wash', text),
+        'list_unselected': ('ink', 'surface', text),
+        'frame_selected': ('accent', 'surface', ('tone-attention', 'tone-done', 'tone-working', 'tone-urgent')),
+        'frame_highlight': ('tone-attention', 'surface', ('tone-urgent', 'tone-done', 'accent', 'tone-working')),
+        'exit_code_success': ('tone-done', 'surface', ('tone-done',) * 4),
+        'exit_code_error': ('tone-urgent', 'surface', ('tone-urgent',) * 4),
+    }
+    lines = [f'    {name} {{']
+    for comp in COMPONENTS:
+        base, background, emphasis = comps[comp]
+        lines.append(f'        {comp} {{ {_component(t, base, background, emphasis)} }}')
+    players = [t['tone-working'], t['tone-attention'], t['tone-done'], t['tone-urgent'], t['accent'], p[5], p[6], p[11], p[10], p[9]]
+    lines.append('        multiplayer_user_colors { ' + ' '.join(f'player_{i + 1} "{c}";' for i, c in enumerate(players)) + ' }')
+    # No legacy `fg bg black … orange` line: in a component-format theme Zellij 0.45.1 neither reads nor validates
+    # those keys, and none of a theme's colours reach the browser's xterm.js palette (DEF-1413; _web_client does).
+    lines.append('    }')
+    return lines
+
+
+ANSI_NAMES = ('black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white')
+
+
+def _web_client():
+    """The phone's terminal palette. Zellij 0.45.1 sends `web_client.theme` to every browser as `SetConfig.theme`,
+    which the web client assigns to xterm.js `options.theme` (zellij-client `control_message.rs` / `app.js`
+    `terminalConfigOptions`). Without this block only background, foreground and selection fall back to a theme's
+    components and the sixteen ANSI slots stay xterm.js's built-in defaults. The block is server-wide and holds ONE
+    palette: the dark variant, the phone's default. It reaches the browser in the HTTP boot config at connect (the
+    xterm.js `Terminal` constructor) and in a `SetConfig` on every config-file reload, which the client assigns
+    wholesale before repainting `<body>`/`#terminal` inline, so the phone's light toggle needs a client-side
+    `term.options.theme` override applied on attach and re-applied after each `SetConfig`, plus a CSS background rule,
+    not set once (spec §6.3, Task 28; DEF-1413). Zellij validates every colour here (an unparseable one fails
+    `setup --check`), so `test_tokens` can prove the block is read."""
+    t, p = TOKENS['dark'], PALETTE16['dark']
+    lines = ['web_client {', '    font "monospace"', '    theme {',
+             f'        background "{t["surface"]}"', f'        foreground "{t["ink"]}"']
+    lines += [f'        {n} "{p[i]}"' for i, n in enumerate(ANSI_NAMES)]
+    lines += [f'        bright_{n} "{p[i + 8]}"' for i, n in enumerate(ANSI_NAMES)]
+    lines += [f'        selection_background "{t["accent-wash"]}"', f'        selection_foreground "{t["ink"]}"']
+    lines += ['    }', '}']
+    return lines
+
+
+def render_kdl():
+    lines = ['// BEGIN lanes tokens (generated by libexec/tokens.py --kdl; do not edit by hand)', 'themes {']
+    lines += _theme('lanes-dark', 'dark') + _theme('lanes-light', 'light')
+    lines += ['}', 'theme_dark "lanes-dark"', 'theme_light "lanes-light"']
+    lines += _web_client() + ['// END lanes tokens']
+    return '\n'.join(lines) + '\n'
+
+
+ALIASES = {'bg': 'surface', 'panel': 'surface-raised', 'border': 'line', 'text': 'ink', 'muted': 'ink-dim',
+           'current': 'accent-wash', 'current-border': 'accent-line'}
+ZJ = {'bg': 'surface', 'surface': 'surface-raised', 'border': 'line', 'text': 'ink', 'text-dim': 'ink-dim',
+      'green': 'tone-done', 'blue': 'tone-working', 'red': 'tone-urgent', 'yellow': 'tone-attention'}
+
+
+def render_css():
+    """Values per variant; every `var()` indirection (legacy aliases, upstream `--zj-*`) ONCE. All three selectors
+    match the same <html> element and a custom property's var() resolves against that element's winning value, so a
+    single alias follows the light override exactly like a per-variant copy did — 289 B less of the phone's mobile.css
+    growth allowance (spec §8; DEF-1414)."""
+    out = ['/* BEGIN lanes tokens (generated by libexec/tokens.py --css; do not edit by hand) */']
+    for selector, variant, scheme in (('html.lanes-mobile', 'dark', 'dark'), ('html.lanes-mobile:root[data-zj-theme="light"]', 'light', 'light')):
+        out.append(selector + ' {')
+        out += [f'  --lanes-{role}: {TOKENS[variant][role]};' for role in ROLES]
+        out.append(f'  color-scheme: {scheme};')
+        out.append('}')
+    out.append('html.lanes-mobile:root {')
+    out += [f'  --lanes-{old}: var(--lanes-{new});' for old, new in ALIASES.items()]
+    out += [f'  --zj-{k}: var(--lanes-{v});' for k, v in ZJ.items()]
+    out.append('}')
+    out.append('/* END lanes tokens */')
+    return '\n'.join(out) + '\n'
+
+
+def render_sh():
+    return ('# BEGIN lanes tokens (generated by libexec/tokens.py --sh; do not edit by hand)\n'
+            "LZ_BOLD='\\033[1m'\nLZ_DIM='\\033[90m'\n"
+            f"LZ_URGENT='\\033[{ANSI16['tone-urgent']}m'\nLZ_ATTENTION='\\033[{ANSI16['tone-attention']}m'\n"
+            f"LZ_WORKING='\\033[{ANSI16['tone-working']}m'\nLZ_DONE='\\033[{ANSI16['tone-done']}m'\nLZ_RESET='\\033[0m'\n"
+            '# END lanes tokens\n')
+
+
+def render_md():
+    rows = ['<!-- BEGIN lanes tokens (generated by libexec/tokens.py --md; do not edit by hand) -->',
+            '| Role | Dark | Light | ANSI-16 | CSS variable |', '|---|---|---|---|---|']
+    rows += [f'| {r} | `{TOKENS["dark"][r]}` | `{TOKENS["light"][r]}` | `{ANSI16.get(r, "—")}` | `--lanes-{r}` |' for r in ROLES]
+    rows += ['', '| Glyph | Codepoint | ASCII | Tone | Meaning |', '|---|---|---|---|---|']
+    for name, table in (('agent', AGENT_GLYPHS), ('stream', GLYPHS), ('mark', MARKS), ('economy', ECONOMY_TAIL)):
+        for key, (glyph, ascii_twin, tone) in table.items():
+            cp = ' '.join(f'U+{ord(c):04X}' for c in glyph)
+            cell = ascii_twin.replace('|', '\\|')   # a bare pipe splits a GFM table cell even inside backticks
+            rows.append(f'| `{glyph}` | {cp} | `{cell}` | {tone} | {name} `{key}` |')
+    rows.append('<!-- END lanes tokens -->')
+    return '\n'.join(rows) + '\n'
+
+
+def render_js():
+    """The phone's xterm.js slots for BOTH variants. Zellij's web_client.theme is one server-wide (dark) palette that
+    arrives in the HTTP boot config and that SetConfig re-sends on every config reload, assigned wholesale; mobile.js
+    applies these on attach and re-applies them after each SetConfig (spec §6.3; DEF-1413). 495 B against mobile.js's
+    3072 B allowance (measured 2026-10-04)."""
+    body = ', '.join(f"{v}: [{', '.join(repr(c) for c in PALETTE16[v])}]" for v in ('dark', 'light'))
+    return ('// BEGIN lanes tokens (generated by libexec/tokens.py --js; do not edit by hand)\n'
+            f'  const LANES_ANSI = {{{body}}};\n  // END lanes tokens\n')
+
+
+def render_ghostty(variant):
+    """The optional Ghostty palette (spec §7; `install.sh --client --palette`): colours only — never font, theme,
+    padding or cursor style, the everyday config keeps those. Valid both as an included config file and as a Ghostty
+    theme file, so install.sh can include the dark one directly or pair both through `theme = light:…,dark:…`."""
+    t, p = TOKENS[variant], PALETTE16[variant]
+    lines = [f'# BEGIN lanes tokens (generated by libexec/tokens.py --ghostty-{variant}; do not edit by hand)',
+             '# Optional: the cockpit palette regardless of your everyday Ghostty theme (install.sh --client --palette).',
+             '# Slots 1-4 are the four tones, so 16-colour mode here equals truecolor mode. No font, padding or cursor keys.',
+             f'background = {t["surface"]}', f'foreground = {t["ink"]}', f'cursor-color = {t["accent"]}',
+             f'selection-background = {t["line"]}', f'selection-foreground = {t["ink"]}']
+    lines += [f'palette = {i}={c}' for i, c in enumerate(p)]
+    lines.append('# END lanes tokens')
+    return '\n'.join(lines) + '\n'
+
+
+RENDERERS = {'kdl': render_kdl, 'css': render_css, 'sh': render_sh, 'md': render_md, 'js': render_js,
+             'ghostty-dark': lambda: render_ghostty('dark'), 'ghostty-light': lambda: render_ghostty('light')}
+TARGETS = {'kdl': 'zellij/config.kdl', 'css': 'web/mobile.css', 'sh': 'libexec/tokens.sh', 'md': 'docs/DESIGN.md',
+           'js': 'web/mobile.js', 'ghostty-dark': 'client/ghostty/lanes-palette.conf',
+           'ghostty-light': 'client/ghostty/lanes-palette-light.conf'}
+MARKERS = {'kdl': ('// BEGIN lanes tokens', '// END lanes tokens'), 'css': ('/* BEGIN lanes tokens', '/* END lanes tokens */'),
+           'sh': ('# BEGIN lanes tokens', '# END lanes tokens'), 'md': ('<!-- BEGIN lanes tokens', '<!-- END lanes tokens -->'),
+           'js': ('// BEGIN lanes tokens', '// END lanes tokens'),
+           'ghostty-dark': ('# BEGIN lanes tokens', '# END lanes tokens'), 'ghostty-light': ('# BEGIN lanes tokens', '# END lanes tokens')}
+
+
+def render(kind):
+    return RENDERERS[kind]()
+
+
+def _splice(text, kind):
+    """Replace the marker block in `text` with the renderer's output; append when no block exists yet."""
+    begin, end = MARKERS[kind]
+    block = render(kind)
+    start = text.find(begin)
+    if start < 0:
+        return text + ('' if text.endswith('\n') or not text else '\n') + block
+    stop = text.find(end, start)
+    stop = text.find('\n', stop) + 1 if stop >= 0 else len(text)
+    return text[:start] + block + text[stop:]
+
+
+def check(repo):
+    """Paths (relative to `repo`) whose committed marker block is not what the renderer emits. A target that is
+    missing or has no block yet is reported too: an unadopted surface is drift, not a skip."""
+    drifted = []
+    for kind, rel in TARGETS.items():
+        path = Path(repo) / rel
+        try:
+            text = path.read_text()
+        except OSError:
+            drifted.append(rel)
+            continue
+        if _splice(text, kind) != text:
+            drifted.append(rel)
+    return drifted
+
+
+def main(argv):
+    repo = Path(__file__).resolve().parents[1]
+    if argv[:1] == ['--check']:
+        drifted = check(repo)
+        for rel in drifted:
+            kind = next(k for k, r in TARGETS.items() if r == rel)
+            current = (repo / rel).read_text() if (repo / rel).exists() else ''
+            sys.stdout.writelines(difflib.unified_diff(current.splitlines(True), _splice(current, kind).splitlines(True), rel, rel + ' (generated)'))
+        return 1 if drifted else 0
+    if argv[:1] == ['--write']:
+        for kind, rel in TARGETS.items():
+            path = repo / rel
+            current = path.read_text() if path.exists() else ''
+            path.write_text(_splice(current, kind))
+        return 0
+    kind = argv[0].lstrip('-') if argv else ''
+    if kind not in RENDERERS:
+        sys.exit('usage: tokens.py --kdl|--css|--sh|--md|--js|--ghostty-dark|--ghostty-light|--check|--write')
+    sys.stdout.write(render(kind))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))

package/payload/lanes/libexec/tokens.sh

@@ -0,0 +1,11 @@
+# Lanes 16-colour SGR literals for view.sh status screens. Sourced, never executed.
+# The block below is generated: edit libexec/tokens.py and run `python3 libexec/tokens.py --write`.
+# BEGIN lanes tokens (generated by libexec/tokens.py --sh; do not edit by hand)
+LZ_BOLD='\033[1m'
+LZ_DIM='\033[90m'
+LZ_URGENT='\033[31m'
+LZ_ATTENTION='\033[33m'
+LZ_WORKING='\033[34m'
+LZ_DONE='\033[32m'
+LZ_RESET='\033[0m'
+# END lanes tokens

package/payload/lanes/libexec/view.sh

@@ -58,12 +58,22 @@ reset_terminal() {
     printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[<u\033[0m\033[?25h\033[2J\033[3J\033[H'
 }
 
+# The 16-colour SGR literals of the design tokens (libexec/tokens.py --sh): sourced once, printf only, no fork.
+# They hold `\033[…m` as text, so they go into printf's FORMAT (which turns `\033` into ESC), never into a %s argument.
+# shellcheck source=libexec/tokens.sh
+. "$repo/libexec/tokens.sh"
+
 # status_screen <title> <text> <dim line> [<lead>]: a lead, when given, is the bold headline above the title.
+# The lead glyph follows the sidebar's published glyph mode ($STATE/clients/<device>.glyphs, written by sidebar.py from
+# devices/<device>.json) and is read on EVERY call with the builtin read, no fork: this runs exactly when the host may be
+# too slow for one, and `lanes attach DEVICE --ascii` against a live session must reach the next screen without a restart.
 status_screen() {
     reset_terminal
-    if [ -n "${4:-}" ]; then printf '\n  \033[1m%s\033[0m\n\n  %s\n' "$4" "$1"
-    else printf '\n  \033[1m%s\033[0m\n' "$1"; fi
-    printf '\n  %s\n\n  \033[2m%s\033[0m\n' "$2" "$3"
+    glyphs=unicode; { IFS= read -r glyphs < "$state/clients/$device.glyphs"; } 2>/dev/null || :
+    lead_glyph='⚠'; [ "$glyphs" != ascii ] || lead_glyph='!'
+    if [ -n "${4:-}" ]; then printf "\n  ${LZ_BOLD}%s %s${LZ_RESET}\n\n  %s\n" "$lead_glyph" "$4" "$1"
+    else printf "\n  ${LZ_BOLD}%s${LZ_RESET}\n" "$1"; fi
+    printf "\n  %s\n\n  ${LZ_DIM}%s${LZ_RESET}\n" "$2" "$3"
 }
 
 # Is the socket of the lane just shown still there? Then only this VIEWER ended: a lane lives in its holder's server
@@ -103,7 +113,7 @@ while :; do
     # A background-created zellij session has no real size yet: idle until a client has attached once.
     while [ ! -e "$state/clients/$device.ready" ] || { [ "$mobile" = 1 ] && [ ! -e "$dir/$ws.$slot.shown" ]; }; do
         status_screen "$ws" 'waiting for the first client…' ''
-        run sleep 2 || :
+        run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 2 || :
     done
 
     # zellij sizes a tab only once some client has looked at it; until then the pane has a made-up size
@@ -115,7 +125,7 @@ while :; do
         [ "$mobile" != 1 ] || { min_cols=20; min_rows=4; }
         if [ "${cols:-0}" -ge "$min_cols" ] 2>/dev/null && [ "${rows:-0}" -ge "$min_rows" ] 2>/dev/null; then break; fi
         status_screen "$ws" 'waiting to be shown…' ''
-        sizing=1; run sleep 3 || :; sizing=0
+        sizing=1; run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 3 || :; sizing=0
     done
 
     lane=$(head -n 1 "$target_file" 2>/dev/null || :)
@@ -126,13 +136,13 @@ while :; do
             if [ "$slot" = main ]; then hint='Pick one in the sidebar (Ctrl-Alt-/ to find a lane).'
             else hint='In the sidebar, move to a lane and press 2 (or 3) to show it here.'; fi
             status_screen "$ws" 'No lane selected.' "$hint"
-            switching=0; run sleep 5 || :; continue ;;
+            switching=0; run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 5 --preserve-screen || :; continue ;;
     esac
     resolve=$state/resolve/$lane
     if [ ! -r "$resolve" ]; then resolve=$state/resolve.dynamic/$lane; fi
     if [ ! -r "$resolve" ]; then
         status_screen "$lane" 'This lane is no longer in the registry.' 'Pick another lane in the sidebar.'
-        switching=0; run sleep 5 || :; continue
+        switching=0; run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait 5 --preserve-screen || :; continue
     fi
     { IFS= read -r holder; IFS= read -r f2; IFS= read -r f3; IFS= read -r f4; IFS= read -r title; } < "$resolve"
 
@@ -140,9 +150,10 @@ while :; do
     switching=0
     started=$(date +%s)
     case "$holder" in
-        tmux) run "$repo/holders/tmux.sh" "$f2" "$f3" "$f4" || : ;;
-        zmx)  run "$repo/holders/zmx.sh" "$f2" "$f3" "$f4" || : ;;
-        exec) run "$repo/holders/exec.sh" "$f2" "$f3" "$f4" || : ;;
+        tmux) run python3 "$repo/libexec/connection.py" --title "${title:-$lane}" -- "$repo/holders/tmux.sh" "$f2" "$f3" "$f4" || : ;;
+        ssh)  run "$repo/holders/ssh.sh" "$f2" "$f3" "$f4" || : ;;
+        zmx)  run python3 "$repo/libexec/connection.py" --title "${title:-$lane}" -- "$repo/holders/zmx.sh" "$f2" "$f3" "$f4" || : ;;
+        exec) run python3 "$repo/libexec/connection.py" --title "${title:-$lane}" -- "$repo/holders/exec.sh" "$f2" "$f3" "$f4" || : ;;
         *)    rc=64 ;;
     esac
     if [ "$switching" = 1 ]; then delay=1; continue; fi
@@ -173,7 +184,7 @@ while :; do
     health_hint "$ended"
     status_screen "${title:-$lane}" "${reason:-viewer detached (exit $rc)}${untouched}; retrying in ${delay}s.${host_hint:+
   $host_hint}" "$holder · $f2 · $f3 · $f4" "$lead"
-    run sleep "$delay" || :
+    run python3 "$repo/libexec/connection.py" --title "${title:-$ws}" --wait "$delay" --preserve-screen || :
     delay=$((delay * 2))
     if [ "$delay" -gt 15 ]; then delay=15; fi
 done

package/payload/lanes/systemd/lanes-economy.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=lanes economy projection (opt-in: GETs the Throttle daemon's loopback /status and /sessions, writes economy.json)
+After=lanes-statusd.service
+
+# No installer enables this unit. It reads the production daemon's control port, so switching it on is an operator
+# action: systemctl --user enable --now lanes-economy.service (RUNBOOK "Economy projection (opt-in)").
+# It runs on the HOST, not in the daemon's container: point LANES_THROTTLE_CONTAINER at that container for the log,
+# and use LANES_THROTTLE_CONTROL=none unless the control port is reachable from the host (RUNBOOK, DEF-1444).
+[Service]
+ExecStart=/usr/bin/python3 -S -E "@REPO@/libexec/economy_poll.py" --interval 10
+Restart=on-failure
+RestartSec=10
+Nice=10
+NoNewPrivileges=true
+MemoryHigh=96M
+MemoryMax=192M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/systemd/lanes-notify.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=lanes push notifications (opt-in: POSTs needs-you transitions from status.json to an ntfy topic)
+After=lanes-statusd.service
+
+# No installer enables this unit. It sends lane names and agent tasks to the ntfy server in
+# ~/.config/lanes/notify.conf (LANES_NOTIFY_CONF), so switching it on is an operator action:
+# systemctl --user enable --now lanes-notify.service (RUNBOOK "Push notifications (opt-in)").
+[Service]
+ExecStart=/usr/bin/python3 -S -E "@REPO@/libexec/notify.py" --interval 3
+Restart=on-failure
+RestartSec=10
+Nice=10
+NoNewPrivileges=true
+MemoryHigh=48M
+MemoryMax=96M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/systemd/lanes-sync.service

@@ -4,6 +4,9 @@ Description=lanes registry sync (read-only: rebuild registry.json from the repos
 [Service]
 Type=oneshot
 ExecStart="@REPO@/bin/lanes" sync
+# Bounded: one `docker inspect` (20 s) plus the registry reads. A sync wedged on a hung docker or volume is
+# stopped here instead of holding the oneshot (and every later timer tick) forever.
+TimeoutStartSec=120
 # A momentarily invalid registry keeps the previous lanes; a non-zero exit here is informational.
 SuccessExitStatus=1
 Nice=5

package/payload/lanes/web/README.md

@@ -5,11 +5,35 @@ The Lanes shell enhances the pinned Zellij 0.45.1 web client on phones. It uses
 There is no separate auth system or command API. Workspace names are rendered as text, and navigation
 uses Zellij's authenticated `FocusPane` messages. Desktop browsers keep the upstream interface.
 
+`laneShellMode` (in `mobile.js`) chooses the mode once at load and records it on `<html data-lanes-shell>`:
+phones get this shell; tablets (other touch screens) get the same shell with the dock in the top bar and the
+workspace sheet as a left panel, and set `zellij:mobile-ui` to `on` when it is unset (iPad Safari reports a desktop
+user agent). Desktop browsers (fine pointer) get only a **Lanes** chip and an overlay bar with workspace and lane
+pickers (`laneBarModel`, from the `MobileState` sent to every web client). The laptop/tablet code and styles live in
+`browser.js`/`browser.css`, which `mobile.js` appends only on a tablet or desktop (a phone never downloads them), so
+a phone downloads only the two files that spec §8 budgets (measured figures under Bundle budget below). The chip
+cancels `mousedown` and refocuses the terminal, so the keys stay the terminal's. On a tablet, `browser.js` also
+undoes the client's per-load single-pane start once
+(`laneFullRender`, the client's own `SetMobileRenderPreferences {single_pane: false, fit: true}`), so a desktop
+view's sidebar shows beside its lanes. `tests/web/activation.test.mjs` (`node --test`) pins the activation matrix,
+the picker model and that render preference; `tests/unit/test_web_view.py` pins the size budgets and runs that
+suite when node is installed. After an upgrade,
+check that `__zjMobileUi`, `__zjSendControl`, `__zjSoftKbdCapture`, `__zjSyncInactiveCursorStyle` and `window.term`
+still exist in the served `app.js`.
+
 The phone keyboard opens through a native tap on an input field. The bottom **Type here** field contains
 Zellij's original capture input in its closed shadow root, preserving its keyboard/IME handling. The client
 blocks programmatic focus on text editors and keeps `__zjSoftKbdEnabled` false, so upstream touch handlers,
 two-finger gestures, server `SetSoftKeyboard` messages and modal autofocus cannot summon it. Search and
 login inputs still focus normally when tapped. Keep this policy in place when upgrading the upstream client.
+The guard is installed before Zellij's first terminal or login modal: otherwise Zellij refocuses a hidden input on
+touchstart, touchend, click and server `SetSoftKeyboard` messages. The **Type here** field keeps the original input
+and its event handlers inside the closed shadow root (including its protection from password-manager extensions) and
+makes it a real, tappable field instead of a 1 px invisible focus target; keystrokes appear in the terminal and its
+internal padding/history stays invisible. Upstream cancels `pointerdown` on the extra keys, which also suppresses
+their touch click in Safari, so the shell cancels `mousedown` instead: typing focus is kept while the native click
+still activates CTRL, the arrows and the other keys. The shell attaches only once server state has arrived — resizing
+before the control socket opens makes 0.45.1 throw `InvalidStateError` and leaves the server with the old size.
 
 `lanes-mobile.service` runs a separate, loopback-only Caddy on port 8083 with its admin API disabled.
 It does not change the system Caddy. Tailscale Serve forwards private HTTPS on 8443 to this frontend;
@@ -26,8 +50,78 @@ clearing login cookies. There is no service worker caching terminal data or cred
 Layout uses the visual viewport and safe-area insets, with independent handling for portrait, landscape,
 keyboard-open and Home Screen views. The default terminal font is 16 px; the user's text-size choice
 is stored locally. Minimum touch targets are 44 px (workspace cards are 74 px). The lane picker in
-`libexec/sidebar.py` uses three terminal rows per lane on mobile. `tests/mobile_view.py` verifies
-the touch-to-lane path with isolated holders; sidebar unit tests cover the complete touch target.
+`libexec/sidebar.py` uses three terminal rows per lane on mobile: name, state and age, the agent's task.
+`tests/mobile_view.py` verifies the touch-to-lane path with isolated holders; sidebar unit tests cover the
+complete touch target.
+
+Every byte the shell sends to a terminal goes through `__zjSendControl({type: 'Write', bytes})`
+(`sendToTerminal`); there is no focus-and-type fallback, since the focus guard above would make it type nowhere.
+The lane filter bar sends `Esc /` and the query as UTF-8 (`TextEncoder`), dropping control bytes and DEL.
+Attention counts come from the picker sidebar's pane title (`WS · ◆1 ◇2 ▸6`, written by the sidebar as OSC 2):
+`parseCounts` (also `window.__lanesParseCounts`) feeds the picker subtitle, `document.title`, the Lanes button's
+`data-count` and the workspace cards, inside the existing `refresh()` / `renderCards()` — no fetch, file or timer.
+Until plan Task 26 (2026-10-04) this reader was inert (DEF-1450): `bin/lanes` `mobile_workspace_tab` gave the
+picker pane a fixed `name="Lanes"`, and Zellij reports a pane's layout name instead of its OSC 2 title, so
+`pickerTitle()` read `Lanes`, `parseCounts` returned null and the shell showed no counts ("Choose a lane to continue").
+Task 26 dropped that `name=` (pinned by `tests/unit/test_layout.py`) for sessions laid out since: an existing
+phone device keeps the old picker pane until `lanes rebuild <device>` (`upgrade-session` never re-lays-out a tab;
+`lanes doctor` names such a device). Whether the OSC 2 title now reaches
+`panes[].title` is still unchecked in a browser (no WebKit pass has run; fallback: the counts stay in the
+sidebar header). The quick-key row (`⏎ y n Esc ^C ↑ ↓`, `.lanes-quick`) shows on view
+tabs only; `refresh()` sets `--lanes-quick` (48 px or 0), which the terminal height subtracts. `n` and `^C` send
+only when `pointerup.timeStamp − pointerdown.timeStamp ≥ 400` (no `setTimeout`); the buttons cancel `mousedown`
+so a tap never moves focus.
+
+Colour (spec §6.3; the operator legend, token table and phone mockup are in [`docs/DESIGN.md`](../docs/DESIGN.md)):
+`mobile.css` uses only the generated `--lanes-*` tokens (legacy names such as `--lanes-bg` stay
+as aliases for one release); `test_web` rejects any colour literal outside the generated block. The terminal palette
+is the phone's own, because Zellij's `web_client.theme` is one server-wide dark palette (DEF-1413): `lanesTheme()`
+builds xterm.js's theme from the CSS tokens (`getComputedStyle(root)`) and the sixteen `LANES_ANSI` slots, which
+`libexec/tokens.py --js` generates into `mobile.js` (never hand-edited). It is applied at three points, all event
+driven: (1) on attach, after `build(); applyFont();`; (2) on every `data-zj-theme` change, through one
+`MutationObserver` on `<html>` (upstream's theme toggle only flips that attribute); (3) after every `SetConfig`, by
+chaining `window.__zjSyncInactiveCursorStyle`, which the pinned `app.js` calls in its `SetConfig` handler right after
+assigning the server theme wholesale (`SetConfig` is sent on each config-file reload). The handler then runs
+`applyTerminalBackground`, which writes the dark background inline on `<body>` and `#terminal`; the stylesheet's
+`!important` `--lanes-surface` rule for those two elements outranks it in either variant. An SRI bump of `app.js`
+re-opens this contract: re-read `startWsControl` and `installSoftKeyboardCapture` before accepting it.
+`index.html` carries one `theme-color` per colour scheme. Bundle budget (spec §8, `test_web.test_bundle_growth`):
+`mobile.css` ≤ 18 982 B and `mobile.js` ≤ 22 174 B; the caps are never raised — the rules sit one per line and the
+explanations live here rather than in the shipped files. MEASURED 2026-10-04 with `wc -c` after LNS-31 (plan Task
+31) met Tasks 13/28: `mobile.js` 21 964 B (23 268 B before its comments moved to Code notes below) and `mobile.css`
+18 945 B. A laptop or tablet also fetches `browser.js` (3 641 B) and `browser.css` (1 947 B); `test_web_view` pins
+that download at `LAPTOP_TABLET_JS_RATCHET` and `LAPTOP_TABLET_CSS_CAP` (DEF-1488).
+
+## Code notes
+
+`mobile.js` carries no explanations (the spec §8 budget above); each note is keyed to the code it explains, in file
+order.
+
+- The file: the Lanes browser shell (phone, tablet, desktop) over the pinned Zellij 0.45.1 client's window hooks.
+- `root.dataset.lanesShell = mode`: read by `browser.js` for the desktop bar and the tablet's full rendering.
+- `if (mode !== 'phone')`: appends the laptop/tablet extras (`browser.css`, `browser.js`); a phone never fetches them.
+- `if (mode === 'tablet')`: iPad Safari's user agent is a desktop one, so the shell asks for the client's mobile UI
+  (`zellij:mobile-ui` set to `on`); a stored `off` stays.
+- The `HTMLElement.prototype.focus` guard: only a native tap on an input may open the keyboard; it is installed before
+  upstream's first terminal or modal.
+- `viewport()`: browser toolbars alone must not mean keyboard mode (`occluded` needs more than 120 px hidden). Zellij's
+  input is in a closed shadow root, so `document.activeElement` is its host; `__zjSoftKbdCapture.isFocused` is read
+  first.
+- `buildTypingField()`: upstream's capture input stays in its closed shadow root and becomes the real, tappable field.
+- `GLYPHS` / `parseCounts()`: counts from the picker sidebar's OSC 2 pane title (spec §6.4).
+- `build()`, the `.zj-mobile-modbar` keys: cancel `mousedown`, not `pointerdown` (upstream's `pointerdown` cancel kills
+  Safari's touch click on the extra keys).
+- `buildQuickRow()` (spec §6.5): `n` and `^C` send after a 400 ms hold, measured from event timestamps with no timer;
+  nothing takes focus.
+- `clearLaneFilter()`: the lone `Esc` leaves the sidebar's filter mode.
+- `lanesTheme()`: the shell's own terminal palette for both variants (spec §6.3, DEF-1413).
+- `connect()`: waits for server state, because an earlier resize throws `InvalidStateError` in 0.45.1. `applyTheme` is
+  re-applied after every `SetConfig` (the client calls the chained `__zjSyncInactiveCursorStyle` hook) and on the theme
+  toggle.
+- The `zellij:soft-keyboard-visibility` listener: rotation also shrinks the viewport, so the shell sends
+  `SoftKeyboardVisibilityChanged` itself to correct upstream's height-only keyboard heuristic.
+- `awaitingClient` (the one `setInterval`, 200 ms, cleared once attached): upstream installs its window hooks just after
+  appending its mobile root.
 
 Validate on Safari/WebKit at 440 × 763 (iPhone 17 Pro Max with browser chrome), 440 × 956 (Home Screen),
 838 × 390 (landscape Safari), and smaller phone widths. Check login, workspace search and switching,

package/payload/lanes/web/browser.css

@@ -0,0 +1,22 @@
+/* LNS-31 laptop/tablet extras, outside the phone's mobile.css budget (spec §8). No scroll-time paint. */
+/* Tablet (LNS-31): the dock joins the top bar; the workspace sheet is a left panel */
+html.lanes-tablet, html.lanes-tablet.lanes-keyboard { --lanes-dock: 0px; }
+.lanes-tablet .lanes-dock { position: static; display: flex; gap: 4px; width: auto; height: 48px; padding: 0; border: 0; background: none; }
+.lanes-tablet .lanes-dock .lanes-button { flex-direction: row; gap: 6px; min-height: 44px; padding: 0 10px; }
+.lanes-tablet .lanes-dock .lanes-button span { font-size: 13px; }
+.lanes-tablet .lanes-terminal-input { width: 140px; height: 44px; }
+.lanes-tablet .lanes-input-label { flex-direction: row; }
+.lanes-tablet .lanes-filter-bar { flex: 0 1 220px; }
+.lanes-tablet .lanes-sheet { align-items: stretch; padding: 0; }
+.lanes-tablet .lanes-sheet-panel {
+  width: min(400px, 85vw); max-height: none; border: 1px solid var(--lanes-border); border-left: 0;
+  border-radius: 0 24px 24px 0; padding: calc(20px + var(--lanes-safe-top)) 16px calc(8px + var(--lanes-safe-bottom)) calc(16px + var(--lanes-safe-left));
+}
+
+/* Desktop (LNS-31): the plain client plus a Lanes chip and its overlay bar; system colours */
+.lanes-chip, .lanes-bar { position: fixed; z-index: 600; color-scheme: dark; font: 13px system-ui, sans-serif; }
+.lanes-chip { top: 4px; right: 8px; padding: 2px 10px; border: 1px solid GrayText; border-radius: 12px; background: Canvas; color: CanvasText; opacity: .7; cursor: pointer; }
+.lanes-chip:hover, .lanes-chip[aria-expanded="true"] { opacity: 1; }
+.lanes-bar { top: 0; left: 0; right: 0; height: 34px; display: flex; gap: 8px; align-items: center; padding: 0 80px 0 8px; background: Canvas; border-bottom: 1px solid GrayText; }
+.lanes-bar[hidden] { display: none; }
+.lanes-bar select { max-width: 40%; height: 26px; border: 1px solid GrayText; border-radius: 6px; background: Canvas; color: CanvasText; font: inherit; }