The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat(web): count what readers do on a shared link, as the Hub does (#1443)
Jacob Pham78f7e2edb5b8
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 33afcd574..e94a0002e 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -172,6 +172,7 @@ jobs:/docs/images//mobile/pubspec.lock/backend/src/lib/communityContract.ts+ /backend/src/lib/hubMetricsContract.ts/mobile/lib/p2p/terminal_p2p_plugin.dart/mobile/lib/p2p/terminal_p2p_link.dart/mobile/lib/p2p/terminal_p2p_policy.dartdiff --git a/backend/README.md b/backend/README.mdindex 4fee69d47..f3610f8ce 100644--- a/backend/README.md+++ b/backend/README.md@@ -312,7 +312,7 @@ The expanded measurement contract adds fixed app-flow and feature-use counts, D2installation returns, and voluntary task outcomes. Native signed-out setup is a separate explicitsession opt-in at `POST /api/product-usage/setup`; it rejects credentials and arbitrary fields andhas a process-wide admission budget without storing IP addresses. Web app signed-out setup reporting-is disabled. Anonymous Hub totals arrive at `POST /api/product-usage/hub`, forwarded by the website's+is disabled. Anonymous Hub totals, shared links' (`/s/:id`) included, arrive at `POST /api/product-usage/hub`, forwarded by the website'sserver without cookies or auth; the route accepts only the Hub vocabulary (`src/lib/hubMetricsContract.ts`)and has its own admission budget.Daily reports keep these populations separate, show unmatched outcomes and measurement loss, anddiff --git a/backend/src/analytics/dailyHubUsage.test.ts b/backend/src/analytics/dailyHubUsage.test.tsindex f32926b0f..11815a0de 100644--- a/backend/src/analytics/dailyHubUsage.test.ts+++ b/backend/src/analytics/dailyHubUsage.test.ts@@ -36,3 +36,17 @@ it('splits views by reader, counts entries, actions and dwell, and keeps both siexpect(today.totals?.forkClicksPerHarnessView).toEqual({ numerator: 0, denominator: 0, ratio: null })expect(JSON.stringify(hub)).not.toContain('PRIVATE_CANARY')})++it('reads a shared link apart: what it showed, how long it stayed, and its clicks', () => {+ const [day] = dailyHubUsage([+ r('2026-10-13', 'hub_view_shared_visitor', 9), r('2026-10-13', 'hub_shared_open_live', 6), r('2026-10-13', 'hub_shared_open_offline', 3),+ r('2026-10-13', 'hub_shared_dwell_10s_to_1m', 4), r('2026-10-13', 'hub_shared_get_app', 2),+ ], 1, new Date('2026-10-13T12:00:00Z')).daily+ expect(day.totals).toMatchObject({+ views: { shared: { visitor: 9, member: 0 } },+ sharedOpens: { live: 6, offline: 3, private: 0, no_access: 0, failed: 0 },+ sharedDwell: { under_10s: 0, '10s_to_1m': 4, over_1m: 0 },+ harnessDwell: { '10s_to_1m': 0 },+ actions: { shared_get_app: 2, get_app: 0 },+ })+})diff --git a/backend/src/analytics/dailyHubUsage.ts b/backend/src/analytics/dailyHubUsage.tsindex ff8f30b8c..c97c59269 100644--- a/backend/src/analytics/dailyHubUsage.ts+++ b/backend/src/analytics/dailyHubUsage.ts@@ -1,4 +1,4 @@-import { HUB_ACTIONS, HUB_DWELL, HUB_ENTRY_SOURCES, HUB_METRICS, HUB_READERS, HUB_VIEW_PAGES } from '../lib/hubMetricsContract.js'+import { HUB_ACTIONS, HUB_DWELL, HUB_ENTRY_SOURCES, HUB_METRICS, HUB_READERS, HUB_SHARED_OPENS, HUB_VIEW_PAGES } from '../lib/hubMetricsContract.js'const DAY = 86_400_000type Row = { dayUtc: Date; metric: string; value: number }@@ -21,6 +21,8 @@ function hubDay(c: Record<string, number> | undefined) {return {views, entries: pick(HUB_ENTRY_SOURCES, source => `hub_entry_${source}`, c), actions,harnessDwell: pick(HUB_DWELL, bucket => `hub_harness_dwell_${bucket}`, c),+ sharedOpens: pick(HUB_SHARED_OPENS, open => `hub_shared_open_${open}`, c),+ sharedDwell: pick(HUB_DWELL, bucket => `hub_shared_dwell_${bucket}`, c),forkClicksPerHarnessView: ratio(actions.fork, views.harness.visitor + views.harness.member),signInClicksPerPromptShown: ratio(actions.sign_in_prompt_click, actions.sign_in_prompt_shown),}@@ -44,6 +46,8 @@ export function dailyHubUsage(rows: Row[], days: number, now: Date) {views: 'A Hub page drawn, once per navigation; visitor is signed out, member signed in.',entries: 'The first Hub page of a browser tab\'s visit, by where it came from, classified in the browser; no referrer is sent.',harnessDwell: 'How long a harness page stayed visible, once per view.',+ sharedOpens: 'What a shared link (`/s/:id`) showed, each outcome at most once per page: live, the owner\'s machine offline, private before sign-in, no access, or failed.',+ sharedDwell: 'How long a live shared harness stayed visible, once per page.',ratios: 'Two separate daily totals divided; a click can follow a view counted on another day. Keep the numerator and denominator.',trust: 'Public, credential-free counts: they can be fabricated. Directional only; no margins are kept, so no suppression applies.',},diff --git a/backend/src/lib/hubMetricsContract.ts b/backend/src/lib/hubMetricsContract.tsindex bcc104382..9c9537ada 100644--- a/backend/src/lib/hubMetricsContract.ts+++ b/backend/src/lib/hubMetricsContract.ts@@ -4,28 +4,37 @@* cookies and auth stripped; its test imports this file directly, so keep it free of imports.*/-/** Hub pages counted when drawn, once per navigation. */-export const HUB_VIEW_PAGES = ['feed', 'harness', 'creator', 'publish', 'notifications', 'fork'] as const+/** Hub pages counted when drawn, once per navigation. `shared`: a harness someone shared live (`/s/:id`, the web app). */+export const HUB_VIEW_PAGES = ['feed', 'harness', 'creator', 'publish', 'notifications', 'fork', 'shared'] as const/** Who drew the page: signed out (`visitor`) or signed in (`member`). */export const HUB_READERS = ['visitor', 'member'] as const/** Where the first Hub page of a browser tab's visit came from, classified in the browser; the referrer is never sent. */export const HUB_ENTRY_SOURCES = ['direct', 'search', 'social', 'internal', 'other'] as const-/** How long a harness page stayed visible, once per view. */+/** How long a harness page, or a live shared harness, stayed visible, once per view. */export const HUB_DWELL = ['under_10s', '10s_to_1m', 'over_1m'] as const-/** One per click or submit. `get_app`: Explore's link to the Harness desktop app. */+/** What a shared link first showed, each at most once per page: the harness live, its owner's machine offline,+ * a private link before sign-in, an account not invited or a link stopped, or a link or connection that failed. */+export const HUB_SHARED_OPENS = ['live', 'offline', 'private', 'no_access', 'failed'] as const+/** One per click or submit. `get_app`: Explore's link to the Harness desktop app. `shared_*` happen on a shared+ * link: `viewer_shown` once when its live viewer first draws, `product_page` its Harness link. */export const HUB_ACTIONS = ['feed_search', 'feed_category', 'feed_sort_newest', 'feed_sort_popular', 'feed_sort_trending', 'feed_more', 'card_open','like', 'comment_post', 'comments_open', 'files_open', 'fullscreen','share_open', 'share_copy', 'share_x', 'share_facebook', 'share_linkedin', 'share_sheet','fork', 'fork_need_app', 'follow', 'report','sign_in_prompt_shown', 'sign_in_prompt_click', 'get_app', 'publish_started', 'publish_ok', 'publish_failed',+ 'shared_viewer_shown', 'shared_comments_open', 'shared_comment_post', 'shared_sign_in_click', 'shared_retry',+ 'shared_get_app', 'shared_product_page',] as constexport const HUB_METRICS = [...HUB_VIEW_PAGES.flatMap(page => HUB_READERS.map(reader => `hub_view_${page}_${reader}` as const)),...HUB_ENTRY_SOURCES.map(source => `hub_entry_${source}` as const),...HUB_ACTIONS.map(action => `hub_${action}` as const),...HUB_DWELL.map(bucket => `hub_harness_dwell_${bucket}` as const),+ ...HUB_SHARED_OPENS.map(open => `hub_shared_open_${open}` as const),+ ...HUB_DWELL.map(bucket => `hub_shared_dwell_${bucket}` as const),] as constexport type HubMetric = typeof HUB_METRICS[number]-export const HUB_REPORT_MAX_COUNTERS = 48+/** A report may carry every counter once. */+export const HUB_REPORT_MAX_COUNTERS = HUB_METRICS.lengthexport const HUB_REPORT_MAX_VALUE = 1000diff --git a/desktop/lib/measurement/hub_usage.dart b/desktop/lib/measurement/hub_usage.dartnew file mode 100644index 000000000..4957979d9--- /dev/null+++ b/desktop/lib/measurement/hub_usage.dart@@ -0,0 +1,185 @@+import 'dart:async';+import 'dart:convert';++import 'package:flutter/foundation.dart';++import 'hub_usage_browser_native.dart'+ if (dart.library.js_interop) 'hub_usage_browser_web.dart'+ as browser;+import 'product_measurement.dart' show newProductReceipt;++/// What a shared link (`/s/:id`) showed, each counted at most once per page. The wires are the+/// backend's `HUB_SHARED_OPENS` (`backend/src/lib/hubMetricsContract.ts`; `hub_usage_contract_test.dart`+/// fails when they drift).+enum SharedOpen {+ live('live'),+ offline('offline'),+ private('private'),+ noAccess('no_access'),+ failed('failed');++ const SharedOpen(this.wire);+ final String wire;+ String get metric => 'hub_shared_open_$wire';+}++/// One per click on a shared link, or once when its live viewer first draws; the backend's+/// `shared_*` entries of `HUB_ACTIONS`.+enum SharedAction {+ viewerShown('viewer_shown'),+ commentsOpen('comments_open'),+ commentPost('comment_post'),+ signInClick('sign_in_click'),+ retry('retry'),+ getApp('get_app'),+ productPage('product_page');++ const SharedAction(this.wire);+ final String wire;+ String get metric => 'hub_shared_$wire';+}++/// The shared page drawn, by a signed-out visitor or a signed-in member.+String sharedViewMetric({required bool member}) =>+ 'hub_view_shared_${member ? 'member' : 'visitor'}';++/// How long a live shared harness stayed in view, bucketed as the backend's `HUB_DWELL`.+String sharedDwellMetric(Duration shown) =>+ 'hub_shared_dwell_${shown < const Duration(seconds: 10)+ ? 'under_10s'+ : shown < const Duration(minutes: 1)+ ? '10s_to_1m'+ : 'over_1m'}';++const hubReportMaxValue = 1000;++/// The web app's half of the Hub's anonymous counters (the website's is `hubMeasure.ts`): daily+/// totals kept in memory and sent to the website's server (`/api/hub-usage`) a minute after the+/// first count and as the tab hides, without cookies. A sign-in rides along only so that server+/// can leave out a member who turned sharing off; it never reaches the backend. Nothing is counted+/// in a native or debug build, or under Global Privacy Control or Do Not Track. A failed send is+/// lost: measurement never retries into the reader's way.+class HubUsage {+ HubUsage({+ bool Function()? enabled,+ void Function(String body, String? authorization)? post,+ DateTime Function()? now,+ String Function()? receipt,+ this.flushAfter = const Duration(minutes: 1),+ }) : _enabled =+ enabled ??+ (() => kIsWeb && kReleaseMode && browser.hubUsageAllowed()),+ _post = post ?? browser.postHubUsage,+ _now = now ?? DateTime.now,+ _receipt = receipt ?? newProductReceipt;++ final bool Function() _enabled;+ final void Function(String body, String? authorization) _post;+ final DateTime Function() _now;+ final String Function() _receipt;+ final Duration flushAfter;+ final _counts = <String, int>{};+ String _day = '';+ Timer? _timer;+ bool _listening = false;++ Future<String?> Function()? _accessToken;+ String? _authorization;+ bool _authorizationKnown = true;+ int _reads = 0;++ /// Reads the reader's sign-in (null when signed out); set by the page that counts. Until the first+ /// read answers, nothing is sent, so a member is never counted without their choice being checked.+ set accessToken(Future<String?> Function()? read) {+ _accessToken = read;+ _authorization = null;+ _authorizationKnown = read == null;+ _reads++;+ if (read != null) _readAuthorization();+ }++ void _readAuthorization() {+ final read = _accessToken, generation = _reads;+ if (read == null) return;+ read().then(+ (token) {+ if (generation != _reads) return;+ _authorization = token == null ? null : 'Bearer $token';+ _authorizationKnown = true;+ },+ onError: (Object _) {+ // An unreadable sign-in keeps the last answer, or, with none yet, sends nothing.+ },+ );+ }++ String _utcDay() => _now().toUtc().toIso8601String().substring(0, 10);++ /// One more of [metric] today.+ void count(String metric) {+ if (!_enabled()) return;+ _listen();+ if (_day.isNotEmpty && _day != _utcDay()) flush();+ _day = _utcDay();+ _counts[metric] = ((_counts[metric] ?? 0) + 1).clamp(1, hubReportMaxValue);+ if (_timer != null) return;+ _timer = Timer(flushAfter, flush);+ // A fresh read per report: a sign-in that changed or was renewed since the last one.+ _readAuthorization();+ }++ /// Sends what is counted so far, once.+ void flush() {+ _timer?.cancel();+ _timer = null;+ if (_counts.isEmpty) return;+ final report = {+ 'schemaVersion': 1,+ 'id': _receipt(),+ 'day': _day,+ 'counters': Map.of(_counts),+ };+ _counts.clear();+ if (!_authorizationKnown) return;+ _post(jsonEncode(report), _authorization);+ }++ void _listen() {+ if (_listening) return;+ _listening = true;+ browser.watchPage(+ visibility: (visible) {+ if (!visible) flush();+ },+ leave: flush,+ );+ }+}++/// The web app's one collector.+final hubUsage = HubUsage();++/// How long something stayed in view, hidden time not counted, reported once as it is left: the+/// page closing, or [finish] (a widget going away).+class VisibleTime {+ VisibleTime(this._done) {+ if (browser.pageVisible()) _shown.start();+ _unwatch = browser.watchPage(+ visibility: (visible) => visible ? _shown.start() : _shown.stop(),+ leave: finish,+ );+ }++ final void Function(Duration shown) _done;+ final _shown = Stopwatch();+ late final void Function() _unwatch;+ bool _finished = false;++ void finish() {+ if (_finished) return;+ _finished = true;+ _unwatch();+ _shown.stop();+ _done(_shown.elapsed);+ }+}diff --git a/desktop/lib/measurement/hub_usage_browser_native.dart b/desktop/lib/measurement/hub_usage_browser_native.dartnew file mode 100644index 000000000..6d623168d--- /dev/null+++ b/desktop/lib/measurement/hub_usage_browser_native.dart@@ -0,0 +1,11 @@+/// Hub counting is the browser's: a native build sends nothing.+bool hubUsageAllowed() => false;++bool pageVisible() => true;++void postHubUsage(String body, String? authorization) {}++void Function() watchPage({+ required void Function(bool visible) visibility,+ required void Function() leave,+}) => () {};diff --git a/desktop/lib/measurement/hub_usage_browser_web.dart b/desktop/lib/measurement/hub_usage_browser_web.dartnew file mode 100644index 000000000..eea76e1a3--- /dev/null+++ b/desktop/lib/measurement/hub_usage_browser_web.dart@@ -0,0 +1,53 @@+import 'dart:js_interop';++import 'package:web/web.dart' as web;++/// The two privacy signals, which package:web does not declare.+extension on web.Navigator {+ external bool? get globalPrivacyControl;+ external String? get doNotTrack;+}++/// Global Privacy Control and Do Not Track turn Hub counting off.+bool hubUsageAllowed() {+ final navigator = web.window.navigator;+ return navigator.globalPrivacyControl != true && navigator.doNotTrack != '1';+}++bool pageVisible() => web.document.visibilityState == 'visible';++/// To the website's own server, which strips the sign-in before the backend: no cookies, and+/// `keepalive` so a report sent as the page goes still leaves. A failed send is dropped.+void postHubUsage(String body, String? authorization) {+ final headers = web.Headers()..set('Content-Type', 'application/json');+ if (authorization != null) headers.set('Authorization', authorization);+ web.window+ .fetch(+ '/api/hub-usage'.toJS,+ web.RequestInit(+ method: 'POST',+ headers: headers,+ body: body.toJS,+ credentials: 'omit',+ cache: 'no-store',+ keepalive: true,+ ),+ )+ .toDart+ .ignore();+}++/// Calls [visibility] as the tab shows or hides and [leave] as the page goes; returns the unsubscribe.+void Function() watchPage({+ required void Function(bool visible) visibility,+ required void Function() leave,+}) {+ final onVisibility = ((web.Event _) => visibility(pageVisible())).toJS;+ final onLeave = ((web.Event _) => leave()).toJS;+ web.document.addEventListener('visibilitychange', onVisibility);+ web.window.addEventListener('pagehide', onLeave);+ return () {+ web.document.removeEventListener('visibilitychange', onVisibility);+ web.window.removeEventListener('pagehide', onLeave);+ };+}diff --git a/desktop/lib/sharing/shared_agent_page.dart b/desktop/lib/sharing/shared_agent_page.dartindex 63cf1f24c..1baf80ac4 100644--- a/desktop/lib/sharing/shared_agent_page.dart+++ b/desktop/lib/sharing/shared_agent_page.dart@@ -5,6 +5,7 @@ import 'package:flutter/material.dart';import 'package:url_launcher/link.dart';import '../core/models.dart';+import '../measurement/hub_usage.dart';import '../shared/theme/app_theme.dart' as grid;import '../state/app_state.dart';import '../state/terminal_pane.dart';@@ -15,16 +16,22 @@ import 'shared_harness_panel.dart';/// Public landing and private recipient view, using the same encrypted renderer as desktop./// It does not add a machine, receive a peer key, or restore the visitor's workspace.+/// It counts, as the Hub does ([HubUsage]), the page drawn, what the link showed, how long a live+/// harness stayed in view and the clicks on it; never the link, its key, the harness or the reader.class SharedAgentPage extends StatefulWidget {const SharedAgentPage({super.key,required this.app,required this.location,this.dio,+ this.usage,});final AppNotifier app;final SharedAgentLocation location;final Dio? dio;++ /// Tests pass their own; the page otherwise counts into the app's [hubUsage].+ final HubUsage? usage;@overrideState<SharedAgentPage> createState() => _SharedAgentPageState();}@@ -45,15 +52,73 @@ class _SharedAgentPageState extends State<SharedAgentPage> {int _revision = 0;Timer? _offlineRetry;late bool _signedIn = widget.app.status == AppStatus.authenticated;+ late final _usage = widget.usage ?? hubUsage;+ bool _viewCounted = false;+ final _opens = <SharedOpen>{};+ VisibleTime? _dwell;@overridevoid initState() {super.initState();+ _usage.accessToken = _accessToken;+ _countView();+ unawaited(_load());+ }++ /// A staging link or account is the team's own, not a reader's.+ bool get _measured =>+ widget.location.environment != 'stag' &&+ widget.app.config.autonomousEnv != 'stag';++ void _count(String metric) {+ if (_measured) _usage.count(metric);+ }++ void _countAction(SharedAction action) => _count(action.metric);++ /// Once per page, as soon as it is known whether the reader is signed in.+ void _countView() {+ final status = widget.app.status;+ if (_viewCounted ||+ (status != AppStatus.authenticated &&+ status != AppStatus.unauthenticated)) {+ return;+ }+ _viewCounted = true;+ _count(sharedViewMetric(member: status == AppStatus.authenticated));+ }++ void _countOpen(SharedOpen open) {+ if (_opens.add(open)) _count(open.metric);+ // Counted, then sent with the rest, as the page goes or the panel leaves.+ if (open == SharedOpen.live) {+ _dwell ??= VisibleTime((shown) {+ _count(sharedDwellMetric(shown));+ _usage.flush();+ });+ }+ }++ Future<String?> _accessToken() async {+ final auth = widget.app.viewer?.auth;+ return auth != null && await auth.hasSession()+ ? await auth.accessToken()+ : null;+ }++ void _signIn() {+ _countAction(SharedAction.signInClick);+ unawaited(widget.app.login());+ }++ void _retry() {+ _countAction(SharedAction.retry);unawaited(_load());}@overridevoid didUpdateWidget(SharedAgentPage oldWidget) {super.didUpdateWidget(oldWidget);+ _countView();final signedIn = widget.app.status == AppStatus.authenticated;if (signedIn != _signedIn || oldWidget.location.id != widget.location.id) {_signedIn = signedIn;@@ -65,6 +130,8 @@ class _SharedAgentPageState extends State<SharedAgentPage> {void dispose() {_revision++;_offlineRetry?.cancel();+ _dwell?.finish();+ _usage.accessToken = null;if (widget.dio == null) _dio.close(force: true);super.dispose();}@@ -85,10 +152,7 @@ class _SharedAgentPageState extends State<SharedAgentPage> {'This link is incomplete. Ask the owner to copy the full link again.',);}- final auth = widget.app.viewer?.auth;- final token = auth != null && await auth.hasSession()- ? await auth.accessToken()- : null;+ final token = await _accessToken();final response = await _dio.get('${widget.app.config.apiBaseUrl}/api/shared-agents/${widget.location.id}',options: Options(@@ -100,6 +164,9 @@ class _SharedAgentPageState extends State<SharedAgentPage> {);if (!mounted || revision != _revision) return;if (response.statusCode != 200) {+ _countOpen(+ response.statusCode == 401 ? SharedOpen.private : SharedOpen.noAccess,+ );setState(() {_signInRequired = response.statusCode == 401;_error = _signInRequired@@ -116,6 +183,7 @@ class _SharedAgentPageState extends State<SharedAgentPage> {);}if (data['online'] != true) {+ _countOpen(SharedOpen.offline);setState(() {_loading = false;_error = 'The owner’s machine is offline. This page reconnects when it comes back.';@@ -126,12 +194,14 @@ class _SharedAgentPageState extends State<SharedAgentPage> {);return;}+ _countOpen(SharedOpen.live);setState(() {_data = data;_loading = false;});} catch (error) {if (mounted && revision == _revision) {+ _countOpen(SharedOpen.failed);setState(() {_loading = false;_error = error is FormatException ? error.message : 'Could not open this link. Check your connection and try again.';@@ -167,10 +237,20 @@ class _SharedAgentPageState extends State<SharedAgentPage> {builder: (context, follow) => DesktopPill(label: 'Harness',quiet: true,- onPressed: follow,+ onPressed: follow == null+ ? null+ : () {+ _countAction(SharedAction.productPage);+ follow();+ },),),- const WebDownloadButton(),+ WebDownloadButton(+ open: (uri) {+ _countAction(SharedAction.getApp);+ return openInNewTab(uri);+ },+ ),],),),@@ -201,9 +281,8 @@ class _SharedAgentPageState extends State<SharedAgentPage> {_data = null;_error = 'Viewing paused.';}),- onSignIn: _signedIn- ? null- : () => unawaited(widget.app.login()),+ onSignIn: _signedIn ? null : _signIn,+ onUsage: _countAction,): Center(child: SingleChildScrollView(@@ -258,12 +337,12 @@ class _SharedAgentPageState extends State<SharedAgentPage> {: 'Sign in',onPressed: widget.app.signingIn? null- : () => unawaited(widget.app.login()),+ : _signIn,),if (!_loading && !_signInRequired)DesktopPill(label: 'Retry',- onPressed: _load,+ onPressed: _retry,),if (!_loading && _signedIn && _data == null)DesktopPill(diff --git a/desktop/lib/sharing/shared_harness_panel.dart b/desktop/lib/sharing/shared_harness_panel.dartindex 90474e3b6..8ecaba1f3 100644--- a/desktop/lib/sharing/shared_harness_panel.dart+++ b/desktop/lib/sharing/shared_harness_panel.dart@@ -7,6 +7,7 @@ import 'package:harness/terminal/terminal_text.dart';import '../core/models.dart';import '../logging/app_log.dart';+import '../measurement/hub_usage.dart';import '../shared/theme/app_theme.dart' as grid;import '../state/app_state.dart';import '../state/terminal_pane.dart';@@ -34,6 +35,7 @@ class SharedHarnessPanel extends StatefulWidget {this.link = false,this.linkEnvironment,this.onSignIn,+ this.onUsage,});final AppNotifier notifier;final TerminalPane pane;@@ -43,6 +45,9 @@ class SharedHarnessPanel extends StatefulWidget {final bool link;final String? linkEnvironment;final VoidCallback? onSignIn;++ /// A shared link's clicks, for its page to count; the workspace's own shared panes pass none.+ final ValueChanged<SharedAction>? onUsage;@overrideState<SharedHarnessPanel> createState() => _SharedHarnessPanelState();}@@ -63,6 +68,9 @@ class _SharedHarnessPanelState extends State<SharedHarnessPanel> {/// noticed left the person looking at a terminal they cannot type into/// (owner, 2026-09-18: "chỉ thấy màn hình terminal").bool _viewerChosen = false;++ /// Counted once per panel: the harness drew a live viewer, not only a terminal.+ bool _viewerShown = false;String _lastViewerState = '';int _generation = 0;bool _commentsSelected = false, _commentsOpened = false;@@ -223,6 +231,10 @@ class _SharedHarnessPanelState extends State<SharedHarnessPanel> {'${payload['message'] != null ? ' · ${payload['message']}' : ''}',);}+ if (next != null && _image == null && !_viewerShown) {+ _viewerShown = true;+ widget.onUsage?.call(SharedAction.viewerShown);+ }setState(() {if (next != null) {if (_image == null && !_viewerChosen) _viewerSelected = true;@@ -277,6 +289,7 @@ class _SharedHarnessPanelState extends State<SharedHarnessPanel> {}void _retry() {+ widget.onUsage?.call(SharedAction.retry);_closeSession();_ended = false;_failure = null;@@ -284,10 +297,13 @@ class _SharedHarnessPanelState extends State<SharedHarnessPanel> {setState(_start);}- void _toggleComments() => setState(() {- _commentsSelected = !_commentsSelected;- _commentsOpened = true;- });+ void _toggleComments() {+ if (!_commentsSelected) widget.onUsage?.call(SharedAction.commentsOpen);+ setState(() {+ _commentsSelected = !_commentsSelected;+ _commentsOpened = true;+ });+ }void _selectViewer(bool viewer) => setState(() {_viewerChosen = true;@@ -418,10 +434,16 @@ class _SharedHarnessPanelState extends State<SharedHarnessPanel> {child: HarnessComments(updates: _commentUpdates,onSignIn: widget.onSignIn,- manage: (action, payload) => _connection.request(- 'observer_$action',- payload: {'agentId': widget.grant.agentId, ...payload},- ),+ manage: (action, payload) async {+ final answer = await _connection.request(+ 'observer_$action',+ payload: {'agentId': widget.grant.agentId, ...payload},+ );+ if (action == 'comment_post') {+ widget.onUsage?.call(SharedAction.commentPost);+ }+ return answer;+ },),);}diff --git a/desktop/test/hub_usage_contract_test.dart b/desktop/test/hub_usage_contract_test.dartnew file mode 100644index 000000000..465b5aec5--- /dev/null+++ b/desktop/test/hub_usage_contract_test.dart@@ -0,0 +1,48 @@+import 'dart:io';++import 'package:flutter_test/flutter_test.dart';+import 'package:harness/measurement/hub_usage.dart';++/// `hub_usage.dart` counts a shared link with names the backend must accept; a counter it does+/// not know fails the whole report. This reads the backend's own source.+void main() {+ late String contract;+ setUpAll(() {+ final file = File('../backend/src/lib/hubMetricsContract.ts');+ if (!file.existsSync()) {+ throw StateError(+ '${file.path} missing — run from desktop/ in the monorepo',+ );+ }+ contract = file.readAsStringSync();+ });++ List<String> list(String name) {+ final from = contract.indexOf('export const $name = [');+ if (from < 0) {+ throw StateError('"$name" is gone from hubMetricsContract.ts');+ }+ final body = contract.substring(from, contract.indexOf('] as const', from));+ return RegExp(r"'([a-z0-9_]+)'")+ .allMatches(body)+ .map((m) => m[1]!)+ .toList();+ }++ test('a shared link\'s counters are the backend\'s', () {+ expect(list('HUB_VIEW_PAGES'), contains('shared'));+ expect(list('HUB_READERS'), ['visitor', 'member']);+ expect(SharedOpen.values.map((o) => o.wire), list('HUB_SHARED_OPENS'));+ expect(+ SharedAction.values.map((a) => 'shared_${a.wire}'),+ list('HUB_ACTIONS').where((a) => a.startsWith('shared_')),+ );+ expect(list('HUB_DWELL'), ['under_10s', '10s_to_1m', 'over_1m']);+ expect(contract, contains('hub_shared_open_\${open}'));+ expect(contract, contains('hub_shared_dwell_\${bucket}'));+ expect(+ RegExp(r'HUB_REPORT_MAX_VALUE = (\d+)').firstMatch(contract)![1],+ '$hubReportMaxValue',+ );+ });+}diff --git a/desktop/test/hub_usage_test.dart b/desktop/test/hub_usage_test.dartnew file mode 100644index 000000000..efaae2f0a--- /dev/null+++ b/desktop/test/hub_usage_test.dart@@ -0,0 +1,137 @@+import 'dart:async';+import 'dart:convert';++import 'package:fake_async/fake_async.dart';+import 'package:flutter_test/flutter_test.dart';+import 'package:harness/measurement/hub_usage.dart';++void main() {+ late List<({Map<String, dynamic> report, String? authorization})> sent;+ late bool enabled;+ var now = DateTime.utc(2026, 10, 20, 9);++ HubUsage usage() => HubUsage(+ enabled: () => enabled,+ post: (body, authorization) => sent.add((+ report: jsonDecode(body) as Map<String, dynamic>,+ authorization: authorization,+ )),+ now: () => now,+ receipt: () => '0f8fad5b-d9cb-469f-a165-70867728950e',+ );++ setUp(() {+ sent = [];+ enabled = true;+ now = DateTime.utc(2026, 10, 20, 9);+ });++ test('adds up a day and sends it once, as the backend reads a report', () {+ fakeAsync((async) {+ final hub = usage();+ hub+ ..count(sharedViewMetric(member: false))+ ..count(SharedOpen.offline.metric)+ ..count(SharedOpen.offline.metric)+ ..flush()+ ..flush();+ expect(sent.single.report, {+ 'schemaVersion': 1,+ 'id': '0f8fad5b-d9cb-469f-a165-70867728950e',+ 'day': '2026-10-20',+ 'counters': {+ 'hub_view_shared_visitor': 1,+ 'hub_shared_open_offline': 2,+ },+ });+ expect(sent.single.authorization, isNull);+ });+ });++ test('sends on its own a minute after the first count', () {+ fakeAsync((async) {+ usage().count(SharedAction.getApp.metric);+ async.elapse(const Duration(seconds: 59));+ expect(sent, isEmpty);+ async.elapse(const Duration(seconds: 1));+ expect(sent.single.report['counters'], {'hub_shared_get_app': 1});+ });+ });++ test('a new UTC day sends the last one first', () {+ fakeAsync((async) {+ final hub = usage()..count(SharedAction.retry.metric);+ now = DateTime.utc(2026, 10, 21, 0, 1);+ hub+ ..count(SharedAction.retry.metric)+ ..flush();+ expect(sent.map((s) => s.report['day']), ['2026-10-20', '2026-10-21']);+ });+ });++ test(+ 'a member\'s sign-in rides along, and nothing leaves before it is read',+ () {+ fakeAsync((async) {+ final token = Completer<String?>();+ final hub = usage()..accessToken = (() => token.future);+ hub+ ..count(sharedViewMetric(member: true))+ ..flush();+ // Unread, a member could be one who turned sharing off: dropped, not sent as a visitor.+ expect(sent, isEmpty);+ token.complete('member');+ async.flushMicrotasks();+ hub+ ..count(sharedViewMetric(member: true))+ ..flush();+ expect(sent.single.authorization, 'Bearer member');+ hub.accessToken = null;+ async.flushMicrotasks();+ hub+ ..count(sharedViewMetric(member: false))+ ..flush();+ expect(sent.last.authorization, isNull);+ });+ },+ );++ test('counts nothing when switched off, and caps a counter', () {+ fakeAsync((async) {+ enabled = false;+ usage()+ ..count(SharedAction.commentPost.metric)+ ..flush();+ expect(sent, isEmpty);+ enabled = true;+ final hub = usage();+ for (var i = 0; i < hubReportMaxValue + 5; i++) {+ hub.count(SharedAction.viewerShown.metric);+ }+ hub.flush();+ expect(sent.single.report['counters'], {+ 'hub_shared_viewer_shown': hubReportMaxValue,+ });+ });+ });++ test('time in view is bucketed as the backend\'s and reported once', () {+ expect(+ sharedDwellMetric(const Duration(milliseconds: 9999)),+ 'hub_shared_dwell_under_10s',+ );+ expect(+ sharedDwellMetric(const Duration(seconds: 10)),+ 'hub_shared_dwell_10s_to_1m',+ );+ expect(+ sharedDwellMetric(const Duration(minutes: 1)),+ 'hub_shared_dwell_over_1m',+ );+ final shown = <Duration>[];+ VisibleTime(shown.add)+ ..finish()+ ..finish();+ expect(shown, hasLength(1));+ });+}diff --git a/desktop/test/shared_agent_page_test.dart b/desktop/test/shared_agent_page_test.dartindex 8361f0ddb..36b23fe6e 100644--- a/desktop/test/shared_agent_page_test.dart+++ b/desktop/test/shared_agent_page_test.dart@@ -8,6 +8,7 @@ import 'package:flutter/rendering.dart';import 'package:flutter_test/flutter_test.dart';import 'package:harness/auth/auth_session.dart';import 'package:harness/core/config.dart';+import 'package:harness/measurement/hub_usage.dart';import 'package:harness/sharing/shared_agent_location.dart';import 'package:harness/sharing/shared_agent_page.dart';import 'package:harness/sharing/shared_harness_panel.dart';@@ -64,6 +65,8 @@ void main() {Brightness brightness = Brightness.dark,Size size = const Size(800, 600),double scale = 1,+ String environment = 'stag',+ HubUsage? usage,}) async {tester.view.devicePixelRatio = 1;tester.view.physicalSize = size;@@ -85,7 +88,8 @@ void main() {child: SharedAgentPage(app: app,dio: dio,- location: SharedAgentLocation(id, pinnedKey, 'stag'),+ location: SharedAgentLocation(id, pinnedKey, environment),+ usage: usage,),),),@@ -228,4 +232,38 @@ void main() {);}}++ testWidgets(+ 'counts what a shared link showed once each, and never the link',+ (tester) async {+ final bodies = <String>[];+ final usage = HubUsage(+ enabled: () => true,+ post: (body, _) => bodies.add(body),+ );+ app.status = AppStatus.unauthenticated;+ await show(tester, pinnedKey: key, environment: 'prod', usage: usage);+ await tester.pump(const Duration(seconds: 10));+ await tester.pump(const Duration(milliseconds: 50));+ await tester.tap(find.widgetWithText(TextButton, 'Retry'));+ await tester.pump(const Duration(milliseconds: 50));+ usage.flush();+ expect(requests.length, greaterThanOrEqualTo(3));+ expect(jsonDecode(bodies.single)['counters'], {+ 'hub_view_shared_visitor': 1,+ 'hub_shared_open_offline': 1,+ 'hub_shared_retry': 1,+ });+ expect(bodies.single, isNot(contains(id)));+ expect(bodies.single, isNot(contains(key)));+ await tester.pumpWidget(const SizedBox());+ usage.flush();+ bodies.clear();+ // A staging link is the team's own.+ await show(tester, pinnedKey: key, usage: usage);+ usage.flush();+ expect(bodies, isEmpty);+ await tester.pumpWidget(const SizedBox());+ },+ );}diff --git a/docs/product-measurement.md b/docs/product-measurement.mdindex ecce84a35..efcf5498f 100644--- a/docs/product-measurement.md+++ b/docs/product-measurement.md@@ -25,7 +25,7 @@ automatically proven improvement. Changes still need review, tests and a deliber| Does Desktop's Add Phone card get used, and where else is Add Phone opened? | The card's flow (`ui_desktop_phone_offer_*`): started once it is on screen, `ok` by its Add Phone, `cancelled` by its ×, `unknown` when it went another way (Add Phone opened from elsewhere, a sign-out); every Add Phone opening by its way in (`ui_desktop_add_phone_<offer\|titlebar\|menu\|account\|machines\|command>`) | The card is offered once per computer, so its starts are computers, not people, and it has no 15-minute bound: started minus outcomes is an app closed with the card still up. An opening is the dialog shown, not a phone paired. `menu` includes a key bound to Harness ▸ Add Phone… on macOS; `command` is `> add phone` or a key bound to it elsewhere. The browser counts none. Vocabulary 3: counted from the start, but sent only once the local CLI has answered that it forwards them, so a Desktop on an older CLI sends none. || Is measurement losing coverage? | Updated collector installation-days, pruned queues, full observation maps, unmatched app starts | Loss signals warrant caution. No signal does not prove complete collection. || How many people use Harness, and do they come back? | People active / working / new per day and per app, and D1/D2/D3/D7 returns (backend rollup of 10-day pseudonymous marks) | Sharing accounts only, staff excluded; an app open across midnight counts on both days, so prefer working returns. Not available before `PRODUCT_USAGE_SUBJECT_KEY` is set. |-| What do people do on the Hub? | Page views by page and signed-out/signed-in reader, the first page of a tab's visit by where it came from (direct, search, social, internal, other; classified in the browser, the referrer is never sent), clicks and submits (search, sort, like, comment, share, fork, follow, report, sign-in prompt, publish), and how long a harness page stayed visible (under 10 s, 10 s–1 min, over 1 min) | Unlinked daily totals of views, entries, clicks and dwell buckets: not people, not a funnel. Public counts that can be fabricated; directional only. Browsers sending Global Privacy Control or Do Not Track, and signed-in readers who turned sharing off, are not counted. The website's server strips cookies and auth before forwarding. |+| What do people do on the Hub? | Page views by page and signed-out/signed-in reader, the first page of a tab's visit by where it came from (direct, search, social, internal, other; classified in the browser, the referrer is never sent), clicks and submits (search, sort, like, comment, share, fork, follow, report, sign-in prompt, publish), and how long a harness page stayed visible (under 10 s, 10 s–1 min, over 1 min). A shared link (`/s/:id`, the web app) counts the same way: the page drawn by reader, what it showed (live, owner offline, private, no access, failed), how long a live harness stayed visible, and its clicks (comments, comment posted, sign-in, retry, Download app, product page), plus once when its live viewer draws | Unlinked daily totals of views, entries, clicks and dwell buckets: not people, not a funnel. Public counts that can be fabricated; directional only. Browsers sending Global Privacy Control or Do Not Track, and signed-in readers who turned sharing off, are not counted. The website's server strips cookies and auth before forwarding. |Desktop setup and sign-in counts are enabled by default, with no onboarding checkbox. Desktop hasone “Share product usage data” switch in Experimental, with no separate Privacy page or feedback@@ -45,7 +45,7 @@ account preference is remembered for the next signed-out launch. With nowhere toSetup state already visible when sharing becomes enabled can start an observation; duration thenbegins at that observation, not necessarily at installation start. The web app's pre-sign-in setupcollection stays disabled because a browser request to the backend cannot guarantee omitted cookies.-The Hub's counters are the one web exception: the browser sends them to the website's own server,+The Hub's counters, shared links' included, are the one web exception: the browser sends them to the website's own server,which forwards them to the backend without cookies or auth, so the backend never sees a browsercredential (see the Hub endpoint below). These untrusted setup counts area separate population from signed-in app/daemon reports; older clients and opt-outs affect coverage. They@@ -78,7 +78,7 @@ excluded from release/platform margins so a return's release cannot be mistaken`health` in `usage:daily` reports consented setup/workspace/first-work/first-response milestones,coarse waits, request-source reconciliation, explicit composer-work D1/D7/D28 cohorts, weekly work-daybins, process health, and collector loss/rejection/late-report signals. `hub` reports the Hub's-daily views by page and reader, entries, clicks and dwell buckets, with fork clicks per harness view+daily views by page and reader, entries, clicks and dwell buckets, shared links' outcomes and dwell, with fork clicks per harness viewand sign-in prompt clicks per prompt shown as numerator, denominator and ratio; a day without Hubreports is null, not zero. These are visits and clicks, not people. Milestones describe localapp episodes, can cross UTC days, and do not establish a joined signup conversion rate. First-work@@ -205,14 +205,18 @@ fabrication; they are directional diagnostics, not trusted account acquisition m`POST /api/product-usage/hub` takes only the Hub vocabulary: no setup, app or daemon counter, andno Hub counter through those routes. It carries a random receipt, the UTC day (today or yesterday)-and at most 48 counters of 1–1,000 each, nothing else: no URL, page id, referrer, harness, creator,-search text or identifier. The website's server forwards it with cookies and auth stripped; the+and at most one of each Hub counter, 1–1,000 each, nothing else: no URL, page id, referrer, harness, creator,+search text, shared link, its key or identifier. The website's server forwards it with cookies and auth stripped; thebackend rejects auth/cookie headers, limits bodies to 4 KiB and admits at most 240 writes/minute andfour concurrent writes per server process, a budget of its own so Hub traffic cannot starve setupor sign-in measurement. The browser skips counting under Global Privacy Control or Do Not Track; thewebsite's server drops a signed-in reader's counts when that account's sharing is off. A view is apage drawn, once per navigation; an entry is the first Hub page of a tab's visit; dwell is counted-once per harness view. The same totals can come from one visitor or many.+once per harness view. A shared link counts each outcome at most once per page, so an offline owner's+automatic reconnects add nothing, and its dwell runs from the first live answer until the page goes;+it counts no entry. The web app (`desktop/lib/measurement/hub_usage.dart`) sends through the same+website route, without cookies, only in a release browser build and never for a staging link or+account. The same totals can come from one visitor or many.Both ingestion paths atomically add only UTC-day/metric totals plus an unlinked random retry receipt.Fast database write conflicts retry that complete transaction up to three times with short jitter,@@ -297,7 +301,8 @@ the historical reporting command will no longer be a current-usage source.Hub counters roll out backend first, then website: an older backend has no `/api/product-usage/hub`route and loses whatever the website sends it, and a backend that does not know a Hub counter-refuses the whole report, so a new Hub counter also ships backend first. Then check that a browser+refuses the whole report, so a new Hub counter also ships backend first (shared-link counters: backend,+then the web app's release). Then check that a browserwith Global Privacy Control and a signed-in reader with sharing off send nothing.People counts roll out in this order: deploy the backend without `PRODUCT_USAGE_SUBJECT_KEY` (no marksdiff --git a/docs/research/2026-10-19-hub-tracking/explore.png b/docs/research/2026-10-19-hub-tracking/explore.pngnew file mode 100644index 000000000..d349a9cacBinary files /dev/null and b/docs/research/2026-10-19-hub-tracking/explore.png differdiff --git a/docs/research/2026-10-19-hub-tracking/harness-phone.png b/docs/research/2026-10-19-hub-tracking/harness-phone.pngnew file mode 100644index 000000000..d7e8ec198Binary files /dev/null and b/docs/research/2026-10-19-hub-tracking/harness-phone.png differdiff --git a/docs/research/2026-10-19-hub-tracking/harness.png b/docs/research/2026-10-19-hub-tracking/harness.pngnew file mode 100644index 000000000..61b8343afBinary files /dev/null and b/docs/research/2026-10-19-hub-tracking/harness.png differdiff --git a/docs/research/2026-10-19-hub-tracking/index.html b/docs/research/2026-10-19-hub-tracking/index.htmlnew file mode 100644index 000000000..16343b807--- /dev/null+++ b/docs/research/2026-10-19-hub-tracking/index.html@@ -0,0 +1,349 @@+<!doctype html>+<html lang="en">+<head>+<meta charset="utf-8">+<meta name="viewport" content="width=device-width, initial-scale=1">+<title>Hub tracking · What readers do</title>+<style>+ :root {+ --page: #0f0f0e; --text: #f5f5f0; --muted: #9a9a90; --line: rgba(255,250,240,.10);+ --bg: #141413; --surface: #1c1c1a; --elev: #262624; --sub: #3a3a36;+ --amber: #ff9f0a; --green: #32d74b; --red: #ff453a; --blue: #0a84ff; --rose: #e879a0; --gold: #d4a574;+ --mono: ui-monospace, "SF Mono", Menlo, monospace;+ --sans: -apple-system, BlinkMacSystemFont, "SF Pro Display", "Inter", "Segoe UI", sans-serif;+ }+ * { box-sizing: border-box; }+ body { margin: 0; background: var(--page); color: var(--text); font: 16px/1.5 var(--sans); }+ main { max-width: 1180px; margin: 0 auto; padding: 40px 16px 96px; }+ h1 { font-size: 30px; margin: 0 0 6px; letter-spacing: -.01em; }+ h2 { font-size: 22px; margin: 64px 0 6px; }+ h3 { font-size: 16px; margin: 28px 0 8px; color: var(--muted); font-weight: 600; }+ p.lede { color: var(--muted); margin: 0 0 18px; max-width: 760px; }+ a { color: var(--gold); }+ code { font: 13px var(--mono); color: #e8e2d4; background: rgba(255,255,255,.06); padding: 1px 5px; border-radius: 5px; white-space: nowrap; }+ .principles { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 12px; margin: 22px 0 6px; }+ .principles div { background: var(--surface); border: 1px solid var(--line); border-radius: 12px; padding: 14px 16px; font-size: 15px; }+ .principles b { display: block; margin-bottom: 2px; }+ .note { color: var(--muted); font-size: 14px; margin: 10px 2px 0; max-width: 900px; }+ .note b { color: var(--text); font-weight: 600; }+ .grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; align-items: start; }+ .phone-row { display: grid; grid-template-columns: minmax(0, 340px) 1fr; gap: 26px; align-items: start; }+ @media (max-width: 860px) { .grid2, .phone-row { grid-template-columns: 1fr; } }+ .cap { margin: 8px 2px 0; font-size: 14px; color: var(--muted); }+ .cap b { color: var(--text); }++ /* A real screenshot in a browser frame; numbered pins sit just above the element they name. */+ .browser { border-radius: 12px; overflow: hidden; border: 1px solid rgba(255,255,255,.08); box-shadow: 0 20px 50px rgba(0,0,0,.55); background: #fff; }+ .browser .chrome { height: 34px; display: flex; align-items: center; gap: 8px; padding: 0 12px; background: #1b1b1a; border-bottom: 1px solid var(--line); }+ .dots { display: flex; gap: 6px; } .dots i { width: 10px; height: 10px; border-radius: 50%; display: block; }+ .dots i:nth-child(1) { background: #ff5f57; } .dots i:nth-child(2) { background: #febc2e; } .dots i:nth-child(3) { background: #28c840; }+ .url { flex: 1; margin-left: 10px; font: 12px var(--mono); color: var(--muted); background: #121211; border-radius: 6px; padding: 4px 10px; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }+ .shot { position: relative; line-height: 0; }+ .shot img { width: 100%; display: block; }+ .pin { position: absolute; transform: translate(-50%, -135%); min-width: 22px; height: 22px; padding: 0 6px; border-radius: 11px; background: var(--amber); color: #1a1205;+ font: 700 12px/22px var(--sans); text-align: center; box-shadow: 0 0 0 2px rgba(15,15,14,.85), 0 4px 10px rgba(0,0,0,.35); font-style: normal; }+ .pin::after { content: ''; position: absolute; left: 50%; bottom: -5px; margin-left: -4px; border: 4px solid transparent; border-top-color: var(--amber); border-bottom: 0; }+ /* Beside its element instead of above it, where above would cover a heading. */+ .pin.right { transform: translate(10px, -50%); }+ .pin.right::after { left: -5px; bottom: auto; top: 50%; margin: -4px 0 0; border: 4px solid transparent; border-right-color: var(--amber); border-left: 0; }+ .pin.view { background: var(--blue); color: #fff; } .pin.view::after { border-top-color: var(--blue); }+ .pin.dwell { background: var(--rose); color: #22060f; } .pin.dwell::after { border-top-color: var(--rose); }+ .pin.none { background: var(--sub); color: var(--text); } .pin.none::after { border-top-color: var(--sub); }++ .legend { list-style: none; margin: 14px 0 0; padding: 0; display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 8px 18px; }+ .legend li { display: grid; grid-template-columns: 30px 1fr; gap: 10px; align-items: start; font-size: 14px; color: #d8d8cf; background: var(--surface); border: 1px solid var(--line); border-radius: 10px; padding: 10px 12px; }+ .legend li > i { position: static; transform: none; }+ .legend li > i::after { display: none; }+ .legend .m { display: block; margin-top: 3px; }+ .legend small { display: block; color: var(--muted); margin-top: 3px; font-size: 13px; }++ /* The path a count takes. */+ .flow { display: grid; grid-template-columns: repeat(5, 1fr); gap: 0; margin: 22px 0 6px; }+ .flow .step { background: var(--surface); border: 1px solid var(--line); border-radius: 12px; padding: 14px; font-size: 14px; position: relative; margin-right: 22px; }+ .flow .step:last-child { margin-right: 0; }+ .flow .step:not(:last-child)::after { content: '→'; position: absolute; right: -19px; top: 50%; transform: translateY(-50%); color: var(--amber); font-size: 16px; }+ .flow b { display: block; margin-bottom: 4px; }+ .flow .step > span { color: var(--muted); display: block; }+ .flow .drop { color: var(--red); }+ @media (max-width: 960px) { .flow { grid-template-columns: 1fr; gap: 22px; } .flow .step { margin-right: 0; }+ .flow .step:not(:last-child)::after { content: '↓'; right: auto; left: 50%; top: auto; bottom: -21px; transform: translateX(-50%); } }++ table { width: 100%; border-collapse: collapse; font-size: 14px; margin-top: 12px; }+ th, td { text-align: left; vertical-align: top; padding: 9px 10px; border-bottom: 1px solid var(--line); }+ th { color: var(--muted); font-weight: 600; font-size: 12px; text-transform: uppercase; letter-spacing: .06em; }+ td.k { white-space: nowrap; }+ tr.group td { color: var(--amber); font-weight: 600; font-size: 12px; text-transform: uppercase; letter-spacing: .1em; padding-top: 22px; border-bottom: 0; }+ .table-wrap { overflow-x: auto; }+ .tag { display: inline-block; font-size: 11px; font-weight: 600; padding: 1px 7px; border-radius: 10px; border: 1px solid var(--line); color: var(--muted); }+ .tag.red { color: var(--red); border-color: rgba(255,69,58,.35); } .tag.amber { color: var(--amber); border-color: rgba(255,159,10,.35); } .tag.green { color: var(--green); border-color: rgba(50,215,75,.35); }+ pre { font: 13px/1.6 var(--mono); background: var(--surface); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; overflow-x: auto; color: #dcd8cc; }+ .toc { display: flex; flex-wrap: wrap; gap: 8px; margin: 18px 0 0; }+ .toc a { font-size: 13px; color: var(--muted); text-decoration: none; border: 1px solid var(--line); border-radius: 20px; padding: 4px 12px; }+ .toc a:hover { color: var(--text); border-color: var(--sub); }+</style>+</head>+<body>+<main>+ <h1>Hub tracking: what readers do, and what we change next</h1>+ <p class="lede">Every counter the Hub sends, pinned on the real pages at harness.autonomous.ai, then how to read the totals and which questions they answer. Counting has been live since <b>v1.2.86_backend</b> and <b>v1.3.56_web</b> on 2026-10-19, 03:36 UTC. The screenshots are production, taken the same day with counting switched off in the test browser.</p>+ <nav class="toc">+ <a href="#path">Where a count goes</a><a href="#explore">1 · Explore</a><a href="#harness">2 · A harness</a><a href="#phone">2b · On a phone</a>+ <a href="#publish">3 · Publish & notifications</a><a href="#shared">4 · A shared link</a><a href="#all">Every counter</a><a href="#read">Reading it</a><a href="#questions">Questions</a><a href="#limits">Limits</a><a href="#optimize">To optimize</a><a href="#first">First reading</a><a href="#decided">Decided</a>+ </nav>++ <div class="principles">+ <div><b>Daily totals only</b>A fixed list of 65 counters, added up per UTC day. No click trail, no per-person history.</div>+ <div><b>Visitors too, cookies never</b>The browser sends with <code>credentials: 'omit'</code>; the website's server forwards without cookie or sign-in.</div>+ <div><b>Opt-outs are absent</b>Global Privacy Control, Do Not Track, a member who turned sharing off, staging accounts and <code>next dev</code> send nothing.</div>+ <div><b>Visits and clicks, not people</b>One person can be many views. Steps are not linked, so totals are not a funnel.</div>+ </div>++ <h2 id="path">Where a count goes</h2>+ <div class="flow">+ <div class="step"><b>The tab</b><span>Counts in memory (<code>countHub</code>). Sent every 60 s and when the tab hides.</span></div>+ <div class="step"><b>/api/hub-usage</b><span>Website server. A member's token is used only to read their sharing choice: <span class="drop">off or unreadable → dropped</span>.</span></div>+ <div class="step"><b>/api/product-usage/hub</b><span>Backend. Refuses any cookie or auth. Strict vocabulary, random receipt, 240 writes/min.</span></div>+ <div class="step"><b>Daily totals</b><span>The same receipt + atomic increment store as setup counts; today or yesterday only.</span></div>+ <div class="step"><b>usage:daily → hub</b><span>Per day: views, entries, actions, dwell, two ratios with numerator and denominator.</span></div>+ </div>+ <p class="note"><b>Code:</b> <code>website/src/lib/community/hubMeasure.ts</code> (collector), <code>website/src/app/api/hub-usage/route.ts</code> (forwarder), <code>desktop/lib/measurement/hub_usage.dart</code> (the web app's collector, for shared links), <code>backend/src/lib/hubMetricsContract.ts</code> (the 65 names), <code>backend/src/analytics/dailyHubUsage.ts</code> (report). The website's copy of the names is checked against the backend's by <code>hubMetrics.spec.ts</code>, the web app's by <code>hub_usage_contract_test.dart</code>.</p>++ <h2 id="explore">1. Explore: what a visitor sees first</h2>+ <p class="lede">The front door. A visitor gets the heading, the desktop app and Sign in; then filters and cards.</p>+ <div class="browser"><div class="chrome"><div class="dots"><i></i><i></i><i></i></div><div class="url">harness.autonomous.ai/hub</div></div>+ <div class="shot"><img src="explore.png" alt="Explore at 1440 by 900, signed out">+ <i class="pin view" style="left:37%;top:16.9%">1</i>+ <i class="pin" style="left:15.1%;top:29.3%">2</i>+ <i class="pin" style="left:24.8%;top:29.3%">3</i>+ <i class="pin" style="left:79.6%;top:4.4%">4</i>+ <i class="pin" style="left:17.5%;top:36.4%">5</i>+ <i class="pin" style="left:83.9%;top:36.4%">6</i>+ <i class="pin" style="left:21.5%;top:62.2%">7</i>+ <i class="pin" style="left:8.9%;top:87.9%">8</i>+ <i class="pin none" style="left:12%;top:87.9%">–</i>+ <i class="pin none" style="left:84.3%;top:4.4%">–</i>+ <i class="pin none" style="left:90%;top:4.4%">–</i>+ </div>+ </div>+ <ol class="legend">+ <li><i class="pin view">1</i><div><b>The page drawn</b><code class="m">hub_view_feed_visitor</code> · <code>hub_view_feed_member</code><small>Once per navigation, as soon as it is known who reads. The first Hub page of a tab's visit also counts <code>hub_entry_direct|search|social|internal|other</code>.</small></div></li>+ <li><i class="pin">2</i><div><b>Get the Harness desktop app</b><code class="m">hub_get_app</code><small>Visitors only. Leads to /desktop.</small></div></li>+ <li><i class="pin">3</i><div><b>Sign in (intro)</b><code class="m">hub_sign_in_prompt_shown</code> · <code>hub_sign_in_prompt_click</code><small>Shown is counted once it is known to be a visitor. Shared with every other sign-in prompt (comments, likes, publish).</small></div></li>+ <li><i class="pin">4</i><div><b>Search</b><code class="m">hub_feed_search</code><small>Once each time the settled (debounced) term changes to something non-empty; not the term a link opened with.</small></div></li>+ <li><i class="pin">5</i><div><b>A category</b><code class="m">hub_feed_category</code><small>Any chip but All.</small></div></li>+ <li><i class="pin">6</i><div><b>Order</b><code class="m">hub_feed_sort_newest|trending|popular</code><small>Every click, including the one already chosen.</small></div></li>+ <li><i class="pin">7</i><div><b>Open a card</b><code class="m">hub_card_open</code><small>The cover or title. The next page then counts its own view.</small></div></li>+ <li><i class="pin">8</i><div><b>Like from a card</b><code class="m">hub_like</code><small>Counted when the like is sent (a member, or a browser holding a sign-in). A visitor gets the sign-in toast instead, which counts as a prompt shown.</small></div></li>+ <li><i class="pin none">–</i><div><b>Not counted</b><small>The card's comments and forks links (they arrive as a harness view), the header's Publish (arrives as a publish view) and Sign in, and scrolling. <code>hub_feed_more</code> counts each further page, by scroll or button, on every feed (Following, Yours, a creator, a harness's forks).</small></div></li>+ </ol>++ <h2 id="harness">2. A harness: the page that should lead to a fork</h2>+ <p class="lede">Share is open so its rows show. Fork on a computer hands the project to the desktop app; "Need the app?" appears under it after the click.</p>+ <div class="browser"><div class="chrome"><div class="dots"><i></i><i></i><i></i></div><div class="url">harness.autonomous.ai/hub/pac-man-neon-maze-chase-fb726d28</div></div>+ <div class="shot"><img src="harness.png" alt="A harness page at 1440 by 900 with the Share menu open">+ <i class="pin view" style="left:32%;top:18.6%">1</i>+ <i class="pin" style="left:61.9%;top:20.1%">2</i>+ <i class="pin" style="left:65.8%;top:20.1%">3</i>+ <i class="pin" style="left:70.4%;top:20.1%">4</i>+ <i class="pin" style="left:75.9%;top:20.1%">5</i>+ <i class="pin" style="left:62.6%;top:25.9%">6</i>+ <i class="pin" style="left:62.6%;top:31.3%">7</i>+ <i class="pin" style="left:62.6%;top:35.5%">7</i>+ <i class="pin" style="left:62.6%;top:39.8%">7</i>+ <i class="pin" style="left:62.6%;top:45.2%">8</i>+ <i class="pin" style="left:81.9%;top:20.1%">9</i>+ <i class="pin" style="left:88.6%;top:20.1%">10</i>+ <i class="pin right" style="left:17.2%;top:22.3%">11</i>+ <i class="pin dwell" style="left:37.2%;top:65%">12</i>+ </div>+ </div>+ <ol class="legend">+ <li><i class="pin view">1</i><div><b>The page drawn</b><code class="m">hub_view_harness_visitor|member</code><small>Also the entry, when a shared link is the first page of the visit.</small></div></li>+ <li><i class="pin">2</i><div><b>Like</b><code class="m">hub_like</code><small>Members, once the reader is known (the button waits). Unlike counts too.</small></div></li>+ <li><i class="pin">3</i><div><b>Comments</b><code class="m">hub_comments_open</code> · <code>hub_comment_post</code><small>Opening the panel by its button (a <code>?comments=1</code> link opens it without counting); a comment or reply that was saved.</small></div></li>+ <li><i class="pin">4</i><div><b>Files</b><code class="m">hub_files_open</code></div></li>+ <li><i class="pin">5</i><div><b>Share</b><code class="m">hub_share_open</code><small>By click, or ↓ on the button.</small></div></li>+ <li><i class="pin">6</i><div><b>Copy link</b><code class="m">hub_share_copy</code></div></li>+ <li><i class="pin">7</i><div><b>X · Facebook · LinkedIn</b><code class="m">hub_share_x|facebook|linkedin</code><small>Opens the network's share page in a new tab. Whether the post was made is not known.</small></div></li>+ <li><i class="pin">8</i><div><b>More options…</b><code class="m">hub_share_sheet</code><small>Only where the browser has a share sheet.</small></div></li>+ <li><i class="pin">9</i><div><b>Report</b><code class="m">hub_report</code><small>A submitted report, of the harness or of a comment.</small></div></li>+ <li><i class="pin">10</i><div><b>Fork</b><code class="m">hub_fork</code> · <code>hub_fork_need_app</code><small>The click that opens the desktop app; then the "Need the app?" link under it. Whether the app opened is not known.</small></div></li>+ <li><i class="pin">11</i><div><b>Follow</b><code class="m">hub_follow</code><small>Follow or unfollow, here and on a creator's page.</small></div></li>+ <li><i class="pin dwell">12</i><div><b>Time in view</b><code class="m">hub_harness_dwell_under_10s|10s_to_1m|over_1m</code><small>Visible time only, once per view, as it is left (another page or the tab closing). Full screen, below this frame, counts <code>hub_fullscreen</code> on entering.</small></div></li>+ </ol>++ <h2 id="phone">2b. On a phone: Fork goes to the fork page</h2>+ <div class="phone-row">+ <div class="browser"><div class="chrome"><div class="dots"><i></i><i></i><i></i></div><div class="url">…/pac-man-neon-maze-chase-fb726d28</div></div>+ <div class="shot"><img src="harness-phone.png" alt="The same harness at 390 by 844 on a phone">+ <i class="pin" style="left:10.1%;top:33.5%">2</i>+ <i class="pin" style="left:23.5%;top:33.5%">3</i>+ <i class="pin" style="left:35.1%;top:33.5%">4</i>+ <i class="pin" style="left:44.8%;top:33.5%">5</i>+ <i class="pin" style="left:54.6%;top:33.5%">9</i>+ <i class="pin" style="left:83.5%;top:33.5%">10</i>+ <i class="pin right" style="left:37.6%;top:26.4%">11</i>+ <i class="pin dwell" style="left:49.2%;top:71.9%">12</i>+ </div>+ </div>+ <div>+ <p class="note" style="margin-top:0"><b>Same counters, one difference.</b> On a touch screen with no fine pointer, Fork is a link to <code>/hub/…/fork</code>: it still counts <code>hub_fork</code>, and the fork page counts <code>hub_view_fork_*</code>. There, "Copy link for your computer" replaces "Open in Harness" and is not counted again.</p>+ <p class="note"><b>What this cannot tell apart:</b> a computer's Fork from a phone's. No counter is split by device. The nearest signal is <code>hub_view_fork</code> against <code>hub_fork</code>: on a computer Fork rarely opens the fork page (only through "Need the app?"), so a fork-page view is mostly a phone's tap or a missing app.</p>+ <p class="note"><b>Labels hide under 480 px:</b> Files, Share and Report show icons only; their counters are unchanged.</p>+ </div>+ </div>++ <h2 id="publish">3. Publish and notifications</h2>+ <div class="grid2">+ <div>+ <div class="browser"><div class="chrome"><div class="dots"><i></i><i></i><i></i></div><div class="url">harness.autonomous.ai/hub/publish</div></div>+ <div class="shot"><img src="publish.png" alt="Publish, signed out">+ <i class="pin view" style="left:47%;top:15.7%">1</i>+ <i class="pin" style="left:14.6%;top:31%">2</i>+ </div>+ </div>+ <p class="cap"><b>1</b> <code>hub_view_publish_*</code>. <b>2</b> the sign-in prompt, shown and clicked. Below the fold, Publish or Save changes counts <code>hub_publish_started</code>, then <code>hub_publish_ok</code> or <code>hub_publish_failed</code>.</p>+ </div>+ <div>+ <div class="browser"><div class="chrome"><div class="dots"><i></i><i></i><i></i></div><div class="url">harness.autonomous.ai/hub/notifications</div></div>+ <div class="shot"><img src="notifications.png" alt="Notifications, signed in, sample rows">+ <i class="pin view" style="left:20%;top:15.3%">1</i>+ <i class="pin none" style="left:30%;top:27%">–</i>+ </div>+ </div>+ <p class="cap"><b>1</b> <code>hub_view_notifications_*</code>. A row is not counted: it arrives as a harness view. (Rows are sample data drawn in the test browser.)</p>+ </div>+ </div>+ <p class="note">A creator's page counts <code>hub_view_creator_*</code>, its Follow <code>hub_follow</code>, and its cards like Explore's.</p>++ <h2 id="shared">4. A shared link: someone's live harness</h2>+ <p class="lede"><code>harness.autonomous.ai/s/<id>#key=…</code> is the web app (Flutter), not the Hub's pages, but it counts the same way and through the same <code>/api/hub-usage</code>. The link, its key, the harness and its owner are never sent. A staging link (<code>?env=stag</code>) or account, a debug build and the desktop app send nothing.</p>+ <ol class="legend">+ <li><i class="pin view">1</i><div><b>The page drawn</b><code class="m">hub_view_shared_visitor|member</code><small>Once per page, as soon as the app knows whether the reader is signed in.</small></div></li>+ <li><i class="pin view">2</i><div><b>What the link showed</b><code class="m">hub_shared_open_live|offline|private|no_access|failed</code><small>Each at most once per page: an offline owner's reconnects every 10 s add nothing, and offline then live counts both. <code>private</code>: a private link before sign-in. <code>no_access</code>: not invited, or the link stopped. <code>failed</code>: an incomplete link, a changed owner identity, or no connection.</small></div></li>+ <li><i class="pin">3</i><div><b>A live viewer drew</b><code class="m">hub_shared_viewer_shown</code><small>Once, on its first frame: the harness shows a picture (Blender, slides, a site), not only a terminal.</small></div></li>+ <li><i class="pin">4</i><div><b>Comments</b><code class="m">hub_shared_comments_open · hub_shared_comment_post</code><small>The panel opened by its button; a comment saved.</small></div></li>+ <li><i class="pin">5</i><div><b>Sign in</b><code class="m">hub_shared_sign_in_click</code><small>On a private link, or under the comments.</small></div></li>+ <li><i class="pin">6</i><div><b>Retry</b><code class="m">hub_shared_retry</code><small>After offline, a failure, or a dropped connection.</small></div></li>+ <li><i class="pin">7</i><div><b>Leaving for the product</b><code class="m">hub_shared_get_app · hub_shared_product_page</code><small>Download app; the Harness mark (the product page, in a new tab).</small></div></li>+ <li><i class="pin dwell">8</i><div><b>Time in view</b><code class="m">hub_shared_dwell_under_10s|10s_to_1m|over_1m</code><small>From the first live answer until the page goes, hidden time not counted; once per page.</small></div></li>+ </ol>+ <p class="note">No entry is counted here: where shared links are pasted (chat apps, mail) mostly sends no referrer, and its visits would blur the Hub's own <code>hub_entry_*</code>.</p>++ <h2 id="all">Every counter</h2>+ <p class="lede">The 65 names the backend accepts (<code>HUB_METRICS</code>). Nothing else can be sent: an unknown name refuses the report.</p>+ <div class="table-wrap"><table>+ <thead><tr><th>Counter</th><th>When it counts</th><th>Where</th></tr></thead>+ <tbody>+ <tr class="group"><td colspan="3">Views · 14</td></tr>+ <tr><td class="k"><code>hub_view_{page}_{visitor|member}</code></td><td>A page drawn, once per navigation, after the reader is known. Pages: <code>feed</code> (Explore, Following, Yours), <code>creator</code>, <code>harness</code>, <code>publish</code>, <code>notifications</code>, <code>fork</code>, <code>shared</code> (a shared link, section 4).</td><td><code>useHubView</code></td></tr>+ <tr class="group"><td colspan="3">Entry · 5</td></tr>+ <tr><td class="k"><code>hub_entry_{direct|search|social|internal|other}</code></td><td>The first Hub page of a tab's visit, classed from the referrer's host in the browser. Search: Google, Bing, DuckDuckGo and similar. Social: X, Facebook, LinkedIn, Reddit, Hacker News, Threads, Bluesky, YouTube, Discord, Telegram, Instagram. Internal: another page of harness.autonomous.ai.</td><td><code>countHubEntry</code></td></tr>+ <tr class="group"><td colspan="3">Feeds · 7</td></tr>+ <tr><td class="k"><code>hub_feed_search</code></td><td>A settled search term, each change.</td><td>Feed</td></tr>+ <tr><td class="k"><code>hub_feed_category</code></td><td>A category chip other than All.</td><td>Feed</td></tr>+ <tr><td class="k"><code>hub_feed_sort_{newest|trending|popular}</code></td><td>An order clicked.</td><td>Feed</td></tr>+ <tr><td class="k"><code>hub_feed_more</code></td><td>Each further page, by scroll or button, on any feed.</td><td><code>useFeed</code></td></tr>+ <tr><td class="k"><code>hub_card_open</code></td><td>A card's cover or title.</td><td>FeedCard</td></tr>+ <tr class="group"><td colspan="3">A harness · 15</td></tr>+ <tr><td class="k"><code>hub_like</code></td><td>A like or unlike sent, from a card or the page.</td><td>useFeed, useHarnessDetail</td></tr>+ <tr><td class="k"><code>hub_comments_open</code> · <code>hub_files_open</code></td><td>The panel opened by its button.</td><td>Detail</td></tr>+ <tr><td class="k"><code>hub_comment_post</code></td><td>A comment or reply saved.</td><td>useHarnessDetail</td></tr>+ <tr><td class="k"><code>hub_fullscreen</code></td><td>Entering full screen.</td><td>Viewer</td></tr>+ <tr><td class="k"><code>hub_share_open</code></td><td>The Share menu opened.</td><td>ShareMenu</td></tr>+ <tr><td class="k"><code>hub_share_{copy|x|facebook|linkedin|sheet}</code></td><td>A Share row chosen.</td><td>ShareMenu</td></tr>+ <tr><td class="k"><code>hub_fork</code></td><td>Fork: the desktop handoff on a computer, the fork-page link on a phone.</td><td>ForkButton</td></tr>+ <tr><td class="k"><code>hub_fork_need_app</code></td><td>"Need the app?" after Fork.</td><td>ForkButton</td></tr>+ <tr><td class="k"><code>hub_follow</code></td><td>Follow or unfollow (harness page, creator page).</td><td>useHarnessDetail, useCreator</td></tr>+ <tr><td class="k"><code>hub_report</code></td><td>A report submitted (harness or comment).</td><td>useHarnessDetail</td></tr>+ <tr class="group"><td colspan="3">Accounts and publishing · 6</td></tr>+ <tr><td class="k"><code>hub_sign_in_prompt_shown</code></td><td>Any sign-in prompt drawn: comments, the like toast, publish, notifications, Following, and Explore's intro for a visitor.</td><td>SignIn, ExploreIntro</td></tr>+ <tr><td class="k"><code>hub_sign_in_prompt_click</code></td><td>Its Sign in link.</td><td>SignIn, ExploreIntro</td></tr>+ <tr><td class="k"><code>hub_get_app</code></td><td>Explore's "Get the Harness desktop app".</td><td>ExploreIntro</td></tr>+ <tr><td class="k"><code>hub_publish_started|ok|failed</code></td><td>Publish or Save changes submitted, and how it ended.</td><td>publish/page</td></tr>+ <tr class="group"><td colspan="3">Time on a harness · 3</td></tr>+ <tr><td class="k"><code>hub_harness_dwell_{under_10s|10s_to_1m|over_1m}</code></td><td>Visible time of one harness view, as it is left.</td><td><code>useHarnessDwell</code></td></tr>+ <tr class="group"><td colspan="3">A shared link · 15</td></tr>+ <tr><td class="k"><code>hub_shared_open_{live|offline|private|no_access|failed}</code></td><td>What the link showed, each once per page.</td><td>SharedAgentPage</td></tr>+ <tr><td class="k"><code>hub_shared_viewer_shown</code></td><td>Its live viewer's first frame.</td><td>SharedHarnessPanel</td></tr>+ <tr><td class="k"><code>hub_shared_comments_open</code> · <code>hub_shared_comment_post</code></td><td>Comments opened by the button; a comment saved.</td><td>SharedHarnessPanel</td></tr>+ <tr><td class="k"><code>hub_shared_sign_in_click</code> · <code>hub_shared_retry</code></td><td>Sign in (private link, comments); Retry (page or panel).</td><td>SharedAgentPage, SharedHarnessPanel</td></tr>+ <tr><td class="k"><code>hub_shared_get_app</code> · <code>hub_shared_product_page</code></td><td>Download app; the Harness mark.</td><td>SharedAgentPage</td></tr>+ <tr><td class="k"><code>hub_shared_dwell_{under_10s|10s_to_1m|over_1m}</code></td><td>Visible time from the first live answer until the page goes.</td><td><code>VisibleTime</code></td></tr>+ </tbody>+ </table></div>++ <h2 id="read">Reading it</h2>+ <pre>cd backend+DATABASE_URL=<read-only> npm run usage:daily -- 14 # keep output in .harness/usage/, never commit it</pre>+ <p class="note">The <code>hub</code> section gives a <b>status</b> for the window (<code>collected</code> or <code>not collected</code>), then per UTC day (a day with no Hub report is <code>null</code>, not zero): <b>views</b> by page and reader, <b>entries</b>, every <b>action</b>, <b>dwell</b>, and two ratios kept as numerator / denominator / ratio: <code>forkClicksPerHarnessView</code> and <code>signInClicksPerPromptShown</code>. Today is partial; compare complete seven-day windows.</p>+ <p class="note"><b>First complete window:</b> 2026-10-20 to 2026-10-26. 2026-10-19 is the release day and partial, and a handful of its Explore views came from this review's Lighthouse and performance runs before counting was switched off in the test browser.</p>++ <h2 id="questions">The questions, and what would change</h2>+ <p class="lede">Each one names its numbers before we look, so the decision is not picked after the fact (see the daily review in <code>docs/product-measurement.md</code>).</p>+ <div class="table-wrap"><table>+ <thead><tr><th>Question</th><th>Numbers</th><th>If so, change</th></tr></thead>+ <tbody>+ <tr><td>Does a visitor find something to open?</td><td><code>hub_card_open</code> ÷ <code>hub_view_feed_visitor</code></td><td>Low: a featured row or starters above the fold; Trending as the visitors' default order.</td></tr>+ <tr><td>Is Trending or Popular wanted over Newest?</td><td><code>hub_feed_sort_trending</code> + <code>_popular</code> against views; card opens per view before and after a default change</td><td>Most sessions that sort leave Newest: make that the default.</td></tr>+ <tr><td>Does the intro bring people in?</td><td><code>hub_get_app</code>, <code>hub_sign_in_prompt_click</code> ÷ <code>hub_sign_in_prompt_shown</code></td><td>Few clicks: shorten the intro, or show it only on a first visit (<code>hub_entry_*</code> says how many are first visits).</td></tr>+ <tr><td>Does a harness page lead to a fork?</td><td><code>forkClicksPerHarnessView</code>; <code>hub_fork_need_app</code> ÷ <code>hub_fork</code></td><td>Many "Need the app?": the handoff fails for most; put the install path before Fork.</td></tr>+ <tr><td>Do phone readers get anywhere?</td><td><code>hub_view_fork_*</code> against <code>hub_fork</code></td><td>Fork pages viewed but no later fork: offer "send to my computer" (email the link) instead of copy.</td></tr>+ <tr><td>Do people stay?</td><td>Dwell buckets, against <code>hub_view_harness</code></td><td>Mostly under 10 s: the output loads slowly or the page does not say what it is; look at output load and the first screen.</td></tr>+ <tr><td>How do people share, and does it bring readers?</td><td><code>hub_share_*</code> by row; <code>hub_entry_social</code> over time</td><td>Copy dominates: keep it first. Social entries flat: preview images and titles (link previews were fixed in v1.3.58_web).</td></tr>+ <tr><td>Do readers talk?</td><td><code>hub_comments_open</code>, <code>hub_comment_post</code>, prompts shown in comments</td><td>Opens but no posts: a prompt or example question in the empty panel.</td></tr>+ <tr><td>Does a shared link reach a live harness?</td><td><code>hub_shared_open_live</code> against <code>hub_view_shared_*</code>; <code>_offline</code>, <code>_private</code>, <code>_no_access</code>, <code>_failed</code></td><td>Mostly offline: show the owner's last output while their machine is away. Many private before sign-in, few <code>hub_shared_sign_in_click</code>: say who invited the reader and why to sign in.</td></tr>+ <tr><td>Does a shared link bring people to Harness?</td><td><code>hub_shared_get_app</code> + <code>hub_shared_product_page</code> ÷ <code>hub_view_shared_visitor</code>; <code>hub_shared_dwell_*</code></td><td>Long dwell, few clicks: a "make one like this" call to action beside the live harness.</td></tr>+ <tr><td>Does search work?</td><td><code>hub_feed_search</code> followed by <code>hub_card_open</code> (same days)</td><td>Searches with few opens: search creators too (the placeholder promises it), fuzzy matching.</td></tr>+ </tbody>+ </table></div>++ <h2 id="limits">Limits</h2>+ <p class="note" style="font-size:15px;line-height:1.7">+ <b>Not people:</b> a reader who reloads counts two views; one who opens ten harnesses, ten. Entry is once per tab visit (session storage), so it is the closest to visits.<br>+ <b>Not a funnel:</b> a fork cannot be traced back to the card that led to it. Ratios compare totals on the same days.<br>+ <b>Absent readers:</b> GPC and Do Not Track browsers, members with sharing off, staging accounts, ad and script blockers that stop <code>/api/hub-usage</code>.<br>+ <b>Lost counts:</b> a tab that is killed before it hides, a failed send (never retried), and anything over the backend's 240 reports a minute per process, which is about 200 tabs open at once. <code>TODO(BE)</code>: past that, add reports up on the website's server and send one a minute.<br>+ <b>Fabricable:</b> the endpoint is public. Treat a sudden jump on one counter as suspect until it shows on others.<br>+ <b>No device split:</b> phone and computer are only told apart through the fork page (2b).</p>++ <h2 id="optimize">To optimize, found while making this page</h2>+ <div class="table-wrap"><table>+ <thead><tr><th></th><th>What</th><th>Evidence</th><th>Fix</th></tr></thead>+ <tbody>+ <tr><td><span class="tag red">decide</span></td><td>A Google Ads tag runs on every Hub page</td><td>Requests to <code>googleads.g.doubleclick.net</code>, <code>google.com/rmkt/collect</code> and <code>/ccm/collect</code> for <code>AW-943247754</code>, served through the first-party path <code>/kaxv/</code> (Cloudflare's Google tag gateway, not in the repo); third-party cookies <code>test_cookie</code>, <code>IDE</code>. Lighthouse Best Practices: 77.</td><td>Whoever owns Cloudflare and ads decides: leave it off <code>/hub</code>, or say so in <code>product-measurement.md</code>, which now promises no cookies. It also ignores GPC.</td></tr>+ <tr><td><span class="tag amber">P1</span></td><td>Covers weigh too much</td><td>Starter covers are PNGs of ~600 KB (<code>ribbon-lamp</code> 615 KB, <code>two-futures</code> 606 KB); a publication's cover is 1775 px wide where a phone shows ~380 px. About 424 KB wasted on a phone's first screen. LCP is still 1.6 s on throttled 4G.</td><td>Resize to 1200 px and serve WebP, with a 1200 px PNG kept for link previews.</td></tr>+ <tr><td><span class="tag amber">P1</span></td><td>Card labels hide their text from screen readers</td><td>Lighthouse <code>label-content-name-mismatch</code>, 67 nodes: the card link, Like and Comments use <code>aria-label</code>, which replaces the description and counts.</td><td><code>aria-labelledby</code> the title, and keep the counts visible to the name.</td></tr>+ <tr><td><span class="tag">P2</span></td><td>Publish does not line up with the header</td><td>Its content starts at 157 px against the header's 115 px at 1440 px (screenshot 3); the fork page too.</td><td>Use the header's width (<code>.wrap</code>) as Notifications does.</td></tr>+ <tr><td><span class="tag">P2</span></td><td>The footer floats mid-page on short pages</td><td>Notifications with three rows: footer at 551 px of 900.</td><td>Keep the footer at the bottom of the viewport on short pages.</td></tr>+ <tr><td><span class="tag">P2</span></td><td>From the earlier review</td><td colspan="2">A comment notification does not jump to its comment; no way to find creators; "All harnesses" loses filters and scroll; headings vary from 25 to 38 px; a few links still use the raw id (reports, fork notifications, download); unused CSS (<code>.steps</code>).</td></tr>+ </tbody>+ </table></div>++ <h2 id="first">First reading · 2026-10-19</h2>+ <p class="lede">Production totals from 03:36 UTC (release) to 08:42 UTC, about five hours. Read straight from the daily totals (<code>hub_*</code> rows), since <code>npm run usage:daily</code> currently fails on production (see below).</p>+ <div class="table-wrap"><table>+ <thead><tr><th>Counter</th><th>Total</th><th>Reading</th></tr></thead>+ <tbody>+ <tr><td class="k"><code>hub_view_feed_visitor</code></td><td>8</td><td>About 3 are this review's own audits (Lighthouse, a network listing, a performance trace), run before counting was switched off in the test browser. About 5 are real.</td></tr>+ <tr><td class="k"><code>hub_view_harness_visitor</code></td><td>5</td><td>All visitors; no member view yet.</td></tr>+ <tr><td class="k"><code>hub_entry_direct</code></td><td>7</td><td>Every entry was direct, none from search or social yet. Includes the audits'.</td></tr>+ <tr><td class="k"><code>hub_sign_in_prompt_shown</code></td><td>11</td><td>Mostly Explore's intro, shown on each visitor view.</td></tr>+ <tr><td class="k"><code>hub_get_app</code></td><td>1</td><td>One click on "Get the Harness desktop app".</td></tr>+ <tr><td class="k"><code>hub_harness_dwell_under_10s</code></td><td>5</td><td>Every harness view left in under ten seconds.</td></tr>+ <tr><td class="k">everything else</td><td>0</td><td>No card open, like, comment, share, fork, search or sort.</td></tr>+ </tbody>+ </table></div>+ <p class="note"><b>Too few to decide anything.</b> The one signal to watch: all five harness views ended under ten seconds with no action. If that holds over the first full week, start from "Do people stay?" above: how fast the output appears, and whether the first screen says what the harness is and what Fork does.<br>+ <b>To fix:</b> <code>npm run usage:daily</code> exits with "Could not read aggregate product usage" against production. The Hub rows read fine with a direct query, so the failure is elsewhere in the report and its catch hides the cause.<br>+ <b>Next readings:</b> daily from 2026-10-20, the first clean day; the first complete week (2026-10-20 to 10-26) on 2026-10-27.</p>++ <h2 id="decided">Decided</h2>+ <p class="note" style="font-size:15px;line-height:1.7">+ <b>Collection:</b> visitors are counted (decided 2026-10-19), with no cookie, identifier, URL or content, through the website's server; the one web exception to signed-out collection, recorded in <code>docs/product-measurement.md</code>.<br>+ <b>Released:</b> <code>v1.2.86_backend</code> (endpoint and report) and <code>v1.3.56_web</code> (collector and the review's fixes) on 2026-10-19; <code>v1.3.58_web</code> fixed link previews and removed Open Harness from the signed-in bar. Checked in production: the backend reports <code>v1.2.86_backend</code>, the endpoint refuses credentials (400), <code>/api/hub-usage</code> answers POST only, <code>robots.txt</code> allows covers.<br>+ <b>Next review:</b> 2026-10-27, on the first complete week (2026-10-20 to 10-26). Then pick one question above, write its hypothesis and guardrails, change one thing, and compare equal windows.<br>+ <b>Still open:</b> the Google Ads tag; cover weight; card labels.</p>+</main>+</body>+</html>diff --git a/docs/research/2026-10-19-hub-tracking/notifications.png b/docs/research/2026-10-19-hub-tracking/notifications.pngnew file mode 100644index 000000000..4028c7fbfBinary files /dev/null and b/docs/research/2026-10-19-hub-tracking/notifications.png differdiff --git a/docs/research/2026-10-19-hub-tracking/publish.png b/docs/research/2026-10-19-hub-tracking/publish.pngnew file mode 100644index 000000000..f401e9b22Binary files /dev/null and b/docs/research/2026-10-19-hub-tracking/publish.png differdiff --git a/scripts/record-ci-validation.py b/scripts/record-ci-validation.pyindex 31dce5955..1c62eee01 100644--- a/scripts/record-ci-validation.py+++ b/scripts/record-ci-validation.py@@ -37,10 +37,11 @@ SOURCE_INPUTS = {".gitattributes", ".gitignore", ".gitmodules", "Makefile"),# VM tests also read CLI protocol definitions, shared layout fixtures,# daemon metadata and store catalog/artwork, including docs/images posters,- # the Hub's publication rules that desktop/lib/community/hub_contract.dart mirrors, and the+ # the Hub's publication rules that desktop/lib/community/hub_contract.dart mirrors, its usage+ # counters that desktop/lib/measurement/hub_usage.dart sends (test/hub_usage_contract_test.dart), and the# phone's P2P/E2EE sources the web's copies are checked against (test/p2p/mobile_parity_test.dart)."desktop": (".github/", "scripts/", "desktop/", "cli/", "tests/", "daemons/", "store/", "docs/images/",- "mobile/pubspec.lock", "backend/src/lib/communityContract.ts",+ "mobile/pubspec.lock", "backend/src/lib/communityContract.ts", "backend/src/lib/hubMetricsContract.ts","mobile/lib/p2p/terminal_p2p_plugin.dart", "mobile/lib/p2p/terminal_p2p_link.dart", "mobile/lib/p2p/terminal_p2p_policy.dart","mobile/lib/ws/terminal_transport_plugin.dart", "mobile/lib/ws/relay_codec.dart", "mobile/lib/e2ee/relay_session_crypto.dart",".gitattributes", ".gitignore", ".gitmodules", "Makefile"),diff --git a/website/src/lib/community/hubMetrics.spec.ts b/website/src/lib/community/hubMetrics.spec.tsindex e3c3655bb..c7c7afe73 100644--- a/website/src/lib/community/hubMetrics.spec.ts+++ b/website/src/lib/community/hubMetrics.spec.ts@@ -1,7 +1,7 @@// @vitest-environment nodeimport { describe, expect, it } from 'vitest';import * as backend from '../../../../backend/src/lib/hubMetricsContract';-import { dwellBucket, entrySource, hubActions, hubDwell, hubEntrySources, hubReportMaxValue, hubViewPages } from './hubMetrics';+import { dwellBucket, entrySource, hubActions, hubDwell, hubEntrySources, hubReportMaxValue, hubSharedOpens, hubViewPages } from './hubMetrics';describe('the Hub usage counters', () => {it('are the ones the backend accepts', () => {@@ -9,6 +9,7 @@ describe('the Hub usage counters', () => {expect([...hubEntrySources]).toEqual([...backend.HUB_ENTRY_SOURCES]);expect([...hubDwell]).toEqual([...backend.HUB_DWELL]);expect([...hubActions]).toEqual([...backend.HUB_ACTIONS]);+ expect([...hubSharedOpens]).toEqual([...backend.HUB_SHARED_OPENS]);expect(hubReportMaxValue).toBe(backend.HUB_REPORT_MAX_VALUE);});it('class a visit by its referrer’s host alone', () => {diff --git a/website/src/lib/community/hubMetrics.ts b/website/src/lib/community/hubMetrics.tsindex 984e13077..0685f274a 100644--- a/website/src/lib/community/hubMetrics.ts+++ b/website/src/lib/community/hubMetrics.ts@@ -2,21 +2,26 @@* The Hub's usage counters, as the backend accepts them (`backend/src/lib/hubMetricsContract.ts`;* `hubMetrics.spec.ts` fails when the two drift). Fixed daily totals only: no identifiers, URLs or content.*/-export const hubViewPages = ['feed', 'harness', 'creator', 'publish', 'notifications', 'fork'] as const;+export const hubViewPages = ['feed', 'harness', 'creator', 'publish', 'notifications', 'fork', 'shared'] as const;export const hubEntrySources = ['direct', 'search', 'social', 'internal', 'other'] as const;export const hubDwell = ['under_10s', '10s_to_1m', 'over_1m'] as const;+/** A shared link (`/s/:id`) is the web app's page; it counts `shared` views, opens and actions through the same route. */+export const hubSharedOpens = ['live', 'offline', 'private', 'no_access', 'failed'] as const;export const hubActions = ['feed_search', 'feed_category', 'feed_sort_newest', 'feed_sort_popular', 'feed_sort_trending', 'feed_more', 'card_open','like', 'comment_post', 'comments_open', 'files_open', 'fullscreen','share_open', 'share_copy', 'share_x', 'share_facebook', 'share_linkedin', 'share_sheet','fork', 'fork_need_app', 'follow', 'report','sign_in_prompt_shown', 'sign_in_prompt_click', 'get_app', 'publish_started', 'publish_ok', 'publish_failed',+ 'shared_viewer_shown', 'shared_comments_open', 'shared_comment_post', 'shared_sign_in_click', 'shared_retry',+ 'shared_get_app', 'shared_product_page',] as const;export type HubViewPage = typeof hubViewPages[number];export type HubEntrySource = typeof hubEntrySources[number];export type HubAction = typeof hubActions[number];-export type HubMetric = `hub_view_${HubViewPage}_${'visitor' | 'member'}` | `hub_entry_${HubEntrySource}` | `hub_${HubAction}` | `hub_harness_dwell_${typeof hubDwell[number]}`;+export type HubMetric = `hub_view_${HubViewPage}_${'visitor' | 'member'}` | `hub_entry_${HubEntrySource}` | `hub_${HubAction}`+ | `hub_${'harness' | 'shared'}_dwell_${typeof hubDwell[number]}` | `hub_shared_open_${typeof hubSharedOpens[number]}`;export const hubReportMaxValue = 1000;