Skip to content

Commit 7d1eeb3

Browse files
authored
Refresh preview extension metadata when _extension.yml changes (#15273)
Preview kept the extension metadata read at startup after an `_extension.yml` edit (such as a brand switch), so renders used the old values until preview was restarted. Both preview modes now pick up the change: a context rebuild reads extensions through a fresh extension context instead of the long-lived cache, and an extension edit triggers a rebuild before the next render. - Project preview treats `_extension.yml` edits as config changes, also when they share a poll event with input edits. - Single file preview rebuilds its context before the next render after an extension edit; it keeps reusing the context across renders. - Context swaps run on the render queue, so cleaning up the old context cannot race a render in flight. `ServeRenderManager` gains `submit()` for non-render tasks. - The preview reload debounce accumulates watch changes instead of keeping only the last call's arguments. Only render-time metadata follows the edit. Values read once at startup (`output-dir`, project type, `lib-dir`) still need a restart. Fixes #15266 See #14784 for the startup metadata this builds on. See #14281 for the single file context reuse this keeps.
1 parent c6ea753 commit 7d1eeb3

9 files changed

Lines changed: 461 additions & 39 deletions

File tree

‎.claude/rules/testing/typescript-tests.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,12 +86,17 @@ unitTest("feature - description", async () => {
8686

8787
Assertions come from `tests/asserts.ts` (relative path, e.g. `../asserts.ts` from `tests/unit/`), never from a std assertion module directly; the Runtime Boundary check flags a direct std import in tests. Exports: `assert`, `assertEquals`, `assertThrows`, `assertRejects`, `assertMatch`, `assertObjectMatch`, `assertStringIncludes`, `fail`, `AssertionError`
8888

89+
Tests follow the same runtime rule as `src/`: no new `Deno.*` calls, import the equivalent from `src/deno_ral/` (`fs.ts`, `temp.ts`, `path.ts`). The Runtime Boundary check counts `Deno.*` calls in `tests/` against a baseline and fails the PR on an increase. Before accepting an increase, check `src/deno_ral/` and `tests/utils.ts` (`writeFixture`, `withTempDir`) for an existing helper. See `.claude/rules/typescript/deno-ral.md`.
90+
8991
## Common Patterns
9092

9193
**Temp files:**
9294
```typescript
93-
const workingDir = Deno.makeTempDirSync({ prefix: "quarto-test" });
94-
// Use workingDir, clean up in teardown
95+
import { withTempDir } from "../utils.ts";
96+
97+
await withTempDir(async (workingDir) => {
98+
// Use workingDir; it is removed when the callback returns
99+
});
95100
```
96101

97102
**Fixtures:**

‎llm-docs/preview-architecture.md‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
2-
main_commit: 16257efdc
3-
analyzed_date: 2026-06-15
2+
main_commit: 8b0f68b95
3+
analyzed_date: 2026-11-03
44
key_files:
55
- src/command/preview/cmd.ts
66
- src/command/preview/preview.ts
77
- src/project/serve/serve.ts
88
- src/project/serve/watch.ts
9+
- src/project/serve/render.ts
910
- src/project/project-shared.ts
1011
- src/project/types.ts
1112
- src/execute/jupyter/jupyter.ts
@@ -100,7 +101,17 @@ When the watched source file changes:
100101
4. `render()` runs with the project context, which creates a fresh target/notebook
101102
5. Browser reloads
102103

103-
The project context persists across all re-renders. Only the per-file cache entry is invalidated.
104+
The project context persists across input re-renders; only the per-file cache
105+
entry is invalidated. The exception is an extension-file change (for example
106+
an `_extension.yml` edit switching the contributed `brand`): the extension
107+
watch sets a dirty flag via `createChangeHandler`'s `onExtensionChange`, and
108+
the queued `render` closure rebuilds the context with `refreshPreviewProject()`
109+
before rendering. A dirty flag, not a queued job, because the render queue is
110+
enqueued with `clearPending` and could drop a standalone rebuild job; the flag
111+
is cleared before the rebuild awaits and restored if the rebuild fails, so a
112+
change landing mid-rebuild is not lost. `refreshPreviewProject()` rebuilds the
113+
way `cmd.ts` built the context, cleans up the old context only once the new
114+
one exists, and keeps the old context (logged) when the rebuild fails.
104115

105116
## Render Request Compatibility Check
106117

@@ -178,6 +189,27 @@ serve.ts ── renderProject(watcher.project(), [input])
178189
mismatch. The two layers are complementary, not redundant: the guard refreshes
179190
only `fullMarkdown`; `invalidateForFile` refreshes all fields.
180191

192+
### Extension changes and context swaps (#15266)
193+
194+
An extension-file change (for example an `_extension.yml` edit) counts as a
195+
config change in `handleWatchEvent`, so `watcher.project()` is refreshed and
196+
the next render uses the newly contributed project metadata. When an
197+
extension file shares a poll event with changed inputs, the queued render
198+
refreshes the context in its own queue slot first, before the
199+
`invalidateForFile` loop.
200+
201+
Every context swap in project preview runs on `ServeRenderManager`'s queue:
202+
the refresh calls `cleanup()` on the old context, which closes its disk cache
203+
and deletes transient `.quarto_ipynb` files, and running that outside the
204+
queue could race an in-flight render. `ServeRenderManager.submit()` queues
205+
such non-render tasks (the PDF reload path, the `changes.config` path, and
206+
the HTTP handler's `refreshProject()`) alongside renders; it must never be
207+
called from inside a queued task, because `PromiseQueue` deadlocks on nested
208+
submission. The refresh itself (`refreshProjectContext`) builds the new
209+
context with a fresh `ExtensionContext`, because the preview's long-lived
210+
render services cache `_extension.yml` per directory and would return the
211+
startup version.
212+
181213
### Out of scope for #10392
182214

183215
The freshness guard fingerprints the edited input file itself. It does NOT detect
@@ -302,6 +334,8 @@ When rendering a `.qmd` with a Jupyter kernel, the engine creates a transient `.
302334
| Project: single input changed | — | 1 (watcher render() without pContext) + 0 (serve.ts HTTP-handler renderProject reuses persistent ctx) |
303335
| Project: multiple inputs changed | — | 0 new (watcher renderProject reuses cached) |
304336
| Project: config file changed (HTML) | — | 1 (refreshProjectConfig) |
337+
| Single file: extension file changed | — | 1 (refreshPreviewProject, before the queued render) |
338+
| Project: extension file changed (HTML) | — | 1 (refreshProjectConfig, on the render queue) |
305339

306340
The single-input row's `+ 0` reflects two render invocations but only one new
307341
context computation: the watcher render builds a fresh context, while the

‎news/changelog-1.12.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ All changes included in 1.12:
1616
### `quarto preview`
1717

1818
- ([#14783](https://github.com/quarto-dev/quarto-cli/issues/14783)): Fix `quarto preview` ignoring project metadata contributed by an extension, such as `brand`. Contributed project metadata now applies to every command that builds a project context, `quarto inspect` included. (author: @mcanouil)
19+
- ([#15266](https://github.com/quarto-dev/quarto-cli/issues/15266)): Fix `quarto preview` keeping the project metadata an extension contributed at startup, such as `brand`, after its `_extension.yml` changes.
1920

2021
## Other fixes and improvements
2122

‎src/command/preview/preview.ts‎

Lines changed: 59 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -169,9 +169,10 @@ export async function preview(
169169
// Reuse the project context from cmd.ts if provided, avoiding redundant
170170
// context creation and transient notebook file duplication (#14281).
171171
const nbContext = pProject?.notebookContext ?? notebookContext();
172-
const project = pProject ??
172+
let project = pProject ??
173173
(await projectContext(file, nbContext)) ??
174174
(await singleFileProjectContext(file, nbContext));
175+
let extensionsChanged = false;
175176
onCleanup(() => {
176177
project.cleanup();
177178
});
@@ -184,6 +185,19 @@ export async function preview(
184185
// render for preview (create function we can pass to watcher then call it)
185186
let isRendering = false;
186187
const render = async (to?: string) => {
188+
// An extension file changed since the last render: rebuild the context
189+
// first so the render uses the newly contributed metadata. The flag is
190+
// cleared before the await (a change landing during the rebuild sets it
191+
// again) and set back if the rebuild fails, so no change is lost.
192+
if (extensionsChanged) {
193+
extensionsChanged = false;
194+
const next = await refreshPreviewProject(file, project);
195+
if (next === project) {
196+
extensionsChanged = true;
197+
} else {
198+
project = next;
199+
}
200+
}
187201
const renderFlags = { ...flags, to: to || flags.to };
188202
const services = renderServices(nbContext);
189203
try {
@@ -234,6 +248,11 @@ export async function preview(
234248
reloader,
235249
render,
236250
options[kProjectWatchInputs]!,
251+
undefined,
252+
undefined,
253+
() => {
254+
extensionsChanged = true;
255+
},
237256
);
238257

239258
// create file request handler (hook clients up to reloader, provide
@@ -247,11 +266,11 @@ export async function preview(
247266
options.port!,
248267
reloader,
249268
changeHandler.render,
250-
project,
269+
() => project,
251270
)
252271
: project && !project.isSingleFile
253272
? projectHtmlFileRequestHandler(
254-
project,
273+
() => project,
255274
normalizePath(file),
256275
flags,
257276
result.format,
@@ -265,7 +284,7 @@ export async function preview(
265284
result.format,
266285
reloader,
267286
changeHandler.render,
268-
project,
287+
() => project,
269288
);
270289

271290
// open browser if this is a browseable format
@@ -301,6 +320,27 @@ export async function preview(
301320
await server.finished;
302321
}
303322

323+
// Rebuild the preview's project context the way cmd.ts built it, so metadata
324+
// an extension contributes reaches the next render after _extension.yml
325+
// changes. A failed rebuild (e.g. a broken _quarto.yml saved during preview)
326+
// keeps the previous context, and the old context is cleaned up only once
327+
// the new one exists.
328+
export async function refreshPreviewProject(
329+
file: string,
330+
project: ProjectContext,
331+
): Promise<ProjectContext> {
332+
try {
333+
const next =
334+
(await projectContext(dirname(file), project.notebookContext)) ??
335+
(await singleFileProjectContext(file, project.notebookContext));
336+
project.cleanup();
337+
return next;
338+
} catch (e) {
339+
logError(e);
340+
return project;
341+
}
342+
}
343+
304344
export interface PreviewRenderRequest {
305345
version: 1 | 2;
306346
path: string;
@@ -548,6 +588,7 @@ export function createChangeHandler(
548588
renderOnChange: boolean,
549589
reloadFileFilter: (file: string) => boolean = () => true,
550590
ignoreChanges?: (files: string[]) => boolean,
591+
onExtensionChange?: () => void,
551592
): ChangeHandler {
552593
const renderQueue = new PromiseQueue<RenderForPreviewResult | undefined>();
553594
let watcher: Watcher | undefined;
@@ -607,7 +648,10 @@ export function createChangeHandler(
607648
// the changes as they do w/ e.g. css files)
608649
watches.push({
609650
files: result.extensionFiles,
610-
handler: ld.debounce(renderHandler, 50),
651+
handler: ld.debounce(async () => {
652+
onExtensionChange?.();
653+
await renderHandler();
654+
}, 50),
611655
});
612656

613657
// reload on output or resource changed (but wait for
@@ -707,7 +751,7 @@ function previewWatcher(
707751
}
708752

709753
function projectHtmlFileRequestHandler(
710-
context: ProjectContext,
754+
project: () => ProjectContext,
711755
inputFile: string,
712756
flags: RenderFlags,
713757
format: Format,
@@ -716,14 +760,15 @@ function projectHtmlFileRequestHandler(
716760
) {
717761
return httpFileRequestHandler(
718762
htmlFileRequestHandlerOptions(
719-
projectOutputDir(context),
763+
// output-dir is fixed at startup; a refresh never changes it
764+
projectOutputDir(project()),
720765
"index.html",
721766
inputFile,
722767
flags,
723768
format,
724769
reloader,
725770
renderHandler,
726-
context,
771+
project,
727772
),
728773
);
729774
}
@@ -735,7 +780,7 @@ function htmlFileRequestHandler(
735780
format: Format,
736781
reloader: HttpDevServer,
737782
renderHandler: (to?: string) => Promise<RenderForPreviewResult | undefined>,
738-
context: ProjectContext,
783+
project: () => ProjectContext,
739784
) {
740785
return httpFileRequestHandler(
741786
htmlFileRequestHandlerOptions(
@@ -746,7 +791,7 @@ function htmlFileRequestHandler(
746791
format,
747792
reloader,
748793
renderHandler,
749-
context,
794+
project,
750795
),
751796
);
752797
}
@@ -759,7 +804,7 @@ function htmlFileRequestHandlerOptions(
759804
format: Format,
760805
devserver: HttpDevServer,
761806
renderHandler: (to?: string) => Promise<RenderForPreviewResult | undefined>,
762-
project: ProjectContext,
807+
project: () => ProjectContext,
763808
): HttpFileRequestOptions {
764809
// if we an alternate format on the fly we need to do a full re-render
765810
// to get the correct state back. this flag will be set whenever
@@ -790,7 +835,7 @@ function htmlFileRequestHandlerOptions(
790835
prevReq &&
791836
existsSync(prevReq.path) &&
792837
pathsEqual(prevReq.path, inputFile) &&
793-
await previewRenderRequestIsCompatible(prevReq, project, flags.to)
838+
await previewRenderRequestIsCompatible(prevReq, project(), flags.to)
794839
) {
795840
// don't wait for the promise so the
796841
// caller gets an immediate reply
@@ -838,7 +883,7 @@ function htmlFileRequestHandlerOptions(
838883
let renderFormat = format;
839884
if (project) {
840885
const input = await inputFileForOutputFile(
841-
project,
886+
project(),
842887
relative(baseDir, file),
843888
);
844889
if (input) {
@@ -901,7 +946,7 @@ function pdfFileRequestHandler(
901946
port: number,
902947
reloader: HttpDevServer,
903948
renderHandler: () => Promise<RenderForPreviewResult | undefined>,
904-
project: ProjectContext,
949+
project: () => ProjectContext,
905950
) {
906951
// start w/ the html handler (as we still need it's http reload injection)
907952
const pdfOptions = htmlFileRequestHandlerOptions(

‎src/project/serve/render.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,18 @@ export class ServeRenderManager {
3737

3838
public submitRender(render: () => Promise<RenderResult>) {
3939
return HttpDevServerRenderMonitor.trackInFlight(
40-
this.renderQueue_.enqueue(render),
40+
this.renderQueue_.enqueue(render) as Promise<RenderResult>,
4141
(result) => !result.error,
4242
);
4343
}
4444

45+
// Queue a non-render task (e.g. a project context refresh) on the render
46+
// queue so it cannot overlap an in-flight render. Never call this from
47+
// inside a queued task: PromiseQueue deadlocks on nested submission.
48+
public submit<T>(task: () => Promise<T>): Promise<T> {
49+
return this.renderQueue_.enqueue(task) as Promise<T>;
50+
}
51+
4552
public isRendering() {
4653
return this.renderQueue_.isRunning();
4754
}
@@ -125,5 +132,5 @@ export class ServeRenderManager {
125132
}
126133

127134
private fileRenders_ = new Map<string, string>();
128-
private renderQueue_ = new PromiseQueue<RenderResult>();
135+
private renderQueue_ = new PromiseQueue<unknown>();
129136
}

0 commit comments

Comments
 (0)