Webview pages

Status: current. This page describes the webview pages as they stand after Phase 7, the last phase of the refactor plan. Phase 6 moved every page to a bundle.

How pages are built

Every page is a shell its host writes and a bundle that draws it. Nine pages draw with Preact on the shared core: Stats, the Task Board, the search page, Related Notes, both calendars, the Notes Graph, the Dashboard, and the note page (its plan). Help’s script is a typed module with no Preact that moves around the body its host builds from the manifest, and the Related Notes debug page is HTML its host builds, with no script at all. Each bundle is built from src/webview/<page>/ and loaded by URI under the page’s nonce (Bundling and loading); its code is type-checked against the DOM, and imports only its own folder, webview/shared, the protocol, the domain modules D1 names, and Preact (layers.md). docs/components.md documents the components a page draws with.

The nine scripts come to 586.2 KB minified, 195.2 KB with gzip (the table); the host’s dist/extension.js is 944.3 KB.

Before Phase 6, each host function wrote its page’s script as one template literal, which interpolated a shared component script of 105.9 KB, and on three pages a 67.8 KB query editor script, as untyped text; the Dashboard rendered to 339.8 KB. The compiler never saw page code, so test/ui/checkWebviewScripts.js extracted it by regex and type-checked it with strict: false. Every redraw assigned app.innerHTML, and renderKeepingPlace put back the focus and scroll each redraw lost. Until step 3, seven of nine builders hand-wrote their CSP, and the copies had drifted. Step 7 deleted what was left of that model: the template builders in src/ui/webview/components.ts and checkWebviewScripts.js. The suites that held the shared components to the template now hold them to recordings of it (The shared core).

The shape every well-made extension shares

The research read the official guide and samples and the webview source of GitLens, GitHub Pull Requests, Jupyter, Azure Cosmos DB, and DocumentDB. Seven patterns hold across all of them, and Deckard adopts all seven:

1. Page code is real TypeScript, bundled, and loaded through asWebviewUri.
2. The HTML template is tiny.
3. A host base class owns the panel lifecycle.
4. Initial state reaches the page as inert data or by a ready handshake, never as JSON inside a script.
5. Message types live in one module imported by both sides.
6. Tests are two-tier: a fast tier under jsdom, and a slow tier in a real VS Code.
7. Rendering is declarative, and CSS is authored as files.

The host side

As built in Phase 6 step 2. Host code lives in src/ui/webview/host/, and each page’s controller and narrowing table in src/ui/webview/pages/<page>/. All nine pages run on it: Stats moved in 2.1, and the other eight in 2.2 to 2.10, by the recipe in the next section. The base then gained what those moves needed, so no controller works around it.

What a controller tells its host

Every option and hook is optional, and a page that sets none behaves as Stats does.

NavigationService (src/services/navigationService.ts) says what openSource and openTag may open. Each page’s rule today is a named policy: entries (Home), graphNodes (the Notes Graph), tasks (the Task Board), and notes (Stats) for a line; and lenient (Stats, Home, a search page, Related Notes) and exact (the Task Board, the Notes Graph) for a tag. test/e2e/navigation.e2e.js pins all six against the hosts.

A message handler is an adapter under the rules in services.md. A message several pages send gets one shared handler only where those pages act on it identically today. Where pages differ, as Stats and a search page do on mergeTags, each page keeps its own handler, so moving a host changes nothing a reader sees. The same goes for narrowers: one used by a single page lives in that page’s table.

src/test/fakeWebview.ts holds a FakeWebview, with only postMessage and onDidReceiveMessage, and a FakeSurface around it. A host-controller test attaches a WebviewHost to a FakeSurface, sends messages with await surface.webview.send(...), and reads what the host posted in surface.webview.posted.

Moving a host onto WebviewHost

This is the recipe Stats followed in 2.1, and steps 2.2 to 2.10 after it, each moving one host on its own branch while the others moved theirs. A move changes nothing a page receives, nothing any message does, and no line the log writes. In step 2 the pages still served their template HTML, so npm run test:dom stayed identical.

What a page owns

Steps

1. Read the host and its parser to the line. For each message, write down its parser case (including every Object.keys(value).length check and every field it copies or passes through), what the handler reads, the index snapshot it reads, and each effect in order. For the session, write down the panel’s view type, title, icon, and creation options, and what attachPanel sets and listens to, in order. Note what the chrome subscription does, what refresh() does when hidden and when visible, what runs after the post, and what show, restore, and dispose do.
2. Protocol maps. In protocol/<page>.ts, declare the two maps and define the old union as MessageOf<...>. The shapes come from protocol/messaging.ts: MessageMap, MessageOf, MessageAs (one type of a message that serves several, listed under each, such as parkTag: MessageAs<ParkTagMessage, 'parkTag'>), StateMessage, IndexingMessage, and Correlated (the request id a request and its answer share, such as moveTask and moveRefused).
3. Narrowing table. Use a shared narrower only where it accepts and returns exactly what the old case did: narrowSetZenMode, narrowOpenSource (it rebuilds the message with beside and pin only when true, which openResultAt and openSourceAt treat as the same as a passed-through message), narrowOpenTag, narrowRenameTag, narrowParkTag, narrowToggleTask, narrowPinNote (today’s parsePinMessage), narrowOpenSearch, narrowExportResults, onlyType(type) (any extra fields), and exactlyType(type) (no extra fields). A check that serves two types is listed under each with narrowAs, as in unparkTag: narrowAs('unparkTag', narrowParkTag), and a request id is checked with isRequestId. Write anything else in the page’s own table. A case that used to pass the whole record through with as unknown as returns the record rebuilt from the fields its handler reads.
4. Controller. Set its name to the name the host gave onIndexUpdateInTurn. If it gave measure another name, or timed more or less than building the snapshot, say so in options.measure, so the log reads as it did. Set its options (retainContextWhenHidden and enableFindWidget as created today) and html(webview, chrome) (the page’s get*Html, handed the theme and zen its host read). Set buildSnapshot() to what refresh() posted as data. Set subscribe(page) to every other listener that called refresh(), in the order the host registered them; the host’s theme and zen listener comes before all of them. Then write one handler per map key. Take a shared handler wherever the old branch matches it, and use the NavigationService policy this page has today for openSource and openTag. Keep each comment that says why, next to its handler.
5. Host class. Build the controller and a WebviewHost with { indexer, themePreview }, and wrap them in a PanelAdapter (view type, title, extension URI, icon path) or a ViewAdapter. Forward the public methods. Construct new NavigationService() there; it holds no state. composition/services.ts, test/harness/modules.js, and the e2e suites should need no change.
6. Delete the parser from messages.ts, with any constant or helper only it used. Move its tests (step 3’s file), including any in other suites, such as Stats’ merge test in tag-hygiene.test.ts.
7. Check. Run npm run check-types && npm run lint, then npm run lint:baseline. Its diff must only remove lines. Then run the page’s unit, host, and e2e suites, node test/e2e/run.js navigation.e2e.js, and npm run test:dom. A host suite also runs without VS Code, under node node_modules/mocha/bin/mocha.js --ui tdd --require test/e2e/support.js out/test/<page>-host.test.js; src/test/timingLog.ts captures what a refresh logs, and src/test/configurationEvents.ts fires one settings change that touches several settings. Run the full set before handing the branch back.

What each host needs beyond Stats

Each host does some things Stats does not. These are the options and hooks each page now sets.

What not to touch

• Another page’s files, and messages.ts beyond your own parser’s region. The hot spots (composition/services.ts, test/harness/modules.js, messages.ts, and messages-rendering.test.ts) are merged by hand, so keep your edits to them small and in one place.
• src/ui/webview/host/ and src/services/navigationService.ts. If a page needs something the base does not have, add it in a separate first commit. Make it an option or a hook that changes nothing for a page that does not set it, with a test in webview-host.test.ts. Do not change what an existing option or policy does. A controller does not work around the base: in step 2 each page that did (a measure under one name, its own theme listener, a settings listener outside subscribe, a refresh wrapper, its own surface) was given the option or hook above instead.
• The policies. No page changes which lines or tags it accepts, even where the rules look like they should agree. Unifying them is a behavior change for a later step.
• The template HTML and the page scripts. Step 2 changes no DOM, so test/ui/dom-baseline/ is never re-recorded here.
• The pinning suite. navigation.e2e.js must pass unchanged, on every branch.

The protocol

src/ui/protocol/<page>.ts declares each page’s HostToPage and PageToHost message maps and its snapshot type. Both the host and the page import it, so a renamed field fails to compile on both sides. The shape follows vscode-messenger: each message is declared once as a request or a notification. A request and its response share a request id, as moveTask and moveRefused do on the Task Board and the calendar page.

Page-to-host messages are untrusted, so the host narrows each one before handling it. The narrowing is hand-written, as in every surveyed extension, in one table of per-message functions shared across pages. It replaces the check-then-cast parsers in messages.ts. No validation library is added; see decision 0004.

Bundling and loading

As built in Phase 6 step 3. esbuild.js has two contexts. node esbuild.js builds both, --production minifies them, --watch watches them, and --webview (npm run build:webview) builds the pages alone.

The page context compiles JSX with the automatic runtime and jsxImportSource: 'preact'. Its output folder is emptied before each build, so a removed page leaves no bundle behind, and with no page entries it builds nothing and still succeeds. Each build writes its esbuild metafile to out/extension-meta.json or out/webview-meta.json, which never ship. scripts/check-bundle-inputs.js reads them: the host bundles may take in only markdown-it and its five packages and picomatch (the list only shrinks: it held 23 packages when the check arrived, and step 6 removed sanitize-html and the 15 it brought), a page’s script only Preact, and a page’s sheet nothing. CI runs it after packaging the VSIX.

src/webview/tsconfig.json type-checks page code against the DOM, with no Node types, strict and noEmit. It also lists the domain modules a page may import (D1 in layers.md), so they are held to the browser’s types before a page imports one. The root tsconfig.json leaves src/webview to it, and npm run check-types runs both. ESLint lints .tsx with the rules for .ts, and forbids preact/compat and react in src/webview. Preact 10.29.8 is a pinned dependency, and each Preact page’s bundle carries its own copy, with what it uses of the shared core; see One bundle per page.

Stats (src/webview/stats/main.tsx), the Task Board (src/webview/taskBoard/main.tsx), the search page (src/webview/searchPage/main.tsx), Related Notes (src/webview/sidebarNotes/main.tsx), the Calendar view (src/webview/calendar/main.tsx), the calendar page (src/webview/calendarPage/main.tsx), the Notes Graph (src/webview/notesGraph/main.tsx), the Dashboard (src/webview/dashboard/main.tsx), and Help (src/webview/help/main.ts) have script entries, built to dist/webview/stats.js, taskBoard.js, searchPage.js, sidebarNotes.js, calendar.js, calendarPage.js, notesGraph.js, dashboard.js, and help.js. The Related Notes debug page has no entry, since it runs no script. The two calendars are two entries over src/webview/shared/calendar/. What step 3 moved is the CSS and the document around the body. Every builder returns buildPageShell({ webview, extensionUri, page, title, nonce, theme, zen, csp, bodyAttributes, body, bundle, state }), which writes:

1. the policy getContentSecurityPolicy builds (next section);
2. for a page with bundle, <meta name="deckard-theme" content="…">, the theme’s name, which ⋯’s theme row reads (readThemeName);
3. <link rel="stylesheet"> for dist/webview/<page>.css, then themes/<theme>.css, then tail.css, each through asWebviewUri, in that cascade order;
4. <body>, with class="zen" when zen is on and any attributes the page adds, such as Help’s anchor, around the body the builder wrote;
5. for a page with bundle, at the end of the body: the snapshot, when state is given, as <script type="application/json" id="state"> with every < written \u003c (inertJson), then <script nonce src> for dist/webview/<page>.js.

A bundled page’s body is its <main id="app">, holding the loading line when the shell carries no snapshot and empty when it does, and the #live-status node. The Notes Graph’s body is empty: its template wrote the canvas and its panels straight into the body, with no #app, so its page draws the whole body (see The Notes Graph).

The theme and zen come from the page’s host: WebviewHost reads them with readPageChrome(themePreview) as it writes the page, and the controller hands them to its builder as chrome, a PageChrome (components.ts). getPageTailCss(chrome) names the sheets after the page’s own and the body’s class, so neither a builder nor the shell reads a setting, and a page’s catalog suites run under test:unit. Each webview’s localResourceRoots is [dist/webview, resources], from pageResourceRoots in host/surface.ts, set wherever its options are set: the panel and view adapters, the search pages, and Related Notes. A builder therefore takes the extension’s folder, and so do the controllers and CalendarView and SidebarNotesView, which hand it on.

The page loader, test/harness/loadPage.js, inlines each linked sheet as it inlines a bundle, so every harness still sees a self-contained page. A sheet’s url() is resolved against the sheet’s URI, as the browser does, and the page nonce is added to style-src for a sheet the policy admits by its origin, so Chrome in the layout harness lets the inline copy through exactly when VS Code would let the link through.

The built pages in development, and minified for the VSIX:

Each page’s sheet carries the base sheet, about 28 KB of it in development; a page loads its own sheet, one theme, and the tail. The development build writes a source map beside each sheet; .vscodeignore keeps every .map out of the VSIX.

A page with a script entry passes bundle: true, and the shell writes <script nonce src> for dist/webview/<page>.js last in the body, after the page’s inert state when it has one.

The pages’ scripts

Measured at the end of Phase 6, from node esbuild.js --production, the build the VSIX ships, with gzip at level 9:

Each Preact page’s script carries Preact and what it uses of the shared core (One bundle per page); Help’s carries neither. scripts/check-bundle-inputs.js holds every page’s script to Preact alone.

Help is the one page with no Preact (Q6 of the Phase 6 plan). Its body stays the HTML the host builds from the manifest, and its script, src/webview/help/main.ts, is a typed module that only moves around in it: the rail, the guide view, and the way back. The guide view sets the HTML of a guide page, rendered by the host through markdown.api.render from the guide the VSIX ships, in one documented assignment. Help is not retained when hidden; it saves { guide?: { page, anchor? }, scrollY, drawn } with setState, and a page shown again asks for its guide page and scrolls back. drawn is a hash of the nonce the HTML was drawn with, so a state saved by an earlier drawing (a theme change, a section asked for while hidden, a window reload) is not read, and those open where they always have. The official guide calls external files the best practice, and every surveyed extension loads its bundle this way; see decision 0001.

One bundle per page

Measured in Phase 6 step 4.2, on Stats, the first Preact page, and again in step 4.5, once the search page and the Task Board shared the query editor; recorded as decision 0016. Open question 3 asked whether the pages share one bundle of Preact and the shared core, or each carry their own. Two variants of Stats were built by scripts/measure-page-bundles.js:

• A, one bundle per page: stats.js holds Preact, what Stats uses of src/webview/shared, and the page.
• B, a shared bundle: shared.js holds Preact and all of src/webview/shared as one iife global, and an esbuild plugin maps the page’s imports to it, so stats.js holds only the page. The shell loads shared.js first.

The rule was set before the numbers: B only if it saves more than 100 KB in the VSIX, or more than 10 ms of Chrome first render on a page; otherwise A, which is one request per page and needs nothing new in the loader.

The shares are of the minified bytes, from esbuild’s metafile. B’s shared bundle carries more of both Preact and the core than A’s page does, because nothing in it can be left out: it exports everything for pages that are not built with it.

The VSIX vsce packed was 1,473.3 KB. A first render runs from the start of the page’s document to its state drawn and laid out. Chrome’s is timed in real time, since virtual time does not advance while a script runs. On macOS, Chrome 153.

Decision: A. With one Preact page, B cannot save anything: it ships 6.6 KB more and draws 3.7 ms later, and jsdom’s 1.3 ms is within its run-to-run spread. The build keeps one bundle per page. The question is measured again at Search, the first time two moved pages share the query editor, and then recorded as a decision.

Measured again at Search (step 4.5), with the same script, on the search page, the Task Board, and Stats. --together swaps every Preact page’s bundles in the VSIX at once, B with one shared.js for all five, which is what B would ship.

The VSIX vsce packed was 1,546.3 KB. On macOS, Chrome 153.

Decision: A, again (0016). B saves 45.5 KB of the VSIX, under half the rule’s 100 KB, and draws every page measured 3 to 5 ms later in Chrome, since its shared bundle holds all of the core for whichever page loads it. Related Notes and the Dashboard, the pages still to move, will raise B’s saving; if it ever crosses 100 KB, the question is measured again with this script and rule.

The Content Security Policy

As built in Phase 6 step 3. Every page’s policy is built by getContentSecurityPolicy(cspSource, nonce, extras) in host/pageShell.ts, so no policy can drift from the others. style-src is the extension alone, since no style is inline any more. Scripts need the page nonce. extras (ContentSecurityExtras) adds images from the extension and the origins it lists, or from any HTTPS origin for images: true; fonts from the extension; or, for scripts: false, no script-src at all.

No page loads a font, so none is granted font-src.

Only Chrome enforces the policy. jsdom ignores CSP entirely: a script with the wrong nonce ran in the probe. So the headless-Chrome srcdoc harness in test/ui/checkLayout.js is the one place a CSP regression can show. A srcdoc document inherits its parent’s policy, so from Phase 0 the harness’s parent page carries the intended CSP rather than stripping it.

State

Initial state. A Preact page reads a snapshot its shell carries as <script type="application/json" id="state">, with < escaped, and draws it on its first frame with no loading line; no JSON is ever interpolated into executable script. Updates arrive as postMessage({ type: 'state' }), the entry point the tests already drive. See decision 0005.

When the shell carries one is Q3 of the sub-plan: a page’s HTML embeds a freshly built snapshot only when the build is cheap, under 50 ms median on the 5,000-note bench, read from the measure line its host writes (npm run bench:index reports Stats’). Otherwise the page opens on its loading line, with the indexing count until the first scan ends, and the host posts the snapshot, as before. Stats builds in 150 ms there (65 ms on 1,000 notes), the Task Board, on the search it opens with, is:open, in 230 ms (47 ms on 1,000; Task Board snapshot in the bench, step 4.4), a search page in 182 ms on the page a tag opens and 133 ms on a search of every note (31 and 19 ms on 1,000; Search page snapshot in the bench, step 4.5), and Home, with the widgets it starts with, in 394 ms (90 ms on 1,000; Dashboard snapshot, Home in the bench, step 4.7), so all four open on their loading lines and nothing builds their snapshots into HTML. A page under 50 ms sets options.embedsSnapshot: whenever its HTML is set while it is shown and the index has notes, the host builds its snapshot, timed as a sent one is, and hands it to html. The Calendar view’s month builds in 15 ms there (3.3 ms on 1,000), and the calendar page’s month with its day panel in 37 ms (6.3 ms), so both calendars’ HTML carries their month; each still says ready when it loads, as it always has, and is sent a snapshot then. The Notes Graph’s whole-workspace graph builds in 1,412 ms there (229 ms on 1,000), and its message is about 40 MB, so its HTML carries none: it never had a loading line, and it is posted its graph as before. Related Notes ranks the whole workspace for its note: 1,924 ms on 5,000 notes and 185 ms on 1,000 (Related Notes snapshot in the bench, step 4.6, for the note and what links to it), so it opens on its loading line too, and is posted its state as before.

A page that reads inert JSON says so with options.readsInertState. controller.html(webview, chrome, state) is then handed a snapshot to carry when there is one. test:dom draws each surface of such a page twice, posted and embedded, and holds the two to one DOM (readsInertState in the page catalog).

A hidden page that is not kept running (Q2). VS Code throws away a hidden webview’s page unless it is retained, and loads its HTML again when it is shown. So when a page that reads inert JSON and is not retained is hidden, its host sets its HTML once more, carrying the last snapshot it sent: the one kept, not built again. Shown, the page draws that at once, and the stale refresh sends a newer one only if the page missed one. A theme change while it is hidden carries the snapshot too; a newly attached panel carries nothing a closed one was sent. What the page itself chose comes back from setState.

retainContextWhenHidden. In step 2 all nine webviews kept it. Stats dropped it in step 4.2 (Q1); its three choices and its scroll position are kept with setState as { showAllOrphans, showUsedOnce, pairsAsTable, scrollY }, each choice when the reader makes it and the scroll at most every 200 ms, and a value that is not true reads as off. Both calendars dropped it in step 4.3: the calendar page keeps { layout, scrollY }, its layout as before and its scroll as Stats keeps its own, and the Calendar view keeps nothing, as before; each is drawn again from its last month when hidden (Q2). Related Notes dropped it in step 4.6: hidden, it is drawn again from the last state it posted, and it keeps what the reader chose in it, which retain used to keep while it was hidden, with setState as { noteLimit, noteListKey, showEveryActiveTag, contextOpen, linksOpen: { linked, mentions }, openLinkSections, expandedRefine, shownGroups, scrollY }: how many results Show more has drawn and for which list, the note’s tags all shown, the context and the Links groups open, the link rows unfolded, the Refine facets opened past five, the calendar day’s groups shown whole, and the scroll, after each draw and each fold, and the scroll at most every 200 ms. A value of the wrong kind reads as a new view’s choice. The relevance breakdown, the gear, and the tag menu are not kept, as a draw closed them before. The Related Notes debug page dropped it in step 4.9: it runs no script and keeps nothing, so shown again it is the HTML it was last given, the same evidence, at the top and with every calculation folded. Q1 keeps it on the Dashboard, Search, the Task Board, and the Notes Graph. The Task Board, a Preact page since step 4.4, keeps it, and keeps { query, scrollY } with setState as its template did: the search on each snapshot, and the scroll only while the search is the one it was scrolled in; and tasksViewMode: true while it edits what the Tasks view lists, which its host reads to reopen it so. A search page, a Preact page since step 4.5, keeps it for the search half built in its box, and keeps { query, origin, scrollY?, tab? } as its template did: the search and the one it opened with on each snapshot, the scroll only while the search is the one it was scrolled in, and the tab only once the reader chose one; its host reads the same record, and the shapes older releases wrote, to restore it. The Dashboard, a Preact page since step 4.7, keeps it for Home’s search box and for arranging Home, and keeps { dashboardMode, tagColumns, browseQuery, tagNamespaceFilter, editingHome, homeHintDismissed } with setState as its template did: the whole record whenever the reader changes one of them, read back as the template read it (the tab only as browse, the columns only as 1 to 4, anything else as nothing kept), and browseQuery written as the Tags tab’s search is typed and never read back. The Notes Graph, moved in step 4.8, keeps it so its simulation does not restart on every reveal; it keeps its 12 settings and its camera with setState, for a reload, read back as its template read them (row 23 of the persisted-formats inventory, which listed 23 before the layout’s eleven were fixed). The guide calls it the exception, with high memory overhead, so it stays only on those four pages, each for the reason decision 0017 gives. Other UI state, such as scroll, selection, and open sections, goes into setState, so the serializers restore it. The stale refresh on onDidChangeViewState stays everywhere. The API documentation and the guide disagree on whether a hidden retained webview receives messages, and the refresh is correct either way. See decision 0017, which supersedes 0006.

VS Code hands a page’s saved setState back after a restart, so a page restored after an upgrade reads state the old script wrote. Those shapes are persisted formats, listed in inventories/persisted-formats.md.

Rendering with Preact

Each page is a tree of TSX components that render from the snapshot. Preact diffs and patches only what changed. That removed the full-page innerHTML redraw, renderKeepingPlace, and the in-page escapeHtml, since text becomes text nodes by construction. esbuild compiles TSX natively, so tsc type-checks the markup with no plugin. See decision 0002.

Two guards apply:

• Pin 10.29.x exactly. Preact 11.0.0 shipped on 2026-09-30 and has no track record yet.
• Never import preact/compat. The React-compatibility layer then never ships, and a later move to React stays a rename the compiler drives.

Preact renders into the light DOM, not a shadow root. Document-level theme CSS does not cross a shadow root except through inherited and custom properties. jsdom has never implemented adoptedStyleSheets. The light DOM keeps the eight themes, the high-contrast sheets, and the layout, contrast, and visual tests working unchanged.

Domain logic left page script. The graph’s clustering and salience, the Home widget catalog, calendar arithmetic, board status validation, tag-key parsing, and the Help manifest interpreter are typed modules: host-side where the host owns the decision, and among the domain modules D1 names where the page computes for itself. Click handlers go through one dispatchAction over a Record<string, handler>.

The shared core

As built in Phase 6 step 4.2. Every Preact page starts from src/webview/shared, written with Stats and held, component by component, to the template script it replaced: src/test/webview-shared.test.ts draws each one through the core bundled as esbuild builds a page, and requires the DOM the template’s helper drew, node for node. Since step 7 deleted the template, the helper’s side is a recording of it, taken before the deletion (src/test/templateRecords.ts).

The token types live in domain/model/inline.ts and blocks.ts, since the protocol imports only the domain model; ui/protocol/inline.ts re-exports the two the pages name, InlineToken and BlockToken, since a page may import the protocol but not the model.

Lane B’s shared components are in src/webview/shared/calendar/, written with the Calendar view and held to the template script they replaced:

The date steps both calendars take are domain/markdown/calendar.ts’s (D1): shiftDate, isWeekend, skipWeekend, stepDate, sameDayIn, sameShownDayIn, chooseFocusDay, and stepCalendar.

The task and search parts

As built in Phase 6 steps 4.4 and 4.5, with the Task Board and the search page. Lane A’s pages share these, each held to the template it replaced, through the recording step 7 kept of it: src/test/webview-tasks.test.ts draws the task parts; src/test/webview-query-editor.test.ts runs the search box through the clicks, keys, and typing the template was driven through, and requires at each step the DOM, the searches, and the focus the template’s recording holds; and src/test/webview-search.test.ts draws every note excerpt of the sample corpus, the development notes, and the fixtures from its tokens and through markdown-it, and opens the tag menu the template opened.

Home and the Tags tab

As built in Phase 6 step 4.7. The Dashboard (src/webview/dashboard/) is drawn from one store on the shared core, and takes the shared parts lane A wrote: the query editor for Home’s search box, the task row, ranked rows for its tags and, while Home is arranged, its widgets, the metric for its three tiles, the page bar and its ⋯, and the undo toast. No other page draws a Home widget, so Home’s parts stay in its folder.

Which widgets there are, and what each can do, is domain/dashboard/widgetCatalog.ts’s WIDGET_KINDS, which the host’s preferences schema reads to keep a stored widget. The catalog also holds the limits the host keeps, how many widgets, entries, and characters, and which namespaces Gone quiet watches, so the page offers only what the host will keep; a tag key’s namespace is domain/markdown/tagKeys.ts’s, which the parser reads too (D1). A widget’s id is made on the page, so the new widget is drawn at once with its mark.

What the template did to the page outside a draw, the page still does, and squares with the next draw: the tag columns are laid out by script and their buttons marked at once, and listened to on the button so ⋯ stays open; a widget’s gear is open exactly when the reader left it open; and the widget just added is marked and focused after the state that shows it, and unmarked before the next draw, as every template draw dropped the mark until the next state. A select is given the value its template marked selected, which Preact puts back on every draw.

Related Notes

As built in Phase 6 step 4.6. Related Notes (src/webview/sidebarNotes/) is a view in the sidebar, drawn with startPage from one store holding the host’s last state. What the reader chose there, which the host never hears of, stays in one choices object of the page’s, as the template’s script kept it, and since the view is not kept running while hidden it is kept with setState too (State): how many results Show more has drawn and for which list, the note’s tags all shown, the context and the Links groups open, the link rows unfolded, the Refine facets opened past five, and the calendar day’s groups shown whole.

It draws the calendar’s day with lane B’s <DayPanel>, the tag menu, markWords with { wordStart }, and the shared core’s rail, tag label, and gear. Two things the template did to the DOM after a draw are put back before the next, so Preact finds the page as it drew it: the words each result shares with the note, marked in its excerpt after every draw, and a relevance breakdown its score opened, which every template draw closed.

The Notes Graph

As built in Phase 6 step 4.8. The Notes Graph (src/webview/notesGraph/) has no #app: its template wrote the canvas and its panels straight into the body. So main.tsx renders <GraphBody> (controls.tsx) into document.body, ahead of the script, with the template’s whitespace between elements as text nodes. It keeps one store and draws synchronously, as decision 0014 asks, but not through startPage: the indexing line, the busy mark, the disabled-click guard, and Escape’s provenance were never on the graph, so it installs the tip alone, and draws Reset’s Undo with <UndoNotice>.

Its groups and the links it draws are domain/graph/communities.ts’s (D1): buildCommunities, choosePrimaryTags, selectSalientEdges, tagMembershipScore, and graphEdgeSalience. Every module is a line-for-line port of the template’s script, its arithmetic in the same order, and its canvas calls are held to the template’s by recording them on the stepped clock.

The canvas is one element with a ref, outside what Preact changes: the frame loop sizes it and draws into it, and writes the zoom readout and Simulating, which Preact draws once; the pointer writes the tooltip’s contents into a box Preact draws empty, and the canvas’s own classes. Three things the controls do differently from a page drawn wholly from its store, each because the template did:

• The two search boxes are not controlled. Their settings follow typing after 150 ms, so a draw in between must not put the old text back; they are set only where the template set them, on load, Reset, and Undo.
• The Group list takes its value only where the template set it, so a group kept from before a graph arrives does not empty the list’s selection.
• Reset’s offer of Undo goes on any later input or change, heard before the control as the template heard it, but drawn by the control’s own handler: a draw before the handler would put a checkbox or slider back to the setting it is changing.

What a page written on the core has to know, learned on Stats, the calendars, the Task Board, the search page, the Notes Graph, and Related Notes:

• The old markup wins. Write the elements, attributes, and text nodes the template wrote, including the empty class="" a choice that is not active carried; test:dom and the recorded suites compare them.
• Key siblings of different kinds. Preact reuses an element at the same position. A reflected property it then takes away, such as id, is set to the empty string rather than removed, so a heading reused for another panel would keep id="". Stats keys its attention panels and its most-viewed panels.
• A reflected property is emptied, not removed. When a prop such as title, id, or placeholder goes from set to unset on an element Preact keeps, the element is left with title="". Key siblings that may trade places, as the task row keys each fact it can carry, and key a title by its HTML, so a title that changes is drawn afresh. Write spellcheck="false" through the spellCheck attribute: Chrome’s spellcheck property reads the string as true.
• A list the page changes outside a draw is drawn afresh. The Task Board moves a card at once, marks it completing, and drags cards and ranked rows; it keys those lists by a count of such changes (listsChanged in src/webview/taskBoard/model.ts), so the next draw makes them anew, as every template draw did, rather than patching elements the page moved. The search box puts back what it changes between draws, its completion lists and the buttons that need text, in afterRender.
• Write a run of words as the one text node the template wrote. test:dom merges adjacent text, but Chrome lays out the edge between two text nodes apart: the search page’s Tasks tab, drawn as Tasks and ` ( in two nodes, moved its glyphs a subpixel. Join the words in one string, as ${label} ( `.
• What a page changes after a draw, it undoes before the next. The search page marks the searched words after each state, replacing text nodes Preact made, and takes out a Show all whose body fits its three lines. Preact would patch, or insert beside, nodes that are no longer in the page, so the page puts both back before it draws again (markWords returns what does it), and Preact finds the page as it drew it. The draw then shows the words unmarked, as every template redraw did, until the next state marks them.
• A test reads a property where Preact writes one. A select’s chosen option is its selected property, which Preact sets; the template wrote the attribute. A test asks the option whether it is selected, which holds on both.
• What the DOM keeps outside props stays. Preact compares props with the last ones it wrote, not with the DOM, so a value a page sets directly, such as the pair grid’s roving tabindex, is not put back by a draw; Stats resets it in afterDraw, as each template redraw did. Focus on an element a draw keeps stays where it is, where the template’s redraw dropped it.

CSS and theming

As built in Phase 6 step 3. Every rule is in a .css file under src/webview, bundled by esbuild; the host builds no style text. Pages keep styling with --vscode-* variables, which is what Microsoft recommends since the webview toolkit was deprecated. The files were written once from the CSS functions they replace, checked equal to them for every page, theme, and zen state, and are maintained by hand.

A sheet names a file of the extension in url() by its path from dist/webview/, where it is served: the favorite heart is ../../resources/favorite-heart-outline.svg, which esbuild leaves as written. getPageTailCss takes the PageChrome ({ theme, zen }) as input instead of reading settings. The previewTheme global became a ThemePreview object owned by the composition root. A theme or zen change still resets the page’s HTML, which links the new theme.

What ships

Current since Phase 6 step 6. Preact is the one package the pages ship, and it runs in the sandbox, which has no file system and no network. The host bundle inlines markdown-it and its five packages, as the parser of note Markdown (decision 0015), and picomatch, which the Phase 0 exclude check kept: seven packages. Before step 6 it also inlined sanitize-html and the 15 packages it brought, postcss and htmlparser2 among them; the production dist/extension.js went from 1,169,906 bytes to 969,343 when they left, and to 966,943 when step 7 deleted the glyphs and the icon button only the template pages wrote. The pages’ scripts are in the table above.

Note Markdown in a card or title reaches the page as a token tree, drawn by an <Inline tokens> component as elements and text nodes. The host builds the tree in domain/markdown/inline.ts and blockExcerpt.ts by mapping the tokens of one markdown-it instance, configured as the retired rendering.ts configured its own, and never asks markdown-it for HTML. Nothing is parsed as HTML, so there is nothing to sanitize, and no snapshot carries HTML: renderedHtml, renderedTitle, and TableCell.html are gone. The Markdown preview’s query blocks write a title’s HTML themselves, from tokenizeInlineWithoutWikiLinks (the same instance, without the wiki-link rule, since the preview’s HTML has always been markdown-it’s reading), byte for byte what markdown-it and the sanitizer wrote. The Markdown previews and the debug page share one escapeHtml in src/shared/html.ts, with escapeHtmlText beside it for the query block’s text, which leaves quotes as written as the sanitizer did. See decision 0011.