@timber-js/app 0.2.0-alpha.228 → 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 (145) hide show
  1. package/agent-skill.md +9 -0
  2. package/dist/_chunks/{actions-DprvPi7O.js → actions-DHum77eH.js} +3 -3
  3. package/dist/_chunks/{actions-DprvPi7O.js.map → actions-DHum77eH.js.map} +1 -1
  4. package/dist/_chunks/{cache-api-BjE-nNC0.js → cache-api-BZJNt01a.js} +4 -4
  5. package/dist/_chunks/{cache-api-BjE-nNC0.js.map → cache-api-BZJNt01a.js.map} +1 -1
  6. package/dist/_chunks/{chains-DaDEXv0c.js → chains-D-RRc7CM.js} +2 -2
  7. package/dist/_chunks/{chains-DaDEXv0c.js.map → chains-D-RRc7CM.js.map} +1 -1
  8. package/dist/_chunks/chains-KblEfYzm.js +1 -0
  9. package/dist/_chunks/{classify-BuIifN5v.js → classify-_W0RWa5w.js} +2 -2
  10. package/dist/_chunks/{classify-BuIifN5v.js.map → classify-_W0RWa5w.js.map} +1 -1
  11. package/dist/_chunks/{cli-check-B_fDvxhs.js → cli-check-B-JZkpBD.js} +3 -3
  12. package/dist/_chunks/{cli-check-B_fDvxhs.js.map → cli-check-B-JZkpBD.js.map} +1 -1
  13. package/dist/_chunks/{cli-schema-sync-D9OLUUFv.js → cli-schema-sync-CAllbqRB.js} +2 -2
  14. package/dist/_chunks/{cli-schema-sync-D9OLUUFv.js.map → cli-schema-sync-CAllbqRB.js.map} +1 -1
  15. package/dist/_chunks/{cli-schema-sync-CUIk0G2X.js → cli-schema-sync-y_8ijmzO.js} +1 -1
  16. package/dist/_chunks/{client-dep-entries-COuyF8-c.js → client-dep-entries-C9hv-3k9.js} +2 -2
  17. package/dist/_chunks/{client-dep-entries-COuyF8-c.js.map → client-dep-entries-C9hv-3k9.js.map} +1 -1
  18. package/dist/_chunks/{convention-lint-BHY0d5AQ.js → convention-lint-CrDKERHg.js} +3 -3
  19. package/dist/_chunks/{convention-lint-BHY0d5AQ.js.map → convention-lint-CrDKERHg.js.map} +1 -1
  20. package/dist/_chunks/dev-server-L8biS7Az.js +1 -0
  21. package/dist/_chunks/{dev-server-BaM7q3pr.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-CZJ9Drb7.js → flight-source-node-BGanuoSS.js} +2 -2
  28. package/dist/_chunks/{flight-source-node-CZJ9Drb7.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-BNwKrm2R.js → json-lossy-check-BXM45k8p.js} +2 -2
  32. package/dist/_chunks/{json-lossy-check-BNwKrm2R.js.map → json-lossy-check-BXM45k8p.js.map} +1 -1
  33. package/dist/_chunks/{live-graph-DiRVmRrC.js → live-graph-C7-yA8W9.js} +4 -4
  34. package/dist/_chunks/{live-graph-DiRVmRrC.js.map → live-graph-C7-yA8W9.js.map} +1 -1
  35. package/dist/_chunks/{logger-DRMij51J.js → logger-YtMSKfft.js} +100 -57
  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-C-dQn-0N.js → node-response-D3hXWb8y.js} +2 -2
  40. package/dist/_chunks/{node-response-C-dQn-0N.js.map → node-response-D3hXWb8y.js.map} +1 -1
  41. package/dist/_chunks/{poison-scan-CqPGN0ru.js → poison-scan-CRSP06Es.js} +2 -2
  42. package/dist/_chunks/{poison-scan-CqPGN0ru.js.map → poison-scan-CRSP06Es.js.map} +1 -1
  43. package/dist/_chunks/{scanner-C__vsQ8d.js → scanner-BNQ4qnLX.js} +2 -2
  44. package/dist/_chunks/{scanner-C__vsQ8d.js.map → scanner-BNQ4qnLX.js.map} +1 -1
  45. package/dist/_chunks/segment-context-GAyTjjtS.js +33 -0
  46. package/dist/_chunks/segment-context-GAyTjjtS.js.map +1 -0
  47. package/dist/_chunks/{sizeof-DcEcQaSL.js → sizeof-Cmx6Fs-Y.js} +2 -2
  48. package/dist/_chunks/{sizeof-DcEcQaSL.js.map → sizeof-Cmx6Fs-Y.js.map} +1 -1
  49. package/dist/_chunks/{status-page-marker-C8POawuF.js → status-page-marker-U6B1aFMb.js} +3 -32
  50. package/dist/_chunks/status-page-marker-U6B1aFMb.js.map +1 -0
  51. package/dist/_chunks/{walkers-D6KY4jyS.js → walkers-D_QHR_nf.js} +3 -3
  52. package/dist/_chunks/{walkers-D6KY4jyS.js.map → walkers-D_QHR_nf.js.map} +1 -1
  53. package/dist/adapters/cloudflare-kv-cache.js +1 -1
  54. package/dist/analyze/crawl-entry.js +3 -3
  55. package/dist/analyze/graph-command.js +2 -2
  56. package/dist/cache/index.js +2 -2
  57. package/dist/cache/stores/memory.js +1 -1
  58. package/dist/cli.js +3 -3
  59. package/dist/client/browser-entry/hmr.d.ts +7 -1
  60. package/dist/client/browser-entry/hmr.d.ts.map +1 -1
  61. package/dist/client/dev-pill/index.d.ts +32 -0
  62. package/dist/client/dev-pill/index.d.ts.map +1 -0
  63. package/dist/client/dev-pill/store.d.ts +96 -0
  64. package/dist/client/dev-pill/store.d.ts.map +1 -0
  65. package/dist/client/dev-pill/view.d.ts +9 -0
  66. package/dist/client/dev-pill/view.d.ts.map +1 -0
  67. package/dist/client/error-boundary.js +1 -1
  68. package/dist/client/index.d.ts +1 -0
  69. package/dist/client/index.d.ts.map +1 -1
  70. package/dist/client/index.js +3 -3
  71. package/dist/client/internal.js +16 -7
  72. package/dist/client/internal.js.map +1 -1
  73. package/dist/client/navigation-context.d.ts +20 -0
  74. package/dist/client/navigation-context.d.ts.map +1 -1
  75. package/dist/client/router-lifecycle.d.ts +4 -1
  76. package/dist/client/router-lifecycle.d.ts.map +1 -1
  77. package/dist/client/use-pending-navigation.d.ts +33 -9
  78. package/dist/client/use-pending-navigation.d.ts.map +1 -1
  79. package/dist/config-types.d.ts +10 -0
  80. package/dist/config-types.d.ts.map +1 -1
  81. package/dist/config-validation.d.ts.map +1 -1
  82. package/dist/dev-tools/await-span.d.ts +17 -0
  83. package/dist/dev-tools/await-span.d.ts.map +1 -0
  84. package/dist/dev-tools/instrumentation.d.ts.map +1 -1
  85. package/dist/dev-tools/logger.d.ts.map +1 -1
  86. package/dist/dev-tools/logs.d.ts.map +1 -1
  87. package/dist/dev-tools/span-sink.d.ts +42 -0
  88. package/dist/dev-tools/span-sink.d.ts.map +1 -0
  89. package/dist/index.d.ts.map +1 -1
  90. package/dist/index.js +282 -9
  91. package/dist/index.js.map +1 -1
  92. package/dist/plugins/dev-await.d.ts +40 -0
  93. package/dist/plugins/dev-await.d.ts.map +1 -0
  94. package/dist/plugins/entries.d.ts.map +1 -1
  95. package/dist/routing/index.js +2 -2
  96. package/dist/server/index.js +2 -2
  97. package/dist/server/internal.js +9 -8
  98. package/dist/server/internal.js.map +1 -1
  99. package/dist/server/pipeline.d.ts +8 -0
  100. package/dist/server/pipeline.d.ts.map +1 -1
  101. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  102. package/dist/server/slot-resolver.d.ts.map +1 -1
  103. package/dist/server/tracing.d.ts +18 -8
  104. package/dist/server/tracing.d.ts.map +1 -1
  105. package/dist/shared/dev-span.d.ts +97 -0
  106. package/dist/shared/dev-span.d.ts.map +1 -0
  107. package/docs/api/31-api-client.mdx +27 -1
  108. package/docs/api/34-api-config.mdx +21 -1
  109. package/docs/learn/09-streaming.mdx +7 -1
  110. package/package.json +3 -3
  111. package/src/client/browser-entry/hmr.ts +13 -1
  112. package/src/client/browser-entry/index.ts +4 -1
  113. package/src/client/dev-pill/index.ts +128 -0
  114. package/src/client/dev-pill/store.ts +231 -0
  115. package/src/client/dev-pill/view.ts +278 -0
  116. package/src/client/index.ts +1 -0
  117. package/src/client/navigation-context.ts +5 -2
  118. package/src/client/router-lifecycle.ts +23 -3
  119. package/src/client/use-pending-navigation.ts +93 -14
  120. package/src/config-types.ts +10 -0
  121. package/src/config-validation.ts +10 -0
  122. package/src/dev-tools/await-span.ts +40 -0
  123. package/src/dev-tools/instrumentation.ts +20 -0
  124. package/src/dev-tools/logger.ts +3 -37
  125. package/src/dev-tools/logs.ts +10 -1
  126. package/src/dev-tools/span-sink.ts +132 -0
  127. package/src/index.ts +2 -0
  128. package/src/plugins/dev-await.ts +268 -0
  129. package/src/plugins/entries.ts +2 -0
  130. package/src/server/pipeline.ts +14 -0
  131. package/src/server/rsc-entry/index.ts +7 -1
  132. package/src/server/slot-resolver.ts +45 -5
  133. package/src/server/tracing.ts +121 -87
  134. package/src/shared/dev-span.ts +182 -0
  135. package/dist/_chunks/build-manifest-Y4jl7nwU.js.map +0 -1
  136. package/dist/_chunks/chains-BS8fQYao.js +0 -1
  137. package/dist/_chunks/dev-server-BaM7q3pr.js.map +0 -1
  138. package/dist/_chunks/dev-server-NnGosJ06.js +0 -1
  139. package/dist/_chunks/global-context-DbxNWeBP.js.map +0 -1
  140. package/dist/_chunks/logger-DRMij51J.js.map +0 -1
  141. package/dist/_chunks/navigation-root-M3B2ZrdO.js +0 -122
  142. package/dist/_chunks/navigation-root-M3B2ZrdO.js.map +0 -1
  143. package/dist/_chunks/segment-context-CYiGTi3K.js +0 -131
  144. package/dist/_chunks/segment-context-CYiGTi3K.js.map +0 -1
  145. package/dist/_chunks/status-page-marker-C8POawuF.js.map +0 -1
@@ -0,0 +1,268 @@
1
+ /**
2
+ * timber-dev-await — dev-only transform that turns every `await` in app
3
+ * server code into a span, so postgres queries, redis calls and SDK
4
+ * requests appear in the terminal tree and the dev request pill without
5
+ * per-library instrumentation.
6
+ *
7
+ * const rows = await db.select().from(users);
8
+ * // becomes
9
+ * const rows = await __timber_await$(async () => (db.select().from(users)),
10
+ * "db.select().from(users)", "app/users/page.tsx:12");
11
+ *
12
+ * `__timber_await$` is declared once per module and looks the wrapper up on
13
+ * `globalThis[DEV_AWAIT_KEY]` at call time (installed with dev tracing,
14
+ * `dev-tools/await-span.ts`); with none installed it calls the thunk. A
15
+ * global rather than an injected import, so the rewrite needs no resolvable
16
+ * specifier from a workspace package outside the app.
17
+ *
18
+ * Scope: the RSC environment, `vite dev` only; every module outside
19
+ * node_modules and outside timber itself, so a monorepo's `packages/db`
20
+ * (where the query actually is) is covered. Skipped: `'use client'`
21
+ * modules, top-level await (no request to nest under), awaits of literals,
22
+ * `await import()` (module loading, and plugin-rsc injects one per layout),
23
+ * awaits whose operand contains `yield` (an async arrow can't hold it).
24
+ * `for await` and `await using` are not AwaitExpressions and are untouched.
25
+ *
26
+ * See design/50-dev-request-pill.md §"Phase 2".
27
+ */
28
+
29
+ import { existsSync } from 'node:fs';
30
+ import { dirname, join, relative } from 'node:path';
31
+ import { fileURLToPath } from 'node:url';
32
+ import MagicString from 'magic-string';
33
+ import { parseAst, type Plugin } from 'vite';
34
+ import type { PluginContext } from '../plugin-context.ts';
35
+
36
+ /** The per-module helper's name; `$` keeps it out of the way of app identifiers. */
37
+ const HELPER = '__timber_await$';
38
+
39
+ /** Longest label kept, in characters. */
40
+ const LABEL_MAX = 80;
41
+
42
+ const SCRIPT_RE = /\.[cm]?[jt]sx?$/;
43
+
44
+ interface Node {
45
+ type: string;
46
+ start: number;
47
+ end: number;
48
+ [key: string]: unknown;
49
+ }
50
+
51
+ function isNode(value: unknown): value is Node {
52
+ return (
53
+ typeof value === 'object' &&
54
+ value !== null &&
55
+ typeof (value as { type?: unknown }).type === 'string' &&
56
+ typeof (value as { start?: unknown }).start === 'number'
57
+ );
58
+ }
59
+
60
+ function children(node: Node): Node[] {
61
+ const out: Node[] = [];
62
+ for (const key of Object.keys(node)) {
63
+ const value = node[key];
64
+ if (Array.isArray(value)) {
65
+ for (const item of value) if (isNode(item)) out.push(item);
66
+ } else if (isNode(value)) {
67
+ out.push(value);
68
+ }
69
+ }
70
+ return out;
71
+ }
72
+
73
+ const FUNCTION_TYPES = new Set([
74
+ 'FunctionDeclaration',
75
+ 'FunctionExpression',
76
+ 'ArrowFunctionExpression',
77
+ ]);
78
+
79
+ function containsYield(node: Node): boolean {
80
+ if (node.type === 'YieldExpression') return true;
81
+ // A nested function's yields belong to it.
82
+ if (FUNCTION_TYPES.has(node.type)) return false;
83
+ return children(node).some(containsYield);
84
+ }
85
+
86
+ /** Leading directive prologue: `'use server'`, `'use client'`, `'use strict'`. */
87
+ function directives(program: Node): { names: string[]; end: number } {
88
+ const body = (program.body as Node[] | undefined) ?? [];
89
+ const names: string[] = [];
90
+ let end = 0;
91
+ for (const stmt of body) {
92
+ if (typeof stmt.directive !== 'string') break;
93
+ names.push(stmt.directive);
94
+ end = stmt.end;
95
+ }
96
+ return { names, end };
97
+ }
98
+
99
+ /** A string or template that starts like a URL: `scheme://`, `/path`, `?query`, or `${base}/path`. */
100
+ const URL_START = /^(?:[a-z][a-z0-9+.-]*:\/\/|\/|\?|\$\{[^}]*\}\/)/i;
101
+
102
+ /** `scheme://user:pass@host` → `scheme://…@host`. */
103
+ function redactUserinfo(text: string): string {
104
+ return text.replace(/:\/\/[^/@\s]*@/g, '://…@');
105
+ }
106
+
107
+ /**
108
+ * The operand's source with URL secrets cut out. Labels are source text,
109
+ * but source can hold literals: `fetch('https://api/x?token=abc')` would
110
+ * put the token in a span attribute that reaches the browser, the replay
111
+ * buffer and any OTEL exporter. In string and template literals that start
112
+ * like a URL, everything from the first `?` or `#` becomes `?…` / `#…`,
113
+ * and userinfo becomes `…@`. Other strings (a SQL `?` placeholder) and
114
+ * code (`a?.b`, ternaries) are left alone. Codex review on #1272.
115
+ */
116
+ function redactedSource(code: string, arg: Node): string {
117
+ const edits: Array<{ start: number; end: number; text: string }> = [];
118
+ const visit = (node: Node) => {
119
+ if (node.type === 'Literal' && typeof node.value === 'string') {
120
+ const inner = code.slice(node.start + 1, node.end - 1);
121
+ if (URL_START.test(inner)) {
122
+ const cut = inner.search(/[?#]/);
123
+ const kept = cut === -1 ? inner : `${inner.slice(0, cut)}${inner[cut]}…`;
124
+ edits.push({ start: node.start + 1, end: node.end - 1, text: redactUserinfo(kept) });
125
+ }
126
+ return;
127
+ }
128
+ if (node.type === 'TemplateLiteral') {
129
+ const inner = code.slice(node.start + 1, node.end - 1);
130
+ const quasis = (node.quasis as Node[] | undefined) ?? [];
131
+ if (URL_START.test(inner)) {
132
+ for (const quasi of quasis) {
133
+ const raw = code.slice(quasi.start, quasi.end);
134
+ const cut = raw.search(/[?#]/);
135
+ if (cut === -1) {
136
+ edits.push({ start: quasi.start, end: quasi.end, text: redactUserinfo(raw) });
137
+ continue;
138
+ }
139
+ // Everything after the cut, later ${…} included, is query.
140
+ edits.push({
141
+ start: quasi.start,
142
+ end: node.end - 1,
143
+ text: `${redactUserinfo(raw.slice(0, cut))}${raw[cut]}…`,
144
+ });
145
+ return;
146
+ }
147
+ return;
148
+ }
149
+ }
150
+ for (const child of children(node)) visit(child);
151
+ };
152
+ visit(arg);
153
+
154
+ let out = '';
155
+ let at = arg.start;
156
+ for (const edit of edits.sort((a, b) => a.start - b.start)) {
157
+ if (edit.start < at) continue;
158
+ out += code.slice(at, edit.start) + edit.text;
159
+ at = edit.end;
160
+ }
161
+ return out + code.slice(at, arg.end);
162
+ }
163
+
164
+ function label(source: string): string {
165
+ const collapsed = source.replace(/\s+/g, ' ').trim();
166
+ return collapsed.length > LABEL_MAX ? `${collapsed.slice(0, LABEL_MAX - 1)}…` : collapsed;
167
+ }
168
+
169
+ /**
170
+ * Rewrite the awaits in one module. Returns null when nothing changed.
171
+ * Exported for tests; `relPath` is the location prefix shown in the pill.
172
+ */
173
+ export function instrumentAwaits(
174
+ code: string,
175
+ relPath: string
176
+ ): { code: string; map: ReturnType<MagicString['generateMap']> } | null {
177
+ if (!code.includes('await')) return null;
178
+
179
+ let parsed: unknown;
180
+ try {
181
+ // Runs after Vite's own TS/JSX transform, but `jsx` also accepts
182
+ // anything that reaches it untransformed.
183
+ parsed = parseAst(code, { lang: 'jsx' });
184
+ } catch {
185
+ return null; // Not ours to report; the module's own parse will.
186
+ }
187
+ if (!isNode(parsed)) return null;
188
+ const program = parsed;
189
+
190
+ const prologue = directives(program);
191
+ if (prologue.names.includes('use client')) return null;
192
+
193
+ const lineStarts = [0];
194
+ for (let i = 0; i < code.length; i++) if (code[i] === '\n') lineStarts.push(i + 1);
195
+ const lineOf = (offset: number) => {
196
+ let lo = 0;
197
+ let hi = lineStarts.length - 1;
198
+ while (lo < hi) {
199
+ const mid = (lo + hi + 1) >> 1;
200
+ if (lineStarts[mid]! <= offset) lo = mid;
201
+ else hi = mid - 1;
202
+ }
203
+ return lo + 1;
204
+ };
205
+
206
+ const s = new MagicString(code);
207
+ let count = 0;
208
+
209
+ const visit = (node: Node, inFunction: boolean) => {
210
+ const nowInFunction = inFunction || FUNCTION_TYPES.has(node.type);
211
+ for (const child of children(node)) visit(child, nowInFunction);
212
+
213
+ // Post-order, so an inner await's suffix lands before an outer one's
214
+ // at a shared end offset.
215
+ if (node.type !== 'AwaitExpression' || !nowInFunction) return;
216
+ const arg = node.argument;
217
+ if (!isNode(arg) || arg.type === 'Literal' || containsYield(arg)) return;
218
+ // Module loading, not data — and plugin-rsc injects `await import()` of
219
+ // its CSS virtual module into layouts, which read as a slow app await.
220
+ if (arg.type === 'ImportExpression') return;
221
+
222
+ const text = JSON.stringify(label(redactedSource(code, arg)));
223
+ const location = JSON.stringify(`${relPath}:${lineOf(node.start)}`);
224
+ // Parenthesized: the operand may be a sequence or an object literal.
225
+ // Async: the operand may itself contain an await.
226
+ s.prependRight(arg.start, `${HELPER}(async () => (`);
227
+ s.appendLeft(arg.end, `), ${text}, ${location})`);
228
+ count++;
229
+ };
230
+ visit(program, false);
231
+ if (count === 0) return null;
232
+
233
+ // After the directive prologue — a statement before `'use server'` would
234
+ // demote it to a plain string.
235
+ const helper =
236
+ `\nconst ${HELPER} = (f, l, c) => ` +
237
+ `(globalThis[Symbol.for("timber.dev.await")] ?? ((g) => g()))(f, l, c);\n`;
238
+ s.appendLeft(prologue.end, helper);
239
+
240
+ return { code: s.toString(), map: s.generateMap({ hires: true }) };
241
+ }
242
+
243
+ /** Directory of the nearest package.json above this file: timber itself. */
244
+ function findTimberRoot(): string {
245
+ let dir = dirname(fileURLToPath(import.meta.url));
246
+ while (!existsSync(join(dir, 'package.json'))) {
247
+ const parent = dirname(dir);
248
+ if (parent === dir) break;
249
+ dir = parent;
250
+ }
251
+ return dir;
252
+ }
253
+
254
+ export function timberDevAwait(ctx: PluginContext): Plugin {
255
+ const timberRoot = findTimberRoot();
256
+ return {
257
+ name: 'timber-dev-await',
258
+ apply: 'serve',
259
+ applyToEnvironment: (env) => env.name === 'rsc',
260
+ transform(code, id) {
261
+ if (id.startsWith('\0')) return;
262
+ const file = id.split('?')[0]!;
263
+ if (!SCRIPT_RE.test(file) || file.includes('/node_modules/')) return;
264
+ if (file.startsWith(`${timberRoot}/`)) return;
265
+ return instrumentAwaits(code, relative(ctx.root, file)) ?? undefined;
266
+ },
267
+ };
268
+ }
@@ -156,6 +156,8 @@ function generateConfigModule(ctx: PluginContext): string {
156
156
  base: ctx.base,
157
157
  dev: ctx.dev ?? false,
158
158
  slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
159
+ // Read by the dev HMR setup only. design/50-dev-request-pill.md.
160
+ devRequestPill: ctx.config.dev?.requestPill ?? true,
159
161
  slowRequestMs: ctx.config.slowRequestMs ?? 3000,
160
162
  topLoader: ctx.config.topLoader,
161
163
  debug: ctx.config.debug ?? false,
@@ -19,10 +19,12 @@ import type { CoercedParams } from '../shared/param-value.ts';
19
19
  import type { ProxyExport } from './proxy.ts';
20
20
  import type { MiddlewareFn } from './middleware-runner.ts';
21
21
  import { runWithTimingCollector, getServerTimingHeader } from './server-timing.ts';
22
+ import { traceTimingEntry } from '../shared/dev-span.ts';
22
23
  import { wrapResponseWithStreamTiming } from './stream-utils.ts';
23
24
  import { runWithRequestContext } from './request-context.ts';
24
25
  import {
25
26
  generateTraceId,
27
+ getTraceId,
26
28
  runWithTraceId,
27
29
  getOtelTraceId,
28
30
  replaceTraceId,
@@ -199,6 +201,14 @@ export interface PipelineConfig {
199
201
  * Default: `'total'`.
200
202
  */
201
203
  serverTiming?: 'detailed' | 'total' | false;
204
+ /**
205
+ * Add a `timber-trace;desc="<traceId>"` Server-Timing entry to every
206
+ * response, whatever `serverTiming` is, so the dev request pill can match
207
+ * the page and its fetches to their spans. Set by the dev RSC entry only:
208
+ * it must never be on in a production build, `TIMBER_DEBUG` included.
209
+ * See design/50-dev-request-pill.md §"Correlation".
210
+ */
211
+ devTraceTiming?: boolean;
202
212
  /**
203
213
  * Auto-generated sitemap handler. When provided, the pipeline intercepts
204
214
  * `/sitemap.xml` and `/sitemap/N.xml` requests and delegates to this
@@ -572,6 +582,10 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
572
582
  }
573
583
  // serverTiming === false: no header at all
574
584
 
585
+ if (config.devTraceTiming) {
586
+ result.headers.append('Server-Timing', traceTimingEntry(getTraceId()));
587
+ }
588
+
575
589
  // Wrap the response body with stream-lifecycle timing when
576
590
  // detailed mode is on. Logs firstChunk/lastChunk/maxGap/close
577
591
  // on stream close — measures the post-flush stream tail that
@@ -281,7 +281,10 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
281
281
  // without exposing anything to clients.
282
282
  if (debugEnabled) {
283
283
  const devLogMode = resolveLogMode();
284
- if (devLogMode !== 'quiet') {
284
+ // Quiet silences the terminal tree, not the spans: in dev they also
285
+ // feed the request pill (design/50-dev-request-pill.md), and the
286
+ // processor prints nothing in quiet mode.
287
+ if (devLogMode !== 'quiet' || isDev) {
285
288
  await initDevTracing({ mode: devLogMode, slowPhaseMs });
286
289
  }
287
290
  }
@@ -400,6 +403,9 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
400
403
  // See design/17-logging.md §"slowRequestMs"
401
404
  slowRequestMs: (runtimeConfig as Record<string, unknown>).slowRequestMs as number | undefined,
402
405
  serverTiming: resolveServerTimingMode(runtimeConfig, isDev),
406
+ devTraceTiming:
407
+ isDev &&
408
+ ((runtimeConfig as Record<string, unknown>).devRequestPill as boolean | undefined) !== false,
403
409
  onPipelineError: isDev
404
410
  ? (error: Error, phase: string) => devHooks.onPipelineError?.(error, phase)
405
411
  : undefined,
@@ -25,6 +25,7 @@ import { containSlotSubtree } from './slot-subtree-contain.ts';
25
25
  import { loadModule, type ManifestLoader } from './safe-load.ts';
26
26
  import type { InterceptionContext, RouteMatch } from './pipeline.ts';
27
27
  import { isDenySignal, isRedirectSignal } from './signal-identity.ts';
28
+ import { traceCall, withSpan } from './tracing.ts';
28
29
  import { loadFallbackModule, reportRenderError } from './pipeline-helpers.ts';
29
30
  import type { ManifestSegmentNode } from './route-matcher.ts';
30
31
  import { setSlotParams, runWithSlotSegmentParams } from './request-context.ts';
@@ -152,10 +153,15 @@ export async function resolveSlotElement(
152
153
  if (isClientReference(SlotPage)) {
153
154
  element = h(SlotPage, {});
154
155
  } else {
156
+ // Same `timber.page` span as a main-route page, tagged with the slot
157
+ // so a slow `@slot` page is attributed to itself in a trace rather
158
+ // than hiding inside its parent layout's span.
159
+ const leaf = slotMatch.chain[slotMatch.chain.length - 1];
160
+ const spanAttributes = slotSpanAttributes('timber.route', leaf, slotNode);
155
161
  const SafeSlotPage = async (props: Record<string, unknown>) => {
156
162
  try {
157
- const rendered = await scope(() =>
158
- (SlotPage as (props: Record<string, unknown>) => unknown)(props)
163
+ const rendered = await withSpan('timber.page', spanAttributes, () =>
164
+ scope(() => (SlotPage as (props: Record<string, unknown>) => unknown)(props))
159
165
  );
160
166
  return containSlotSubtree(rendered as React.ReactNode, denyFallback);
161
167
  } catch (error) {
@@ -184,6 +190,7 @@ export async function resolveSlotElement(
184
190
  // handles main segments. The slot root (index 0) is handled below.
185
191
  element = await wrapWithIntermediateSegments(
186
192
  slotMatch.chain,
193
+ slotNode,
187
194
  element,
188
195
  h,
189
196
  req,
@@ -193,7 +200,7 @@ export async function resolveSlotElement(
193
200
 
194
201
  // Wrap with slot root's layout — INSIDE the access gate, so the layout
195
202
  // server component never executes when access.ts denies. See TIM-1074.
196
- element = await wrapWithLayout(slotNode, element, h, scope, denyFallback);
203
+ element = await wrapWithLayout(slotNode, slotNode, element, h, scope, denyFallback);
197
204
 
198
205
  // Wrap in SlotAccessGate if slot root has access.ts. The gate is
199
206
  // OUTSIDE the layout, matching the segment model in
@@ -286,6 +293,7 @@ function computeSlotSegmentPath(
286
293
  */
287
294
  async function wrapWithIntermediateSegments(
288
295
  chain: ManifestSegmentNode[],
296
+ slotNode: ManifestSegmentNode,
289
297
  element: React.ReactElement,
290
298
  h: CreateElementFn,
291
299
  req: Request,
@@ -300,7 +308,7 @@ async function wrapWithIntermediateSegments(
300
308
  errorBoundaryComponent: TimberErrorBoundary,
301
309
  isSlotBoundary: true,
302
310
  });
303
- element = await wrapWithLayout(seg, element, h, scope, denyFallback);
311
+ element = await wrapWithLayout(seg, slotNode, element, h, scope, denyFallback);
304
312
  element = await wrapWithAccessGate(seg, element, h, scope);
305
313
  }
306
314
  return element;
@@ -341,12 +349,42 @@ function ScopedSlotLayout(props: {
341
349
  layout: (props: Record<string, unknown>) => unknown;
342
350
  scope: SlotParamScope;
343
351
  denyFallback: React.ReactNode;
352
+ spanAttributes: Record<string, string>;
344
353
  children: React.ReactElement;
345
354
  }): unknown {
346
- const rendered = props.scope(() => props.layout({ children: props.children }));
355
+ // `traceCall`, not `withSpan`: the layout runs in this frame, under React's
356
+ // render dispatcher, and a synchronous throw leaves synchronously — so a
357
+ // sync layout's `use()` can suspend and be retried by Flight. A promise an
358
+ // async layout returns goes to the walk, which turns a rejected deny into
359
+ // the slot's fallback; a synchronous deny gets the same answer here.
360
+ let rendered: unknown;
361
+ try {
362
+ rendered = traceCall('timber.layout', props.spanAttributes, () =>
363
+ props.scope(() => props.layout({ children: props.children }))
364
+ );
365
+ } catch (error) {
366
+ if (isDenySignal(error)) return props.denyFallback;
367
+ throw error;
368
+ }
347
369
  return containSlotSubtree(rendered as React.ReactNode, props.denyFallback, props.children);
348
370
  }
349
371
 
372
+ /**
373
+ * Span attributes for a component in a slot's matched chain: the segment's
374
+ * URL pattern under `routeKey` (`timber.route` for a page, `timber.segment`
375
+ * for a layout — the keys the main route's spans use) and the slot's
376
+ * directory name under `timber.slot`. A slot is transparent to the URL, so
377
+ * without `timber.slot` a slot page and the main page at the same pattern
378
+ * would be indistinguishable in a trace.
379
+ */
380
+ function slotSpanAttributes(
381
+ routeKey: 'timber.route' | 'timber.segment',
382
+ node: ManifestSegmentNode,
383
+ slotNode: ManifestSegmentNode
384
+ ): Record<string, string> {
385
+ return { [routeKey]: node.urlPath || '/', 'timber.slot': slotNode.segmentName };
386
+ }
387
+
350
388
  /**
351
389
  * Wrap an element with a segment's layout component, if present.
352
390
  *
@@ -359,6 +397,7 @@ function ScopedSlotLayout(props: {
359
397
  */
360
398
  async function wrapWithLayout(
361
399
  node: ManifestSegmentNode,
400
+ slotNode: ManifestSegmentNode,
362
401
  element: React.ReactElement,
363
402
  h: CreateElementFn,
364
403
  scope?: SlotParamScope,
@@ -373,6 +412,7 @@ async function wrapWithLayout(
373
412
  layout: Layout as (props: Record<string, unknown>) => unknown,
374
413
  scope,
375
414
  denyFallback,
415
+ spanAttributes: slotSpanAttributes('timber.segment', node, slotNode),
376
416
  children: element,
377
417
  });
378
418
  }