@timber-js/app 0.2.0-alpha.227 → 0.2.0-alpha.229

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/agent-skill.md +9 -0
  2. package/dist/_chunks/{actions-B1xSIv32.js → actions-DHum77eH.js} +3 -3
  3. package/dist/_chunks/{actions-B1xSIv32.js.map → actions-DHum77eH.js.map} +1 -1
  4. package/dist/_chunks/{cache-api-DsSXA4Sp.js → cache-api-BZJNt01a.js} +4 -4
  5. package/dist/_chunks/{cache-api-DsSXA4Sp.js.map → cache-api-BZJNt01a.js.map} +1 -1
  6. package/dist/_chunks/{chains-Dgm3PrMe.js → chains-D-RRc7CM.js} +2 -2
  7. package/dist/_chunks/{chains-Dgm3PrMe.js.map → chains-D-RRc7CM.js.map} +1 -1
  8. package/dist/_chunks/chains-KblEfYzm.js +1 -0
  9. package/dist/_chunks/{classify--_kINHQV.js → classify-_W0RWa5w.js} +2 -2
  10. package/dist/_chunks/{classify--_kINHQV.js.map → classify-_W0RWa5w.js.map} +1 -1
  11. package/dist/_chunks/{cli-check-B33yhAPa.js → cli-check-B-JZkpBD.js} +3 -3
  12. package/dist/_chunks/{cli-check-B33yhAPa.js.map → cli-check-B-JZkpBD.js.map} +1 -1
  13. package/dist/_chunks/{cli-schema-sync-DIPurq7X.js → cli-schema-sync-CAllbqRB.js} +2 -2
  14. package/dist/_chunks/{cli-schema-sync-DIPurq7X.js.map → cli-schema-sync-CAllbqRB.js.map} +1 -1
  15. package/dist/_chunks/{cli-schema-sync-uq72EZmD.js → cli-schema-sync-y_8ijmzO.js} +1 -1
  16. package/dist/_chunks/{client-dep-entries-CP7AkMCM.js → client-dep-entries-C9hv-3k9.js} +2 -2
  17. package/dist/_chunks/{client-dep-entries-CP7AkMCM.js.map → client-dep-entries-C9hv-3k9.js.map} +1 -1
  18. package/dist/_chunks/{convention-lint-hZwz5wd4.js → convention-lint-CrDKERHg.js} +4 -13
  19. package/dist/_chunks/convention-lint-CrDKERHg.js.map +1 -0
  20. package/dist/_chunks/dev-server-L8biS7Az.js +1 -0
  21. package/dist/_chunks/{dev-server-B7o4As0l.js → dev-server-Rq659RR1.js} +8 -2
  22. package/dist/_chunks/dev-server-Rq659RR1.js.map +1 -0
  23. package/dist/_chunks/{build-manifest-Y4jl7nwU.js → dev-span-_NzMX-au.js} +25 -2
  24. package/dist/_chunks/dev-span-_NzMX-au.js.map +1 -0
  25. package/dist/_chunks/{error-boundary-D3YyVVuP.js → error-boundary-OHK1mI99.js} +3 -3
  26. package/dist/_chunks/{error-boundary-D3YyVVuP.js.map → error-boundary-OHK1mI99.js.map} +1 -1
  27. package/dist/_chunks/{flight-source-node-0Tp6evlz.js → flight-source-node-BGanuoSS.js} +2 -2
  28. package/dist/_chunks/{flight-source-node-0Tp6evlz.js.map → flight-source-node-BGanuoSS.js.map} +1 -1
  29. package/dist/_chunks/{global-context-DbxNWeBP.js → global-context-CFSSysdJ.js} +32 -2
  30. package/dist/_chunks/global-context-CFSSysdJ.js.map +1 -0
  31. package/dist/_chunks/{json-lossy-check-DVkLUlfC.js → json-lossy-check-BXM45k8p.js} +2 -2
  32. package/dist/_chunks/{json-lossy-check-DVkLUlfC.js.map → json-lossy-check-BXM45k8p.js.map} +1 -1
  33. package/dist/_chunks/{live-graph-BcVjQ1Te.js → live-graph-C7-yA8W9.js} +4 -4
  34. package/dist/_chunks/{live-graph-BcVjQ1Te.js.map → live-graph-C7-yA8W9.js.map} +1 -1
  35. package/dist/_chunks/{logger-CWk44DLp.js → logger-YtMSKfft.js} +103 -60
  36. package/dist/_chunks/logger-YtMSKfft.js.map +1 -0
  37. package/dist/_chunks/navigation-root-CoGHIMiE.js +239 -0
  38. package/dist/_chunks/navigation-root-CoGHIMiE.js.map +1 -0
  39. package/dist/_chunks/{node-response-B9aviPDa.js → node-response-D3hXWb8y.js} +2 -2
  40. package/dist/_chunks/{node-response-B9aviPDa.js.map → node-response-D3hXWb8y.js.map} +1 -1
  41. package/dist/_chunks/{poison-scan-DJYxZc_7.js → poison-scan-CRSP06Es.js} +2 -2
  42. package/dist/_chunks/{poison-scan-DJYxZc_7.js.map → poison-scan-CRSP06Es.js.map} +1 -1
  43. package/dist/_chunks/route-methods-Dk2kZc0n.js +36 -0
  44. package/dist/_chunks/route-methods-Dk2kZc0n.js.map +1 -0
  45. package/dist/_chunks/{scanner-CJC-ScJU.js → scanner-BNQ4qnLX.js} +2 -2
  46. package/dist/_chunks/{scanner-CJC-ScJU.js.map → scanner-BNQ4qnLX.js.map} +1 -1
  47. package/dist/_chunks/segment-context-GAyTjjtS.js +33 -0
  48. package/dist/_chunks/segment-context-GAyTjjtS.js.map +1 -0
  49. package/dist/_chunks/{sizeof-DG4W40lv.js → sizeof-Cmx6Fs-Y.js} +2 -2
  50. package/dist/_chunks/{sizeof-DG4W40lv.js.map → sizeof-Cmx6Fs-Y.js.map} +1 -1
  51. package/dist/_chunks/{status-page-marker-C8POawuF.js → status-page-marker-U6B1aFMb.js} +3 -32
  52. package/dist/_chunks/status-page-marker-U6B1aFMb.js.map +1 -0
  53. package/dist/_chunks/{walkers-DIE203ir.js → walkers-D_QHR_nf.js} +3 -3
  54. package/dist/_chunks/{walkers-DIE203ir.js.map → walkers-D_QHR_nf.js.map} +1 -1
  55. package/dist/adapters/cloudflare-kv-cache.js +1 -1
  56. package/dist/analyze/crawl-entry.js +3 -3
  57. package/dist/analyze/graph-command.js +2 -2
  58. package/dist/cache/index.js +2 -2
  59. package/dist/cache/stores/memory.js +1 -1
  60. package/dist/cli.js +3 -3
  61. package/dist/client/browser-entry/hmr.d.ts +7 -1
  62. package/dist/client/browser-entry/hmr.d.ts.map +1 -1
  63. package/dist/client/dev-pill/index.d.ts +32 -0
  64. package/dist/client/dev-pill/index.d.ts.map +1 -0
  65. package/dist/client/dev-pill/store.d.ts +96 -0
  66. package/dist/client/dev-pill/store.d.ts.map +1 -0
  67. package/dist/client/dev-pill/view.d.ts +9 -0
  68. package/dist/client/dev-pill/view.d.ts.map +1 -0
  69. package/dist/client/error-boundary.js +1 -1
  70. package/dist/client/index.d.ts +1 -0
  71. package/dist/client/index.d.ts.map +1 -1
  72. package/dist/client/index.js +3 -3
  73. package/dist/client/internal.js +16 -7
  74. package/dist/client/internal.js.map +1 -1
  75. package/dist/client/navigation-context.d.ts +20 -0
  76. package/dist/client/navigation-context.d.ts.map +1 -1
  77. package/dist/client/router-lifecycle.d.ts +4 -1
  78. package/dist/client/router-lifecycle.d.ts.map +1 -1
  79. package/dist/client/use-pending-navigation.d.ts +33 -9
  80. package/dist/client/use-pending-navigation.d.ts.map +1 -1
  81. package/dist/config-types.d.ts +10 -0
  82. package/dist/config-types.d.ts.map +1 -1
  83. package/dist/config-validation.d.ts.map +1 -1
  84. package/dist/dev-tools/await-span.d.ts +17 -0
  85. package/dist/dev-tools/await-span.d.ts.map +1 -0
  86. package/dist/dev-tools/instrumentation.d.ts.map +1 -1
  87. package/dist/dev-tools/logger.d.ts.map +1 -1
  88. package/dist/dev-tools/logs.d.ts.map +1 -1
  89. package/dist/dev-tools/span-sink.d.ts +42 -0
  90. package/dist/dev-tools/span-sink.d.ts.map +1 -0
  91. package/dist/index.d.ts.map +1 -1
  92. package/dist/index.js +282 -9
  93. package/dist/index.js.map +1 -1
  94. package/dist/plugins/dev-await.d.ts +40 -0
  95. package/dist/plugins/dev-await.d.ts.map +1 -0
  96. package/dist/plugins/entries.d.ts.map +1 -1
  97. package/dist/routing/convention-lint.d.ts.map +1 -1
  98. package/dist/routing/index.js +2 -2
  99. package/dist/server/action-handler.d.ts.map +1 -1
  100. package/dist/server/csrf.d.ts +1 -1
  101. package/dist/server/csrf.d.ts.map +1 -1
  102. package/dist/server/index.js +2 -2
  103. package/dist/server/internal.d.ts +2 -1
  104. package/dist/server/internal.d.ts.map +1 -1
  105. package/dist/server/internal.js +26 -27
  106. package/dist/server/internal.js.map +1 -1
  107. package/dist/server/pipeline.d.ts +8 -0
  108. package/dist/server/pipeline.d.ts.map +1 -1
  109. package/dist/server/route-handler.d.ts +1 -2
  110. package/dist/server/route-handler.d.ts.map +1 -1
  111. package/dist/server/route-methods.d.ts +23 -0
  112. package/dist/server/route-methods.d.ts.map +1 -0
  113. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  114. package/dist/server/slot-resolver.d.ts.map +1 -1
  115. package/dist/server/tracing.d.ts +18 -8
  116. package/dist/server/tracing.d.ts.map +1 -1
  117. package/dist/shared/dev-span.d.ts +97 -0
  118. package/dist/shared/dev-span.d.ts.map +1 -0
  119. package/docs/api/31-api-client.mdx +27 -1
  120. package/docs/api/34-api-config.mdx +21 -1
  121. package/docs/learn/09-streaming.mdx +7 -1
  122. package/package.json +3 -3
  123. package/src/client/browser-entry/hmr.ts +13 -1
  124. package/src/client/browser-entry/index.ts +4 -1
  125. package/src/client/dev-pill/index.ts +128 -0
  126. package/src/client/dev-pill/store.ts +231 -0
  127. package/src/client/dev-pill/view.ts +278 -0
  128. package/src/client/index.ts +1 -0
  129. package/src/client/navigation-context.ts +5 -2
  130. package/src/client/router-lifecycle.ts +23 -3
  131. package/src/client/use-pending-navigation.ts +93 -14
  132. package/src/config-types.ts +10 -0
  133. package/src/config-validation.ts +10 -0
  134. package/src/dev-tools/await-span.ts +40 -0
  135. package/src/dev-tools/instrumentation.ts +20 -0
  136. package/src/dev-tools/logger.ts +3 -37
  137. package/src/dev-tools/logs.ts +10 -1
  138. package/src/dev-tools/span-sink.ts +132 -0
  139. package/src/index.ts +2 -0
  140. package/src/plugins/dev-await.ts +268 -0
  141. package/src/plugins/entries.ts +2 -0
  142. package/src/routing/convention-lint.ts +1 -3
  143. package/src/server/action-handler.ts +5 -0
  144. package/src/server/csrf.ts +11 -3
  145. package/src/server/internal.ts +2 -1
  146. package/src/server/pipeline.ts +14 -0
  147. package/src/server/route-handler.ts +8 -19
  148. package/src/server/route-methods.ts +37 -0
  149. package/src/server/rsc-entry/index.ts +7 -1
  150. package/src/server/slot-resolver.ts +45 -5
  151. package/src/server/tracing.ts +124 -90
  152. package/src/shared/dev-span.ts +182 -0
  153. package/dist/_chunks/build-manifest-Y4jl7nwU.js.map +0 -1
  154. package/dist/_chunks/chains-CwOr3Myj.js +0 -1
  155. package/dist/_chunks/convention-lint-hZwz5wd4.js.map +0 -1
  156. package/dist/_chunks/dev-server-B7o4As0l.js.map +0 -1
  157. package/dist/_chunks/dev-server-hZzmbMvK.js +0 -1
  158. package/dist/_chunks/global-context-DbxNWeBP.js.map +0 -1
  159. package/dist/_chunks/logger-CWk44DLp.js.map +0 -1
  160. package/dist/_chunks/navigation-root-M3B2ZrdO.js +0 -122
  161. package/dist/_chunks/navigation-root-M3B2ZrdO.js.map +0 -1
  162. package/dist/_chunks/segment-context-CYiGTi3K.js +0 -131
  163. package/dist/_chunks/segment-context-CYiGTi3K.js.map +0 -1
  164. package/dist/_chunks/status-page-marker-C8POawuF.js.map +0 -1
@@ -0,0 +1,231 @@
1
+ /**
2
+ * Dev request pill — the state behind the pill: spans by trace, the requests
3
+ * this tab made, and which one the pill shows.
4
+ *
5
+ * Pure: no DOM, no HMR, no fetch. `index.ts` feeds it; `view.ts` renders it.
6
+ * See design/50-dev-request-pill.md §"Correlation".
7
+ */
8
+
9
+ import { ROOT_SPAN_NAME, type DevSpanPayload } from '../../shared/dev-span.ts';
10
+ import { RSC_KEY_PARAM } from '../../shared/rsc-cache-key.ts';
11
+
12
+ export type DevRequestKind = 'document' | 'navigation' | 'action' | 'fetch';
13
+
14
+ /** A request this tab made whose response named its trace. */
15
+ export interface DevRequest {
16
+ traceId: string;
17
+ kind: DevRequestKind;
18
+ method: string;
19
+ /** Pathname of the request URL, for display. */
20
+ path: string;
21
+ /**
22
+ * Which page the request is for: pathname and search, without the
23
+ * payload's `_rsc` cache key. The router tells pages apart by both
24
+ * (`router-url.ts`), so `/search?page=1` and `/search?page=2` must not
25
+ * match. Built with `pageKey()` on both sides so encodings agree.
26
+ */
27
+ page: string;
28
+ }
29
+
30
+ export interface TraceSummary {
31
+ fetches: number;
32
+ awaits: number;
33
+ /**
34
+ * First span start to last span end. Null until the root span has
35
+ * arrived: before that, more spans are certainly still coming. (The root
36
+ * ends when the pipeline returns its Response; Suspense work streamed
37
+ * after it still counts, which is why this is not the root's duration.)
38
+ */
39
+ durationMs: number | null;
40
+ slow: boolean;
41
+ error: boolean;
42
+ }
43
+
44
+ export interface WaterfallRow {
45
+ span: DevSpanPayload;
46
+ depth: number;
47
+ /** Milliseconds from the trace's start. */
48
+ offsetMs: number;
49
+ durationMs: number;
50
+ }
51
+
52
+ /**
53
+ * The page a URL addresses, comparable across the address bar and a payload
54
+ * URL: `_rsc` dropped, and the query re-serialized by `URLSearchParams` on
55
+ * both sides, so `%20` and `+` spellings agree.
56
+ */
57
+ export function pageKey(url: URL): string {
58
+ const params = new URLSearchParams(url.search);
59
+ params.delete(RSC_KEY_PARAM);
60
+ const search = params.toString();
61
+ return search ? `${url.pathname}?${search}` : url.pathname;
62
+ }
63
+
64
+ /** Traces whose spans are kept. Spans for traces no request claims are dropped first. */
65
+ const MAX_TRACES = 64;
66
+ /** Requests listed in the panel. */
67
+ const MAX_REQUESTS = 20;
68
+
69
+ export class DevPillStore {
70
+ private spansByTrace = new Map<string, DevSpanPayload[]>();
71
+ private requestList: DevRequest[] = [];
72
+ private selectedId: string | null = null;
73
+ private listeners = new Set<() => void>();
74
+
75
+ /**
76
+ * @param slowMs `dev.slowPhaseMs` from timber.config.ts, the threshold the
77
+ * terminal tree highlights at (design/17-logging.md §"Slow Phase Highlighting").
78
+ */
79
+ constructor(
80
+ private readonly currentPage: () => string,
81
+ readonly slowMs = 200
82
+ ) {}
83
+
84
+ /** Newest first. */
85
+ get requests(): readonly DevRequest[] {
86
+ return this.requestList;
87
+ }
88
+
89
+ get selected(): DevRequest | null {
90
+ return this.requestList.find((r) => r.traceId === this.selectedId) ?? null;
91
+ }
92
+
93
+ subscribe(listener: () => void): () => void {
94
+ this.listeners.add(listener);
95
+ return () => this.listeners.delete(listener);
96
+ }
97
+
98
+ /**
99
+ * Record a finished span. It may arrive before the response that names
100
+ * its trace (proxy and middleware end before the headers go out), so
101
+ * spans are kept for unclaimed traces too.
102
+ */
103
+ addSpan(span: DevSpanPayload): void {
104
+ let spans = this.spansByTrace.get(span.traceId);
105
+ if (!spans) {
106
+ this.evictTraces();
107
+ spans = [];
108
+ this.spansByTrace.set(span.traceId, spans);
109
+ }
110
+ // Replay and the live broadcast can both deliver a span.
111
+ if (spans.some((s) => s.spanId === span.spanId)) return;
112
+ spans.push(span);
113
+ if (this.requestList.some((r) => r.traceId === span.traceId)) this.emit();
114
+ }
115
+
116
+ /**
117
+ * Record a request whose response named its trace. Selected when it is
118
+ * the page itself (the document, or a payload for the path on screen —
119
+ * a refresh) or an action. A navigation's payload arrives before the
120
+ * address bar moves, so it is selected by `navigationCommitted()`.
121
+ */
122
+ addRequest(request: DevRequest): void {
123
+ if (this.requestList.some((r) => r.traceId === request.traceId)) return;
124
+ this.requestList.unshift(request);
125
+ const isPage =
126
+ request.kind === 'document' ||
127
+ (request.kind === 'navigation' && request.page === this.currentPage());
128
+ if (isPage || request.kind === 'action') this.selectedId = request.traceId;
129
+ this.trimRequests();
130
+ this.emit();
131
+ }
132
+
133
+ /** The address bar moved: show the newest payload fetched for the new page. */
134
+ navigationCommitted(): void {
135
+ const page = this.currentPage();
136
+ const match = this.requestList.find(
137
+ (r) => (r.kind === 'navigation' || r.kind === 'document') && r.page === page
138
+ );
139
+ if (match && match.traceId !== this.selectedId) {
140
+ this.selectedId = match.traceId;
141
+ this.emit();
142
+ }
143
+ }
144
+
145
+ select(traceId: string): void {
146
+ this.selectedId = traceId;
147
+ this.emit();
148
+ }
149
+
150
+ spans(traceId: string): readonly DevSpanPayload[] {
151
+ return this.spansByTrace.get(traceId) ?? [];
152
+ }
153
+
154
+ summary(traceId: string): TraceSummary {
155
+ const spans = this.spans(traceId);
156
+ const root = spans.find((s) => s.name === ROOT_SPAN_NAME);
157
+ const status = root?.attributes['http.response.status_code'];
158
+ return {
159
+ fetches: spans.filter((s) => s.name === 'timber.fetch').length,
160
+ awaits: spans.filter((s) => s.name === 'timber.await').length,
161
+ durationMs: root
162
+ ? Math.max(...spans.map((s) => s.endMs)) - Math.min(...spans.map((s) => s.startMs))
163
+ : null,
164
+ slow: spans.some((s) => s !== root && s.endMs - s.startMs > this.slowMs),
165
+ error: spans.some((s) => s.error) || (typeof status === 'number' && status >= 500),
166
+ };
167
+ }
168
+
169
+ /** Spans in tree order (parent before children, siblings by start). */
170
+ waterfall(traceId: string): WaterfallRow[] {
171
+ const spans = this.spans(traceId);
172
+ if (spans.length === 0) return [];
173
+ const ids = new Set(spans.map((s) => s.spanId));
174
+ const children = new Map<string | undefined, DevSpanPayload[]>();
175
+ for (const span of spans) {
176
+ // A span whose parent isn't here (the root still open, or a parent
177
+ // outside this trace's spans) sits at the top level.
178
+ const parent =
179
+ span.parentSpanId && ids.has(span.parentSpanId) ? span.parentSpanId : undefined;
180
+ const siblings = children.get(parent) ?? [];
181
+ siblings.push(span);
182
+ children.set(parent, siblings);
183
+ }
184
+ const origin = Math.min(...spans.map((s) => s.startMs));
185
+ const rows: WaterfallRow[] = [];
186
+ const visit = (parent: string | undefined, depth: number) => {
187
+ const siblings = (children.get(parent) ?? []).sort((a, b) => a.startMs - b.startMs);
188
+ for (const span of siblings) {
189
+ rows.push({
190
+ span,
191
+ depth,
192
+ offsetMs: span.startMs - origin,
193
+ durationMs: span.endMs - span.startMs,
194
+ });
195
+ visit(span.spanId, depth + 1);
196
+ }
197
+ };
198
+ visit(undefined, 0);
199
+ return rows;
200
+ }
201
+
202
+ /**
203
+ * Keep the newest requests, and always the selected one: a page that polls
204
+ * a route handler would otherwise push its own trace out, leaving the pill
205
+ * with nothing selected and no picker to get it back.
206
+ */
207
+ private trimRequests(): void {
208
+ while (this.requestList.length > MAX_REQUESTS) {
209
+ // Newest first, so the oldest unselected request is the last one that
210
+ // isn't selected.
211
+ let oldest = this.requestList.length - 1;
212
+ if (this.requestList[oldest]?.traceId === this.selectedId) oldest--;
213
+ this.requestList.splice(oldest, 1);
214
+ }
215
+ }
216
+
217
+ private evictTraces(): void {
218
+ while (this.spansByTrace.size >= MAX_TRACES) {
219
+ const claimed = new Set(this.requestList.map((r) => r.traceId));
220
+ const victim =
221
+ [...this.spansByTrace.keys()].find((id) => !claimed.has(id)) ??
222
+ this.spansByTrace.keys().next().value;
223
+ if (victim === undefined) return;
224
+ this.spansByTrace.delete(victim);
225
+ }
226
+ }
227
+
228
+ private emit(): void {
229
+ for (const listener of this.listeners) listener();
230
+ }
231
+ }
@@ -0,0 +1,278 @@
1
+ /**
2
+ * Dev request pill — the DOM. A fixed pill in the bottom-right corner (the
3
+ * compiling overlay owns bottom-left) that opens a waterfall of the selected
4
+ * request's server spans. Rendered in a shadow root so app CSS can't reach
5
+ * it and it can't reach the app. See design/50-dev-request-pill.md §"The pill".
6
+ */
7
+
8
+ import { devSpanLabel } from '../../shared/dev-span.ts';
9
+ import type { DevPillStore, DevRequest, WaterfallRow } from './store.ts';
10
+
11
+ /** localStorage key remembering a minimized pill, per dev origin. */
12
+ const MINIMIZED_KEY = 'timber:dev-pill:minimized';
13
+
14
+ function readMinimized(): boolean {
15
+ try {
16
+ return localStorage.getItem(MINIMIZED_KEY) === '1';
17
+ } catch {
18
+ return false; // Storage blocked: start expanded, as on first visit.
19
+ }
20
+ }
21
+
22
+ function writeMinimized(value: boolean): void {
23
+ try {
24
+ if (value) localStorage.setItem(MINIMIZED_KEY, '1');
25
+ else localStorage.removeItem(MINIMIZED_KEY);
26
+ } catch {
27
+ // Storage blocked: the choice lasts until reload.
28
+ }
29
+ }
30
+
31
+ const STYLES = `
32
+ :host { all: initial; }
33
+ .root {
34
+ position: fixed; right: 12px; bottom: calc(12px + env(safe-area-inset-bottom, 0px));
35
+ z-index: 2147483646; display: flex; flex-direction: column; align-items: flex-end; gap: 8px;
36
+ font: 12px/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
37
+ color: #e8ebe6; -webkit-font-smoothing: antialiased;
38
+ }
39
+ .pill {
40
+ display: inline-flex; align-items: center; gap: 8px; padding: 6px 12px 6px 10px;
41
+ background: #171a16; border: 1px solid #2f352c; border-radius: 999px; color: inherit;
42
+ font: inherit; font-variant-numeric: tabular-nums; cursor: pointer;
43
+ box-shadow: 0 4px 16px rgb(0 0 0 / 0.25);
44
+ }
45
+ .pill:hover { border-color: #4a5444; }
46
+ .pill:focus-visible { outline: 2px solid #8fbf5a; outline-offset: 2px; }
47
+ .dot { width: 8px; height: 8px; border-radius: 50%; background: #8fbf5a; flex: none; }
48
+ .dot.slow { background: #e0a53a; }
49
+ .dot.error { background: #e5534b; }
50
+ .dot.open { animation: pulse 1s ease-in-out infinite; }
51
+ @keyframes pulse { 50% { opacity: 0.35; } }
52
+ .muted { color: #9aa394; }
53
+ .panel {
54
+ width: min(560px, calc(100vw - 24px)); max-height: min(60vh, 520px);
55
+ display: flex; flex-direction: column; background: #171a16; border: 1px solid #2f352c;
56
+ border-radius: 10px; overflow: hidden; box-shadow: 0 12px 40px rgb(0 0 0 / 0.35);
57
+ }
58
+ .head {
59
+ display: flex; align-items: center; gap: 8px; padding: 8px 10px;
60
+ border-bottom: 1px solid #2f352c;
61
+ }
62
+ select {
63
+ flex: 1; min-width: 0; background: #20241e; color: inherit; border: 1px solid #2f352c;
64
+ border-radius: 6px; padding: 4px 6px; font: inherit;
65
+ }
66
+ .rows { overflow: auto; padding: 4px 0; }
67
+ .row {
68
+ display: grid; grid-template-columns: minmax(0, 1fr) minmax(80px, 38%) 56px;
69
+ align-items: center; gap: 8px; padding: 3px 10px;
70
+ }
71
+ .row:hover { background: #20241e; }
72
+ .label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
73
+ .label .sub { color: #9aa394; margin-left: 6px; }
74
+ .track { position: relative; height: 8px; }
75
+ .bar {
76
+ position: absolute; top: 0; height: 8px; min-width: 2px; border-radius: 2px;
77
+ background: #5f7f45;
78
+ }
79
+ .bar.fetch { background: #4f86b8; }
80
+ .bar.await { background: #3f9a8f; }
81
+ .bar.slow { background: #e0a53a; }
82
+ .bar.error { background: #e5534b; }
83
+ .dur { text-align: right; font-variant-numeric: tabular-nums; color: #9aa394; }
84
+ .empty { padding: 16px 10px; color: #9aa394; }
85
+ .bar-row { display: flex; align-items: center; gap: 4px; }
86
+ .icon {
87
+ display: inline-grid; place-items: center; width: 24px; height: 24px; padding: 0;
88
+ background: #171a16; border: 1px solid #2f352c; border-radius: 999px; color: #9aa394;
89
+ font: 14px/1 ui-sans-serif, system-ui, sans-serif; cursor: pointer;
90
+ }
91
+ .icon:hover { color: #e8ebe6; border-color: #4a5444; }
92
+ .icon:focus-visible, .mini:focus-visible { outline: 2px solid #8fbf5a; outline-offset: 2px; }
93
+ .mini {
94
+ width: 14px; height: 14px; padding: 0; border-radius: 50%; cursor: pointer;
95
+ background: #171a16; border: 1px solid #4a5444; opacity: 0.6;
96
+ display: grid; place-items: center;
97
+ }
98
+ .mini:hover { opacity: 1; }
99
+ .mini .dot { width: 6px; height: 6px; }
100
+ @media (prefers-reduced-motion: reduce) { .dot.open { animation: none; } }
101
+ `;
102
+
103
+ function el<K extends keyof HTMLElementTagNameMap>(
104
+ tag: K,
105
+ className?: string,
106
+ text?: string
107
+ ): HTMLElementTagNameMap[K] {
108
+ const node = document.createElement(tag);
109
+ if (className) node.className = className;
110
+ if (text !== undefined) node.textContent = text;
111
+ return node;
112
+ }
113
+
114
+ function formatMs(ms: number): string {
115
+ return ms < 1 ? '<1ms' : ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`;
116
+ }
117
+
118
+ function requestLabel(r: DevRequest): string {
119
+ return `${r.kind === 'action' ? 'action' : r.method} ${r.path}`;
120
+ }
121
+
122
+ function rowSubtitle(row: WaterfallRow): string {
123
+ const a = row.span.attributes;
124
+ if (row.span.name === 'timber.fetch') {
125
+ const parts = [a['http.response.status_code'], a['timber.cache_status']].filter(
126
+ (v) => v !== undefined
127
+ );
128
+ return parts.join(' · ');
129
+ }
130
+ if (row.span.name === 'timber.await') {
131
+ return String(a['timber.await_location'] ?? '');
132
+ }
133
+ if (row.span.name === 'http.server.request') {
134
+ return String(a['http.response.status_code'] ?? '');
135
+ }
136
+ return row.span.events.includes('timber.cache.hit') ? 'cache hit' : '';
137
+ }
138
+
139
+ export function mountDevPill(store: DevPillStore): void {
140
+ const host = el('div');
141
+ host.id = 'timber-dev-pill';
142
+ const shadow = host.attachShadow({ mode: 'open' });
143
+ const style = el('style');
144
+ style.textContent = STYLES;
145
+ const root = el('div', 'root');
146
+ shadow.append(style, root);
147
+
148
+ let open = false;
149
+ let minimized = readMinimized();
150
+ let scheduled = false;
151
+
152
+ const setMinimized = (value: boolean) => {
153
+ minimized = value;
154
+ open = false;
155
+ writeMinimized(value);
156
+ render();
157
+ };
158
+
159
+ const render = () => {
160
+ scheduled = false;
161
+ root.replaceChildren();
162
+ const selected = store.selected;
163
+ if (!selected) return;
164
+ const summary = store.summary(selected.traceId);
165
+ const dot = el('span', 'dot');
166
+ if (summary.error) dot.classList.add('error');
167
+ else if (summary.slow) dot.classList.add('slow');
168
+ if (summary.durationMs === null) dot.classList.add('open');
169
+
170
+ // Minimized: a 14px dot that keeps its status color and restores on click.
171
+ if (minimized) {
172
+ const mini = el('button', 'mini');
173
+ mini.type = 'button';
174
+ mini.title = 'Show the timber request pill';
175
+ mini.setAttribute('aria-label', 'Show the timber request pill');
176
+ mini.append(dot);
177
+ mini.addEventListener('click', () => setMinimized(false));
178
+ root.append(mini);
179
+ return;
180
+ }
181
+
182
+ if (open) root.append(renderPanel(selected));
183
+
184
+ const pill = el('button', 'pill');
185
+ pill.type = 'button';
186
+ pill.setAttribute('aria-expanded', String(open));
187
+ pill.title = 'Server work behind this page (timber dev)';
188
+ const counts = [
189
+ `${summary.fetches} fetch${summary.fetches === 1 ? '' : 'es'}`,
190
+ ...(summary.awaits > 0 ? [`${summary.awaits} await${summary.awaits === 1 ? '' : 's'}`] : []),
191
+ ].join(' · ');
192
+ pill.append(
193
+ dot,
194
+ el('span', undefined, counts),
195
+ el('span', 'muted', summary.durationMs === null ? 'streaming…' : formatMs(summary.durationMs))
196
+ );
197
+ pill.addEventListener('click', () => {
198
+ open = !open;
199
+ render();
200
+ });
201
+ const hide = el('button', 'icon', '×');
202
+ hide.type = 'button';
203
+ hide.title =
204
+ 'Minimize (remembered in this browser). Disable entirely with dev.requestPill: false';
205
+ hide.setAttribute('aria-label', 'Minimize the timber request pill');
206
+ hide.addEventListener('click', () => setMinimized(true));
207
+ const row = el('div', 'bar-row');
208
+ row.append(pill, hide);
209
+ root.append(row);
210
+ };
211
+
212
+ const renderPanel = (selected: DevRequest): HTMLElement => {
213
+ const panel = el('div', 'panel');
214
+ const head = el('div', 'head');
215
+ const picker = el('select');
216
+ picker.setAttribute('aria-label', 'Request');
217
+ for (const r of store.requests) {
218
+ const option = el('option', undefined, requestLabel(r));
219
+ option.value = r.traceId;
220
+ option.selected = r.traceId === selected.traceId;
221
+ picker.append(option);
222
+ }
223
+ picker.addEventListener('change', () => store.select(picker.value));
224
+ head.append(picker);
225
+
226
+ const rows = el('div', 'rows');
227
+ const waterfall = store.waterfall(selected.traceId);
228
+ if (waterfall.length === 0) {
229
+ rows.append(el('div', 'empty', 'Waiting for spans…'));
230
+ }
231
+ const total = Math.max(1, ...waterfall.map((r) => r.offsetMs + r.durationMs));
232
+ for (const row of waterfall) {
233
+ const line = el('div', 'row');
234
+ const { label } = devSpanLabel(row.span.name, row.span.attributes);
235
+ const labelCell = el('div', 'label');
236
+ labelCell.style.paddingLeft = `${row.depth * 12}px`;
237
+ labelCell.title = label;
238
+ labelCell.append(document.createTextNode(label));
239
+ const sub = rowSubtitle(row);
240
+ if (sub) labelCell.append(el('span', 'sub', sub));
241
+
242
+ const track = el('div', 'track');
243
+ const bar = el('div', 'bar');
244
+ if (row.span.name === 'timber.fetch') bar.classList.add('fetch');
245
+ else if (row.span.name === 'timber.await') bar.classList.add('await');
246
+ if (row.span.error) bar.classList.add('error');
247
+ else if (row.depth > 0 && row.durationMs > store.slowMs) bar.classList.add('slow');
248
+ bar.style.left = `${(row.offsetMs / total) * 100}%`;
249
+ bar.style.width = `${(row.durationMs / total) * 100}%`;
250
+ track.append(bar);
251
+
252
+ line.append(labelCell, track, el('div', 'dur', formatMs(row.durationMs)));
253
+ rows.append(line);
254
+ }
255
+ panel.append(head, rows);
256
+ return panel;
257
+ };
258
+
259
+ // Escape closes the panel.
260
+ document.addEventListener('keydown', (event) => {
261
+ if (event.key === 'Escape' && open) {
262
+ open = false;
263
+ render();
264
+ }
265
+ });
266
+
267
+ // Spans arrive in bursts; render at most once a frame.
268
+ store.subscribe(() => {
269
+ if (scheduled) return;
270
+ scheduled = true;
271
+ requestAnimationFrame(render);
272
+ });
273
+
274
+ const attach = () => document.body.append(host);
275
+ if (document.body) attach();
276
+ else document.addEventListener('DOMContentLoaded', attach, { once: true });
277
+ render();
278
+ }
@@ -61,6 +61,7 @@ export interface LinkFunction {
61
61
  // augmentation in `.timber/timber-routes.d.ts`.
62
62
  }
63
63
  export { usePendingNavigation } from './use-pending-navigation.ts';
64
+ export type { PendingNavigationSelector } from './use-pending-navigation.ts';
64
65
  export { useLinkStatus, LinkStatusContext } from './use-link-status.ts';
65
66
  export type { LinkStatus } from './use-link-status.ts';
66
67
  export { useRouter } from './use-router.ts';
@@ -82,9 +82,12 @@ export interface NavigationState {
82
82
  * which has throwing stubs for the hooks (TIM-1420).
83
83
  *
84
84
  * See design/19-client-navigation.md §"Singleton Guarantee via globalThis"
85
+ *
86
+ * Exported for `usePendingNavigation(select)`, which reads it with React
87
+ * `use()` — only in its selector form, so the plain form does not re-render
88
+ * on every commit.
85
89
  */
86
-
87
- function getOrCreateContext(): import('react').Context<NavigationState | null> {
90
+ export function getOrCreateContext(): import('react').Context<NavigationState | null> {
88
91
  return createGlobalContext<NavigationState | null>(Symbol.for('__timber_nav_ctx'), null);
89
92
  }
90
93
 
@@ -64,7 +64,10 @@ export interface NavigationLifecycle {
64
64
  /** React has committed `owner`'s tree — every earlier handoff is off screen. */
65
65
  forgetOlderHandoffs: (owner: RenderOwner) => void;
66
66
 
67
- /** Whether a navigation is currently in flight. */
67
+ /**
68
+ * Whether a navigation is in flight: from its start until its payload has
69
+ * decoded AND React has committed its tree, whichever is later.
70
+ */
68
71
  isPending: () => boolean;
69
72
  /** The URL currently being navigated to, or null if idle. */
70
73
  getPendingUrl: () => string | null;
@@ -260,16 +263,27 @@ export function createNavigationLifecycle(): NavigationLifecycle {
260
263
  ): Promise<void> {
261
264
  const owner = createNavOwner('navigation', externalSignal);
262
265
  setPending(true, url);
266
+ let failed = false;
263
267
  try {
264
268
  await fn(owner);
265
269
  } catch (error) {
266
270
  if (isAbortError(error)) return;
271
+ failed = true;
267
272
  throw error;
268
273
  } finally {
269
274
  if (current === owner) {
270
275
  current = null;
271
- setPending(false);
272
- flushIdleTask();
276
+ // A tree handed to React but not yet committed is still loading as
277
+ // far as the user can see: React may be rendering it for a while
278
+ // after the stream finishes decoding. Pending stays on until the
279
+ // commit (forgetOlderHandoffs) or a supersession clears it, so the
280
+ // loader ends on the later of decode and commit. A navigation that
281
+ // failed ends now: its tree may never commit (design/19 §"How
282
+ // Pending State Works").
283
+ if (failed || pendingCommit !== owner) {
284
+ setPending(false);
285
+ flushIdleTask();
286
+ }
273
287
  }
274
288
  }
275
289
  }
@@ -313,6 +327,9 @@ export function createNavigationLifecycle(): NavigationLifecycle {
313
327
  owner.settle('committed');
314
328
  if (pendingCommit === owner) {
315
329
  pendingCommit = null;
330
+ // runNavigation already finished decoding and left pending on for
331
+ // this commit. If it is still decoding, its finally clears pending.
332
+ if (current !== owner) setPending(false);
316
333
  }
317
334
  const seq = ownerSeq.get(owner) ?? navigationSeq;
318
335
  for (const listener of [...treeCommitListeners]) listener(seq);
@@ -363,6 +380,9 @@ export function createNavigationLifecycle(): NavigationLifecycle {
363
380
  settleHandoffs(): void {
364
381
  if (pendingCommit) {
365
382
  pendingCommit.settle('superseded');
383
+ // Its runNavigation may already have finished and left pending on
384
+ // for a commit that will now never come.
385
+ if (current !== pendingCommit) setPending(false);
366
386
  pendingCommit = null;
367
387
  }
368
388
  if (current !== null && current.handedOff && current.outcome === null) {