Skip to content

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.

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.yml
index 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.dart
diff --git a/backend/README.md b/backend/README.md
index 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, D2
installation returns, and voluntary task outcomes. Native signed-out setup is a separate explicit
session opt-in at `POST /api/product-usage/setup`; it rejects credentials and arbitrary fields and
has 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's
server 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, and
diff --git a/backend/src/analytics/dailyHubUsage.test.ts b/backend/src/analytics/dailyHubUsage.test.ts
index 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 si
expect(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.ts
index 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_000
type 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.ts
index 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 const
export 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 const
export 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.length
export const HUB_REPORT_MAX_VALUE = 1000
diff --git a/desktop/lib/measurement/hub_usage.dart b/desktop/lib/measurement/hub_usage.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
index 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;
@override
State<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;
@override
void 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());
}
@override
void 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.dart
index 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;
@override
State<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.dart
new file mode 100644
index 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.dart
new file mode 100644
index 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.dart
index 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.md
index 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 has
one “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 to
Setup state already visible when sharing becomes enabled can start an observation; duration then
begins at that observation, not necessarily at installation start. The web app's pre-sign-in setup
collection 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 browser
credential (see the Hub endpoint below). These untrusted setup counts are
a 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-day
bins, 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 view
and sign-in prompt clicks per prompt shown as numerator, denominator and ratio; a day without Hub
reports is null, not zero. These are visits and clicks, not people. Milestones describe local
app 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, and
no 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; the
backend rejects auth/cookie headers, limits bodies to 4 KiB and admits at most 240 writes/minute and
four concurrent writes per server process, a budget of its own so Hub traffic cannot starve setup
or sign-in measurement. The browser skips counting under Global Privacy Control or Do Not Track; the
website's server drops a signed-in reader's counts when that account's sharing is off. A view is a
page 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 browser
with 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 marks
diff --git a/docs/research/2026-10-19-hub-tracking/explore.png b/docs/research/2026-10-19-hub-tracking/explore.png
new file mode 100644
index 000000000..d349a9cac
Binary files /dev/null and b/docs/research/2026-10-19-hub-tracking/explore.png differ
diff --git a/docs/research/2026-10-19-hub-tracking/harness-phone.png b/docs/research/2026-10-19-hub-tracking/harness-phone.png
new file mode 100644
index 000000000..d7e8ec198
Binary files /dev/null and b/docs/research/2026-10-19-hub-tracking/harness-phone.png differ
diff --git a/docs/research/2026-10-19-hub-tracking/harness.png b/docs/research/2026-10-19-hub-tracking/harness.png
new file mode 100644
index 000000000..61b8343af
Binary files /dev/null and b/docs/research/2026-10-19-hub-tracking/harness.png differ
diff --git a/docs/research/2026-10-19-hub-tracking/index.html b/docs/research/2026-10-19-hub-tracking/index.html
new file mode 100644
index 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 &amp; 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/&lt;id&gt;#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=&lt;read-only&gt; 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.png
new file mode 100644
index 000000000..4028c7fbf
Binary files /dev/null and b/docs/research/2026-10-19-hub-tracking/notifications.png differ
diff --git a/docs/research/2026-10-19-hub-tracking/publish.png b/docs/research/2026-10-19-hub-tracking/publish.png
new file mode 100644
index 000000000..f401e9b22
Binary files /dev/null and b/docs/research/2026-10-19-hub-tracking/publish.png differ
diff --git a/scripts/record-ci-validation.py b/scripts/record-ci-validation.py
index 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.ts
index 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 node
import { 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.ts
index 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;