@tinvar/renderer 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinvar/renderer",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "license": "MIT",
   "files": [
     "src",

package/src/client-deps.js

@@ -0,0 +1,25 @@
+// What the browser's dependency optimizer leaves alone in dev (ADR 0180).
+//
+// Vite bundles the packages the browser imports before it serves them.
+// @tinvar/react's client components are client references, which the RSC
+// plugin points the browser at by their own path; bundled into the
+// browser's @tinvar/react as well, a page loaded both copies, each with its
+// own React, and the first page of every new app failed with "Invalid hook
+// call" until Vite reloaded it. The plugin says so, as "client component
+// dependency is inconsistently optimized". Served as its own modules, the
+// package loads once. What it imports, React alone, is optimized as before.
+
+/** Served to the browser as their own modules, never optimized into a bundle. */
+export const NOT_OPTIMIZED = ['@tinvar/react'];
+
+/** @returns {import('vite').Plugin} */
+export function clientDependencies() {
+  return {
+    name: 'tinvar:client-dependencies',
+    apply: 'serve',
+    configEnvironment(name) {
+      // Merged with the app's own: Vite concatenates the lists.
+      return name === 'client' ? { optimizeDeps: { exclude: [...NOT_OPTIMIZED] } } : undefined;
+    },
+  };
+}

package/src/dev-app.js

@@ -15,6 +15,24 @@ export function useDevEntry(loader) {
   load = loader;
 }
 
+/** @type {() => string} */
+let head = () => '';
+
+/** Sets what the dev server adds to every document's head (ADR 0179). */
+export function useDevHead(markup) {
+  head = markup;
+}
+
+/**
+ * What the renderer adds before each document's `</head>` in dev: the link
+ * to StyleX's dev stylesheet, so a page is styled from its first paint
+ * rather than once its script has run. Asked at each render, since a
+ * restarted dev server may have StyleX where it had none.
+ */
+export function tinvarDevHead() {
+  return head();
+}
+
 async function entry() {
   if (load === null) throw new Error('The dev entry was imported before the dev server started.');
   return load();

package/src/dev-server.js

@@ -19,7 +19,7 @@
 import { createRequire } from 'node:module';
 import { existsSync, mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { useDevEntry } from './dev-app.js';
+import { useDevEntry, useDevHead } from './dev-app.js';
 import { assertDevelopment, DevServerRefused } from './dev-guard.js';
 import {
   actionsOf,
@@ -32,6 +32,7 @@ import {
   viewsOf,
 } from './vite.js';
 
+import { clientDependencies } from './client-deps.js';
 import { styleXDevStyles } from './stylex-dev.js';
 export { assertDevelopment, DevServerRefused, PRODUCTION_MARKERS } from './dev-guard.js';
 
@@ -89,6 +90,9 @@ export async function createDevServer({
   let listened = null;
   const restartListening = () => (listened ??= Promise.withResolvers()).promise;
 
+  // StyleX's rules for pages in dev (ADR 0179): served under the base,
+  // taken in by the client entry, and linked from each document's head.
+  const styles = styleXDevStyles(DEV_BASE);
   const vite = await createServer({
     root: appRoot,
     configFile: configFileOf(appRoot),
@@ -98,7 +102,8 @@ export async function createDevServer({
     clearScreen: false,
     ...(logLevel ? { logLevel } : {}),
     plugins: [
-      styleXDevStyles(DEV_BASE),
+      styles,
+      clientDependencies(),
       ignoreReplayedChanges(watchedFrom),
       followRestarts(() => {
         const waiting = listened;
@@ -198,6 +203,7 @@ export async function createDevServer({
     throw error;
   }
   useDevEntry(load);
+  useDevHead(() => styles.api.link());
 
   // Loaded once now, so a broken entry fails the start rather than the
   // first page, and the module graph the deferred manifest is read from

package/src/head.js

@@ -448,6 +448,18 @@ export function modulePreloads(document) {
   return [...new Set(out)];
 }
 
+/**
+ * $document, which ends with `</head>`, with $extra just before it.
+ *
+ * @param {string} document
+ * @param {string} extra
+ */
+function withExtra(document, extra) {
+  if (extra === '') return document;
+  const close = asciiLower(document).lastIndexOf('</head>');
+  return close === -1 ? document : document.slice(0, close) + extra + document.slice(close);
+}
+
 /**
  * The HTML stream with its head resolved: held until `</head>` arrives,
  * then sent with the fallbacks written and the duplicates dropped, and
@@ -457,9 +469,11 @@ export function modulePreloads(document) {
  * @param {unknown} head the render frame's `head`
  * @param {(resolved: { preload: string[] }) => void} [onResolved] told, once,
  *        what the resolved head preloads -- for PHP's Link header
+ * @param {string} [extra] markup the renderer adds before `</head>`, its own
+ *        and never a frame's: in dev, the link to StyleX's stylesheet (ADR 0179)
  * @returns {ReadableStream<Uint8Array>}
  */
-export function withHead(html, head, onResolved) {
+export function withHead(html, head, onResolved, extra = '') {
   const fallbacks = fallbackTags(head);
   // What is held, as it came: joined once, when `</head>` is found, and
   // searched only where the newest chunk could finish it -- copying and
@@ -510,7 +524,7 @@ export function withHead(html, head, onResolved) {
 
         const bytes = join();
         const end = windowStart + found;
-        const resolvedHead = resolveHead(decoder.decode(bytes.subarray(0, end)), fallbacks);
+        const resolvedHead = withExtra(resolveHead(decoder.decode(bytes.subarray(0, end)), fallbacks), extra);
         onResolved?.({ preload: modulePreloads(resolvedHead) });
         controller.enqueue(encoder.encode(resolvedHead));
         if (end < bytes.length) controller.enqueue(bytes.subarray(end));

package/src/render-session.js

@@ -351,9 +351,17 @@ export class RenderSession {
       // among them until a component's replace them. What the head preloads
       // goes to PHP as a `meta` frame -- the page's client references, for its
       // Link header -- before the first byte of the document does.
-      htmlStream = withHead(htmlStream, frame.head, ({ preload }) => {
-        if (preload.length > 0) this.#send({ t: FRAME.META, preload });
-      });
+      // The dev renderer's app adds its own to the head -- the link to
+      // StyleX's dev stylesheet (ADR 0179); a built app's entry, nothing.
+      const devHead = typeof this.#app.tinvarDevHead === 'function' ? String(this.#app.tinvarDevHead()) : '';
+      htmlStream = withHead(
+        htmlStream,
+        frame.head,
+        ({ preload }) => {
+          if (preload.length > 0) this.#send({ t: FRAME.META, preload });
+        },
+        devHead,
+      );
       return injectRscPayload(htmlStream, rscStream, frame.nonce, frame.page);
     } catch (error) {
       // Both renders are running by now, and neither has a reader: left

package/src/stylex-dev.js

@@ -21,6 +21,9 @@ import { normalizePath } from 'vite';
 /** Where the compiled rules are served, under the dev server's base. */
 export const STYLEX_DEV_CSS = '__tinvar/stylex.css';
 
+/** The attribute that marks the head's link, which the runtime disables once it has the rules. */
+export const STYLEX_DEV_LINK = 'data-tinvar-stylex-dev';
+
 /** The module the client entry imports to take the rules into the page. */
 export const STYLEX_DEV_MODULE = 'virtual:tinvar/stylex-dev';
 
@@ -45,6 +48,11 @@ export function styleXDevStyles(base) {
   return {
     name: 'tinvar:stylex-dev',
     apply: 'serve',
+    api: {
+      /** The link that styles a page from its first paint, for its head (ADR 0179). */
+      link: () =>
+        collect === null ? '' : `<link rel="stylesheet" href="${base}${STYLEX_DEV_CSS}" ${STYLEX_DEV_LINK}>`,
+    },
 
     configResolved(config) {
       // The app's StyleX plugin: the one that can say what it compiled.
@@ -126,6 +134,7 @@ function clientInputs(config) {
  */
 export function styleXDevRuntime(url) {
   return `const URL = ${JSON.stringify(url)};
+const LINK = ${JSON.stringify(STYLEX_DEV_LINK)};
 const ID = 'tinvar-stylex-dev';
 let last = null;
 let asked = 0;
@@ -147,6 +156,9 @@ async function update() {
     if (request === asked && css !== last) {
       element().textContent = css;
       last = css;
+      // The head's link styled the first paint; from here the <style> is
+      // current, and the link would keep rules an edit took out.
+      for (const link of document.querySelectorAll('link[' + LINK + ']')) link.disabled = true;
     }
   } catch {}
 }