SPEC-46 P1: Docs screen, preview, and tailnet publishing

BRANCH_SUMMARY.md

@@ -0,0 +1,59 @@
+# SPEC-46 P1: Docs — Preview HTML and Markdown (feat/serving-html)
+
+## Status
+✅ **Verified on device.** 21 commits, 1243 server tests, 2061 app tests. All green.
+
+## What ships
+
+### Desktop & App
+- **Docs screen** (Option A from the spec): grouped by repo/worktree, searchable by title and path, filterable (All / Mockups / Specs / Changed)
+- **Markdown preview** in-app: front-matter (Status/Priority/Branch) hoisted above the title, reader-width toggle for desktop
+- **HTML preview**: local clients open in Safari/Edge via `docs.open` (no serving). Remote clients publish and share via tailnet grant.
+
+### Server
+- **D1 rev 2 — Everything git doesn't ignore**: `git ls-files --cached --others --exclude-standard` (69 docs in teachme, 143 in makit), with fallback to the old allowlist (`mockups/`, `docs/`, `*.md` at root) when git cannot answer
+- **D8 rev 2 — Where the viewer is decides how**: loopback client → `docs.open` → OS opener. Tailnet client → publish → grant → URL. No webview.
+- **D9/D10/D15**: tailnet-bound HTTP listener, lazy on first publish, capability URL in the path (no bearer), TTL-gated grants
+- **D11**: snapshot streaming, indexed by worktree, enriched with mtime, status, and changed flag
+
+### Fixes from ocr review
+- `serverIsLocal` reset on reconnect (race window between local→remote switch)
+- `markdownError` plumbed through FutureBuilder
+- Listener bind/close races coalesced
+- Popover crash when available height < 96pt (fixed with Flexible + ConstrainedBox)
+- All three `hello.ack` paths now send `isLocal`
+- `docs.open` refuses win32 (argv-only, no shell)
+- Defensive error handling in scan loop
+
+## Verified behavior (device test)
+- ✅ teachme shows **69 docs** (was 3 with D1 rev 1)
+- ✅ Popover **search field** works, filters title+path
+- ✅ Paths are **relative** in popover, **absolute** in Docs screen
+- ✅ **Open in browser** button on local client (no serve)
+- ✅ Edge opened HTML without any HTTP listener for this profile
+- ✅ `hello.ack` carries `isLocal: true` on loopback
+
+## Known non-issues
+- `flutter_tester` WebSocket concurrency flake (~19 failures per full-suite run, all `: loading ` entries, zero real assertion failures)
+- ocr found 48 issues: 5 high (all fixed + tests), 19 medium (left for follow-up), 24 low (left for follow-up)
+
+## Test coverage
+- Server: 1243/1243 pass (includes new race, timeout, coalesce, arg-passing tests)
+- App: 2061 pass (includes new D8 rev 2 local/remote split tests)
+- Both: typecheck clean, analyze clean
+
+## Not in P1 (deferred to P2+)
+- P2: Canvas (doc beside chat, live-reload)
+- P3: HTML in-app webview
+- P4+: VCS annotations, publishing from within the preview
+
+## Branch readiness
+- All commits squashed per project style? No — kept logical units for review
+- PR template required? Check with maintainers
+- Needs rebase? No — all commits since P1a exist only in this branch
+
+## For reviewers
+- Start with `d627c229` (SPEC-46 P1a) to see the security boundary
+- `00317d01` has the D1 rev 2 restructure (git vs walk)
+- `20a1cd8d` is the major refactor (ocr fixes + defensiveness)
+- `8495844a` wires D8 rev 2 (local OS opener)

app/lib/app/router.dart

@@ -7,6 +7,7 @@ import '../status/activity_screen.dart';
 import '../pairing/onboarding_controller.dart';
 import '../pairing/onboarding_screen.dart';
 import '../pairing/readiness.dart';
+import '../ui/docs/docs_screen.dart';
 import '../ui/home/closed_screen.dart';
 import '../ui/home/home_screen.dart';
 import '../ui/ports/ports_screen.dart';
@@ -63,6 +64,7 @@ final routerProvider = Provider<GoRouter>((ref) {
                 builder: (_, s) =>
                     PortsScreen(repoId: s.uri.queryParameters['repo']),
               ),
+              GoRoute(path: 'docs', builder: (_, _) => const DocsScreen()),
               GoRoute(
                 path: 'diagnostics',
                 builder: (_, _) => const DiagnosticsScreen(),

app/lib/app/routes.dart

@@ -29,5 +29,9 @@ const kRouteActivity = '$kRouteRepos/activity';
 /// optional `?repo=<id>` that pre-selects the *This repo* filter.
 const kRoutePorts = '$kRouteRepos/ports';
 
+/// The global Docs screen (SPEC-46 P1) — the repo's mockups and specs, grouped
+/// repo → worktree.
+const kRouteDocs = '$kRouteRepos/docs';
+
 /// A single session's screen.
 String routeForSession(String sessionId) => '$kRouteRepos/session/$sessionId';

app/lib/desktop/chat/desktop_sidebar.dart

@@ -7,9 +7,12 @@ import 'package:phosphoricons_flutter/phosphoricons_flutter.dart';
 import '../../app/theme.dart';
 import '../../store/connection.dart';
 import '../../store/models.dart';
+import '../../store/docs.dart';
 import '../../store/ports.dart';
 import '../../store/store.dart';
 import '../../ui/home/repo_chips.dart';
+import '../../ui/docs/docs_popover.dart';
+import '../../ui/docs/doc_preview.dart';
 import '../../ui/ports/ports_popover.dart';
 import '../../ui/ports/session_ports_glyph.dart';
 import '../../ui/widgets/pr_state_style.dart';
@@ -498,6 +501,11 @@ class _WorktreeGroupState extends ConsumerState<_WorktreeGroup> {
   // menu back to a diff pill under the cursor while the popover is open. The
   // popover reports its open-state through `onOpenChanged` (SPEC-41 §5 trap).
   bool _portsOpen = false;
+  bool _docsOpen = false;
+
+  // Hold the ref-counted docs watch while any worktree group is mounted (D11),
+  // the same discipline as the ports watch below.
+  late final DocsWatch _docsWatch = ref.read(docsWatchProvider);
 
   // Hold the ref-counted ports watch while any worktree group is mounted in the
   // sidebar, so the server polls `lsof` only while the sidebar is up (SPEC-41
@@ -509,11 +517,13 @@ class _WorktreeGroupState extends ConsumerState<_WorktreeGroup> {
   void initState() {
     super.initState();
     _portsWatch.watch();
+    _docsWatch.watch();
   }
 
   @override
   void dispose() {
     _portsWatch.release();
+    _docsWatch.release();
     super.dispose();
   }
 
@@ -620,7 +630,8 @@ class _WorktreeGroupState extends ConsumerState<_WorktreeGroup> {
                             if (_hovering ||
                                 _focused ||
                                 _menuOpen ||
-                                _portsOpen)
+                                _portsOpen ||
+                                _docsOpen)
                               _WorktreeMenuButton(
                                 worktree: worktree,
                                 onMenuOpened: () =>
@@ -710,6 +721,15 @@ class _WorktreeGroupState extends ConsumerState<_WorktreeGroup> {
                               // 22 × 16 target: wider than tall, so the fixed
                               // 16 pt sub-row does NOT grow. Renders nothing when
                               // the branch is serving nothing.
+                              // Docs glyph, sharing the trailing slot with the
+                              // ports plug (mockup Card 2 right frame). Renders
+                              // nothing when the branch owns no docs.
+                              _SubRowDocsGlyph(
+                                worktreePath: worktree.path,
+                                branch: branch,
+                                onOpenChanged: (open) =>
+                                    setState(() => _docsOpen = open),
+                              ),
                               _SubRowPortsGlyph(
                                 worktreePath: worktree.path,
                                 branch: branch,
@@ -898,6 +918,43 @@ class _WorktreeMenuButton extends ConsumerWidget {
   }
 }
 
+/// The worktree sub-row's docs glyph (SPEC-46), desktop form. A 14 pt glyph in
+/// a fixed 22 × 16 hit target so the sub-row keeps its reserved height. Opens
+/// the docs popover; renders nothing when the branch owns no docs.
+class _SubRowDocsGlyph extends ConsumerWidget {
+  const _SubRowDocsGlyph({
+    required this.worktreePath,
+    required this.branch,
+    required this.onOpenChanged,
+  });
+
+  final String worktreePath;
+  final String branch;
+  final ValueChanged<bool> onOpenChanged;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final docs = ref.watch(docsForWorktreeProvider(worktreePath));
+    if (docs.isEmpty) return const SizedBox.shrink();
+    return SizedBox(
+      key: ValueKey('docsSubRowTarget-$worktreePath'),
+      width: 22,
+      height: 16,
+      child: Center(
+        child: DocsPopover(
+          branch: branch,
+          docs: docs,
+          onOpenChanged: onOpenChanged,
+          // The preview is a widget in a sheet (D12); Navigator.of works on the
+          // MaterialApp(home:) desktop shell — unlike `context.go`, which has no
+          // GoRouter there.
+          onOpenDoc: (doc) => showDocPreviewSheet(context, doc),
+        ),
+      ),
+    );
+  }
+}
+
 /// The worktree sub-row's ports glyph (SPEC-41 §5), desktop form. A 14 pt glyph
 /// in a fixed 22 × 16 hit target — wider, not taller — so the sub-row keeps its
 /// reserved 16 pt height. Hit testing is bounded by this box (Flutter clips to

app/lib/store/connection.dart

@@ -91,6 +91,7 @@ class MakitConnState {
     this.useFake = false,
     this.lastError,
     this.pushRegistered = false,
+    this.serverIsLocal = false,
   });
 
   /// Every server this device has paired with. Only [activeServer] holds a live
@@ -125,6 +126,15 @@ class MakitConnState {
   /// (SPEC-07). Resets on reconnect; used by Settings to show wake status.
   final bool pushRegistered;
 
+  /// SPEC-46 D8 rev 2: whether this client shares a machine with the server,
+  /// **as stated by the server** in `hello.ack`.
+  ///
+  /// Never inferred from [PairedServer.host]: mDNS rediscovery rewrites that
+  /// behind us, and a loopback-looking host is not proof anyway. Governs whether
+  /// a document can be opened directly (`docs.open`) or has to be published.
+  /// Defaults false, so the safe path (publish) is the fallback.
+  final bool serverIsLocal;
+
   bool get paired => activeServer != null || useFake || _wsUrl.isNotEmpty;
 
   MakitConnState copyWith({
@@ -134,6 +144,7 @@ class MakitConnState {
     bool? useFake,
     String? lastError,
     bool? pushRegistered,
+    bool? serverIsLocal,
     bool clearError = false,
     bool clearServer = false,
     bool clearPushRegistered = false,
@@ -146,6 +157,7 @@ class MakitConnState {
     pushRegistered: clearPushRegistered
         ? false
         : (pushRegistered ?? this.pushRegistered),
+    serverIsLocal: serverIsLocal ?? this.serverIsLocal,
   );
 }
 
@@ -510,7 +522,19 @@ class ConnectionController extends StateNotifier<MakitConnState> {
 
     final ws = _transportFactory();
     _ws = ws;
-    _wsSub = ws.frames.listen(_inFrames.add);
+    // Reset serverIsLocal on each new connection; it will be set from hello.ack if local.
+    state = state.copyWith(serverIsLocal: false);
+    _wsSub = ws.frames.listen((env) {
+      // D8 rev 2: the server states whether we share its machine. Captured here,
+      // before fan-out, so it is set by the time any screen reads it.
+      if (env.t == MsgType.helloAck) {
+        final isLocal = env.body['isLocal'];
+        // Absent (an older server) is treated as remote: publishing works
+        // everywhere, so the fallback must be the one that cannot be wrong.
+        state = state.copyWith(serverIsLocal: isLocal == true);
+      }
+      _inFrames.add(env);
+    });
     _wsStateSub = ws.state.listen((s) {
       // Clear any stale "unreachable" error once we're actually connected, so
       // the connection chip doesn't keep showing a dead-server message after a