@warlock.js/web 5.0.0

package/esm/server/settle-page-response.mjs

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+
+//#region ../web/src/server/settle-page-response.ts
+/** Root → leaf. The pipeline's one ordering, used by every stage that walks levels. */
+const LEVEL_ORDER = [
+	"app",
+	"layout",
+	"page"
+];
+/**
+* Settle the surviving buffers root→leaf, per cookie name / header key: a
+* leafward level re-writing the same key wins it, everything else merges.
+*
+* **Headers and status are mirrored onto the live response here; COOKIES ARE
+* NOT**, and that asymmetry is the fix for a real defect rather than an
+* oversight. `header()` and `setStatusCode()` are keyed SETs, so mirroring here
+* and re-applying at the emit is idempotent. `cookie()` APPENDS — Fastify emits
+* one `Set-Cookie` per call — so doing both put the same cookie on the wire
+* twice, on every page response including the happy path.
+*
+* The emit is the authoritative application site (`createPageRouteHandler`
+* replays `rendered.cookies` through `applyBufferedCookie`), so the cookie loop
+* is the one that goes.
+*/
+function commitBuffers(realResponse, ordered, forcedStatusCode) {
+	const headers = /* @__PURE__ */ new Map();
+	const cookies = /* @__PURE__ */ new Map();
+	let statusCode;
+	for (const { buffer } of ordered) {
+		for (const header of buffer.headers) headers.set(header.key.toLowerCase(), header);
+		for (const cookie of buffer.cookies) cookies.set(cookie.name, cookie);
+		if (buffer.statusCode !== void 0) statusCode = buffer.statusCode;
+	}
+	if (forcedStatusCode !== void 0) statusCode = forcedStatusCode;
+	for (const header of headers.values()) realResponse.header(header.key, header.value);
+	if (statusCode !== void 0) realResponse.setStatusCode(statusCode);
+	return {
+		headers: [...headers.values()],
+		cookies: [...cookies.values()],
+		statusCode,
+		committedLevels: ordered.map(({ level }) => level)
+	};
+}
+/** Nearest `ErrorBoundary` at or rootward of the throw; `app` is terminal. */
+function designateBoundary(throwingLevel, triple) {
+	const throwingIndex = LEVEL_ORDER.indexOf(throwingLevel);
+	for (let index = throwingIndex; index >= 0; index--) {
+		const level = LEVEL_ORDER[index];
+		if (triple[level].ErrorBoundary) return {
+			throwingLevel,
+			boundaryLevel: level
+		};
+	}
+	return {
+		throwingLevel,
+		boundaryLevel: "app"
+	};
+}
+/**
+* The one place a throw enters the bundle.
+*
+* **Production never lets the raw error reach a client** — the boundary gets a
+* surrogate carrying only `digest`, which is all the reference app's
+* ErrorBoundary renders. Dev keeps the real thrown value so the stack survives,
+* and it is never mutated to attach `digest`: that lives on the RECORD only.
+*/
+function buildErrorRecord(thrown, boundary, requestPath) {
+	const digest = randomUUID();
+	console.error("[warlock] page error", digest, ...requestPath ? [requestPath] : [], thrown);
+	if (process.env.NODE_ENV === "production") {
+		const surrogate = /* @__PURE__ */ new Error("An unexpected error occurred.");
+		surrogate.digest = digest;
+		return {
+			error: surrogate,
+			boundary,
+			digest,
+			scrubbed: true
+		};
+	}
+	return {
+		error: thrown,
+		boundary,
+		digest,
+		scrubbed: false
+	};
+}
+
+//#endregion
+export { LEVEL_ORDER, buildErrorRecord, commitBuffers, designateBoundary };
+//# sourceMappingURL=settle-page-response.mjs.map

package/esm/server/settle-page-response.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle-page-response.mjs","names":[],"sources":["../../../../../../../web/src/server/settle-page-response.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { BufferedCookie, BufferedHeader, ResponseBuffer } from \"./buffered-response\";\nimport type {\n  PageBoundaryDesignation,\n  PageErrorRecord,\n  PageLevelName,\n  PageResponseCommit,\n  PageRouteEntry,\n  PipelineResponse,\n} from \"./execute-page-request.types\";\n\n/** Root → leaf. The pipeline's one ordering, used by every stage that walks levels. */\nexport const LEVEL_ORDER: readonly PageLevelName[] = [\"app\", \"layout\", \"page\"];\n\n/**\n * Settle the surviving buffers root→leaf, per cookie name / header key: a\n * leafward level re-writing the same key wins it, everything else merges.\n *\n * **Headers and status are mirrored onto the live response here; COOKIES ARE\n * NOT**, and that asymmetry is the fix for a real defect rather than an\n * oversight. `header()` and `setStatusCode()` are keyed SETs, so mirroring here\n * and re-applying at the emit is idempotent. `cookie()` APPENDS — Fastify emits\n * one `Set-Cookie` per call — so doing both put the same cookie on the wire\n * twice, on every page response including the happy path.\n *\n * The emit is the authoritative application site (`createPageRouteHandler`\n * replays `rendered.cookies` through `applyBufferedCookie`), so the cookie loop\n * is the one that goes.\n */\nexport function commitBuffers(\n  realResponse: PipelineResponse,\n  ordered: readonly { level: PageLevelName; buffer: ResponseBuffer }[],\n  forcedStatusCode?: number,\n): PageResponseCommit {\n  const headers = new Map<string, BufferedHeader>();\n  const cookies = new Map<string, BufferedCookie>();\n  let statusCode: number | undefined;\n\n  for (const { buffer } of ordered) {\n    for (const header of buffer.headers) headers.set(header.key.toLowerCase(), header);\n    for (const cookie of buffer.cookies) cookies.set(cookie.name, cookie);\n    if (buffer.statusCode !== undefined) statusCode = buffer.statusCode;\n  }\n\n  if (forcedStatusCode !== undefined) statusCode = forcedStatusCode;\n\n  for (const header of headers.values()) realResponse.header(header.key, header.value);\n  if (statusCode !== undefined) realResponse.setStatusCode(statusCode);\n\n  // No `realResponse.cookie(...)` loop — see above. Settled cookies leave\n  // through the return value only, and the emit applies them exactly once.\n\n  return {\n    headers: [...headers.values()],\n    cookies: [...cookies.values()],\n    statusCode,\n    committedLevels: ordered.map(({ level }) => level),\n  };\n}\n\n/** Nearest `ErrorBoundary` at or rootward of the throw; `app` is terminal. */\nexport function designateBoundary(\n  throwingLevel: PageLevelName,\n  triple: PageRouteEntry[\"triple\"],\n): PageBoundaryDesignation {\n  const throwingIndex = LEVEL_ORDER.indexOf(throwingLevel);\n\n  for (let index = throwingIndex; index >= 0; index--) {\n    const level = LEVEL_ORDER[index];\n\n    if (triple[level].ErrorBoundary) {\n      return { throwingLevel, boundaryLevel: level };\n    }\n  }\n\n  // The framework owns a root boundary.\n  return { throwingLevel, boundaryLevel: \"app\" };\n}\n\n/**\n * The one place a throw enters the bundle.\n *\n * **Production never lets the raw error reach a client** — the boundary gets a\n * surrogate carrying only `digest`, which is all the reference app's\n * ErrorBoundary renders. Dev keeps the real thrown value so the stack survives,\n * and it is never mutated to attach `digest`: that lives on the RECORD only.\n */\nexport function buildErrorRecord(\n  thrown: unknown,\n  boundary: PageBoundaryDesignation,\n  requestPath?: string,\n): PageErrorRecord {\n  const digest = randomUUID();\n\n  // The boundary tells the user this was logged, so log it. A digest that\n  // appears in no log is worse than no digest.\n  console.error(\"[warlock] page error\", digest, ...(requestPath ? [requestPath] : []), thrown);\n\n  if (process.env.NODE_ENV === \"production\") {\n    const surrogate = new Error(\"An unexpected error occurred.\");\n\n    (surrogate as Error & { digest: string }).digest = digest;\n\n    return { error: surrogate, boundary, digest, scrubbed: true };\n  }\n\n  return { error: thrown, boundary, digest, scrubbed: false };\n}\n"],"mappings":";;;;AAYA,MAAa,cAAwC;CAAC;CAAO;CAAU;AAAM;;;;;;;;;;;;;;;;AAiB7E,SAAgB,cACd,cACA,SACA,kBACoB;CACpB,MAAM,0BAAU,IAAI,IAA4B;CAChD,MAAM,0BAAU,IAAI,IAA4B;CAChD,IAAI;CAEJ,KAAK,MAAM,EAAE,YAAY,SAAS;EAChC,KAAK,MAAM,UAAU,OAAO,SAAS,QAAQ,IAAI,OAAO,IAAI,YAAY,GAAG,MAAM;EACjF,KAAK,MAAM,UAAU,OAAO,SAAS,QAAQ,IAAI,OAAO,MAAM,MAAM;EACpE,IAAI,OAAO,eAAe,QAAW,aAAa,OAAO;CAC3D;CAEA,IAAI,qBAAqB,QAAW,aAAa;CAEjD,KAAK,MAAM,UAAU,QAAQ,OAAO,GAAG,aAAa,OAAO,OAAO,KAAK,OAAO,KAAK;CACnF,IAAI,eAAe,QAAW,aAAa,cAAc,UAAU;CAKnE,OAAO;EACL,SAAS,CAAC,GAAG,QAAQ,OAAO,CAAC;EAC7B,SAAS,CAAC,GAAG,QAAQ,OAAO,CAAC;EAC7B;EACA,iBAAiB,QAAQ,KAAK,EAAE,YAAY,KAAK;CACnD;AACF;;AAGA,SAAgB,kBACd,eACA,QACyB;CACzB,MAAM,gBAAgB,YAAY,QAAQ,aAAa;CAEvD,KAAK,IAAI,QAAQ,eAAe,SAAS,GAAG,SAAS;EACnD,MAAM,QAAQ,YAAY;EAE1B,IAAI,OAAO,MAAM,CAAC,eAChB,OAAO;GAAE;GAAe,eAAe;EAAM;CAEjD;CAGA,OAAO;EAAE;EAAe,eAAe;CAAM;AAC/C;;;;;;;;;AAUA,SAAgB,iBACd,QACA,UACA,aACiB;CACjB,MAAM,SAAS,WAAW;CAI1B,QAAQ,MAAM,wBAAwB,QAAQ,GAAI,cAAc,CAAC,WAAW,IAAI,CAAC,GAAI,MAAM;CAE3F,IAAI,QAAQ,IAAI,aAAa,cAAc;EACzC,MAAM,4BAAY,IAAI,MAAM,+BAA+B;EAE3D,AAAC,UAAyC,SAAS;EAEnD,OAAO;GAAE,OAAO;GAAW;GAAU;GAAQ,UAAU;EAAK;CAC9D;CAEA,OAAO;EAAE,OAAO;EAAQ;EAAU;EAAQ,UAAU;CAAM;AAC5D"}

package/esm/server/stylesheet-urls.mjs

@@ -0,0 +1,65 @@
+import { CLIENT_ASSET_URL_PREFIX } from "./client-asset-url-prefix.mjs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+//#region ../web/src/server/stylesheet-urls.ts
+/**
+* Which stylesheets a document must link, in each of the two modes.
+*
+* WHY THIS EXISTS AT ALL. Nothing used to put CSS into the server-rendered
+* document. A stylesheet reached the browser only because the CLIENT bundle
+* imported it, which means JavaScript applied it after the module graph
+* loaded — so every full page load painted unstyled first and restyled a
+* moment later. The markup was correct the whole time, which is precisely why
+* it was easy to miss.
+*
+* The two modes learn the answer from different places, and neither can use
+* the other's:
+*
+*  - PRODUCTION reads Vite's client manifest, the same artifact the hydration
+*    entry is already resolved from.
+*  - DEV has no manifest — Vite serves modules on demand — so the URLs are
+*    derived from the source files themselves.
+*/
+/**
+* Every stylesheet the client build emitted, as URLs the asset route serves.
+*
+* Vite records CSS against the CHUNK that imported it — an app whose
+* `root.tsx` imports `app.css` produces a `root.tsx` entry carrying
+* `css: ["assets/root-<hash>.css"]`, not a hydration entry carrying it. So
+* this collects across every entry rather than looking under one name, which
+* would silently find nothing the moment a stylesheet moved file.
+*
+* Duplicates are collapsed and order is preserved: two chunks importing the
+* same stylesheet must not emit two `<link>` tags.
+*
+* A missing or malformed manifest returns NOTHING rather than throwing. The
+* hydration resolver already fails loudly on exactly those conditions, from
+* exactly the same file, and it runs first — a second, worse error for the
+* same cause helps nobody.
+*/
+function productionStylesheetUrls(clientDir) {
+	const manifestPath = path.join(clientDir, ".vite", "manifest.json");
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+	} catch {
+		return [];
+	}
+	if (typeof manifest !== "object" || manifest === null) return [];
+	const urls = [];
+	for (const entry of Object.values(manifest)) {
+		if (entry === void 0 || !Array.isArray(entry.css)) continue;
+		for (const file of entry.css) {
+			if (typeof file !== "string" || file === "") continue;
+			const url = `/${file}`;
+			if (!url.startsWith(`${"/assets"}/`)) continue;
+			if (!urls.includes(url)) urls.push(url);
+		}
+	}
+	return urls;
+}
+
+//#endregion
+export { productionStylesheetUrls };
+//# sourceMappingURL=stylesheet-urls.mjs.map

package/esm/server/stylesheet-urls.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stylesheet-urls.mjs","names":[],"sources":["../../../../../../../web/src/server/stylesheet-urls.ts"],"sourcesContent":["/**\n * Which stylesheets a document must link, in each of the two modes.\n *\n * WHY THIS EXISTS AT ALL. Nothing used to put CSS into the server-rendered\n * document. A stylesheet reached the browser only because the CLIENT bundle\n * imported it, which means JavaScript applied it after the module graph\n * loaded — so every full page load painted unstyled first and restyled a\n * moment later. The markup was correct the whole time, which is precisely why\n * it was easy to miss.\n *\n * The two modes learn the answer from different places, and neither can use\n * the other's:\n *\n *  - PRODUCTION reads Vite's client manifest, the same artifact the hydration\n *    entry is already resolved from.\n *  - DEV has no manifest — Vite serves modules on demand — so the URLs are\n *    derived from the source files themselves.\n */\nimport { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { CLIENT_ASSET_URL_PREFIX } from \"./client-asset-url-prefix\";\n\n/** Stylesheet extensions Vite can serve directly. Mirrors the build's list. */\nconst STYLE_EXTENSIONS = [\".css\", \".scss\", \".sass\", \".less\", \".styl\"];\n\n/**\n * The stylesheets the ROOT document imports, as dev URLs.\n *\n * Dev has no manifest, so the source is the root file itself: whatever\n * `root.tsx` imports with a stylesheet extension is what the document needs.\n * That is deliberately narrow — it answers \"what CSS does this application\n * set up globally\", which is where `app.css` lives and where Tailwind is\n * wired, and it does NOT try to reproduce Vite's per-route CSS graph.\n *\n * The narrowness is the honest part: production splits CSS per chunk, dev\n * links the root's stylesheets on every page. A page whose own module imports\n * its own stylesheet still gets it in dev — Vite's client graph injects it as\n * before — it simply is not render-blocking the way the root's is. That is a\n * smaller gap than the flash this removes, and it is stated rather than\n * hidden.\n *\n * Specifiers are resolved against the root file and expressed relative to the\n * app root, because that is the shape Vite's dev server serves from.\n */\nexport function devStylesheetUrls(appRoot: string, appFile: string): string[] {\n  let source: string;\n\n  try {\n    source = readFileSync(appFile, \"utf-8\");\n  } catch {\n    return [];\n  }\n\n  const urls: string[] = [];\n  const pattern = /\\bimport\\s*[\"']([^\"']+)[\"']/g;\n\n  let match = pattern.exec(source);\n\n  while (match !== null) {\n    const specifier = match[1];\n    const lowered = specifier.toLowerCase();\n\n    if (STYLE_EXTENSIONS.some((extension) => lowered.endsWith(extension))) {\n      const absolute = path.resolve(path.dirname(appFile), specifier);\n      const relative = path.relative(appRoot, absolute).split(path.sep).join(\"/\");\n\n      // Outside the app root Vite would need an `/@fs/` URL and a widened\n      // `fs.allow`; a stylesheet living there is unusual enough that guessing\n      // is worse than leaving it to the client import.\n      if (!relative.startsWith(\"..\")) {\n        const url = `/${relative}${VITE_DIRECT_CSS_QUERY}`;\n\n        if (!urls.includes(url)) urls.push(url);\n      }\n    }\n\n    match = pattern.exec(source);\n  }\n\n  return urls;\n}\n\n/**\n * A stylesheet Vite serves in DEV must be requested with `?direct`.\n *\n * Without it Vite answers the same URL with `text/javascript` — its CSS-as-JS\n * module transform, meant for `import \"./app.css\"` — and a\n * `<link rel=\"stylesheet\">` pointing at a JavaScript response applies\n * NOTHING, silently. No console error, no network failure, just an unstyled\n * page. `?direct` is what makes Vite reply with real `text/css`.\n */\nexport const VITE_DIRECT_CSS_QUERY = \"?direct\";\n\ntype ManifestEntry = {\n  css?: unknown;\n  file?: unknown;\n};\n\n/**\n * Every stylesheet the client build emitted, as URLs the asset route serves.\n *\n * Vite records CSS against the CHUNK that imported it — an app whose\n * `root.tsx` imports `app.css` produces a `root.tsx` entry carrying\n * `css: [\"assets/root-<hash>.css\"]`, not a hydration entry carrying it. So\n * this collects across every entry rather than looking under one name, which\n * would silently find nothing the moment a stylesheet moved file.\n *\n * Duplicates are collapsed and order is preserved: two chunks importing the\n * same stylesheet must not emit two `<link>` tags.\n *\n * A missing or malformed manifest returns NOTHING rather than throwing. The\n * hydration resolver already fails loudly on exactly those conditions, from\n * exactly the same file, and it runs first — a second, worse error for the\n * same cause helps nobody.\n */\nexport function productionStylesheetUrls(clientDir: string): string[] {\n  const manifestPath = path.join(clientDir, \".vite\", \"manifest.json\");\n\n  let manifest: Record<string, ManifestEntry | undefined>;\n\n  try {\n    manifest = JSON.parse(readFileSync(manifestPath, \"utf-8\")) as Record<\n      string,\n      ManifestEntry | undefined\n    >;\n  } catch {\n    return [];\n  }\n\n  if (typeof manifest !== \"object\" || manifest === null) return [];\n\n  const urls: string[] = [];\n\n  for (const entry of Object.values(manifest)) {\n    if (entry === undefined || !Array.isArray(entry.css)) continue;\n\n    for (const file of entry.css) {\n      if (typeof file !== \"string\" || file === \"\") continue;\n\n      // Built EXACTLY as the hydration entry's URL is built — `/${file}`, then\n      // checked against the prefix — rather than reassembled from a basename.\n      // The manifest already records `assets/root-<hash>.css`, and rebuilding\n      // that path here would be a second expression of a convention\n      // `client-asset-url-prefix.ts` owns.\n      const url = `/${file}`;\n\n      // A stylesheet outside the directory the asset route mounts would 404.\n      // Dropped rather than emitted, because a dead <link> in <head> is a\n      // silent styling failure — the exact thing this module exists to end.\n      if (!url.startsWith(`${CLIENT_ASSET_URL_PREFIX}/`)) continue;\n\n      if (!urls.includes(url)) urls.push(url);\n    }\n  }\n\n  return urls;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmHA,SAAgB,yBAAyB,WAA6B;CACpE,MAAM,eAAe,KAAK,KAAK,WAAW,SAAS,eAAe;CAElE,IAAI;CAEJ,IAAI;EACF,WAAW,KAAK,MAAM,aAAa,cAAc,OAAO,CAAC;CAI3D,QAAQ;EACN,OAAO,CAAC;CACV;CAEA,IAAI,OAAO,aAAa,YAAY,aAAa,MAAM,OAAO,CAAC;CAE/D,MAAM,OAAiB,CAAC;CAExB,KAAK,MAAM,SAAS,OAAO,OAAO,QAAQ,GAAG;EAC3C,IAAI,UAAU,UAAa,CAAC,MAAM,QAAQ,MAAM,GAAG,GAAG;EAEtD,KAAK,MAAM,QAAQ,MAAM,KAAK;GAC5B,IAAI,OAAO,SAAS,YAAY,SAAS,IAAI;GAO7C,MAAM,MAAM,IAAI;GAKhB,IAAI,CAAC,IAAI,WAAW,aAA2B,EAAE,GAAG;GAEpD,IAAI,CAAC,KAAK,SAAS,GAAG,GAAG,KAAK,KAAK,GAAG;EACxC;CACF;CAEA,OAAO;AACT"}

package/esm/server/web-connector-factory.d.mts

@@ -0,0 +1,25 @@
+import { WebBuildOptions } from "../build/contribution.mjs";
+import { WebConnectorOptions } from "./web-connector.mjs";
+import { Connector } from "@warlock.js/core";
+
+//#region ../web/src/server/web-connector-factory.d.ts
+type WebConnectorFactoryOptions = WebConnectorOptions & {
+  /**
+   * What web contributes to `warlock build`. Passed straight to
+   * {@link createWebBuildContribution}; JSON-serializable values only — no
+   * plugin or pipeline instances, so a config load never pulls Vite in.
+   */
+  build?: WebBuildOptions;
+};
+/**
+ * Construct web's connector for `warlock.config.ts > connectors`.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({ connectors: [webConnector()] });
+ * ```
+ */
+declare function webConnector(options?: WebConnectorFactoryOptions): Connector;
+//#endregion
+export { webConnector };
+//# sourceMappingURL=web-connector-factory.d.mts.map

package/esm/server/web-connector-factory.mjs

@@ -0,0 +1,121 @@
+import { createWebBuildContribution } from "../build/contribution.mjs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ConnectorLifecyclePhase } from "@warlock.js/core";
+
+//#region ../web/src/server/web-connector-factory.ts
+/**
+* `webConnector()` — the ONE thing `warlock.config.ts` imports from
+* `@warlock.js/web/connector`, and the only value the `./connector` barrel
+* adds beyond the build/runtime seams.
+*
+* WHY THIS MODULE EXISTS AT ALL, rather than the barrel exporting
+* `WebConnector` directly: `./web-connector.ts` imports `../vite`
+* (`web-connector.ts:52` → `@babel/parser` + `magic-string`),
+* `../../../core/src/router/router` (`:51`) and `./dev-server` (`:53`, which
+* itself pulls core's http stack and `../vite`) at VALUE level. Re-exporting
+* that class from `web/src/connector/index.ts` would drag every one of those
+* into the static graph of every consuming app's config file — the exact
+* config-load weight the `./connector` subpath was created to prevent.
+*
+* So the factory returns a LAZY DELEGATE: a `Connector` whose identity fields
+* (`name`, `priority`, `lifecyclePhase`, `build`) are plain data available
+* synchronously, and whose lifecycle methods `await import("./web-connector")`
+* on first use. `warlock build` reads `build` off this object and never boots
+* anything, so a build never loads Vite or React through
+* here either. This is the third instance of a pattern the codebase already
+* uses twice — `core/src/connectors/access-connector.ts:39` and
+* `web/src/server/dev-cli.ts:61` — not a new one.
+*
+* KEEP THIS MODULE LIGHT. Its whole value-level static graph is `node:path`,
+* `node:url`, `../../../core/src/connectors/types` (whose own two imports are
+* both `import type` and therefore erased — `core/src/connectors/types.ts:1-2`)
+* and `../build/contribution` (`node:fs` + `node:path` + type-only core).
+* Everything else here is `import type`, which `verbatimModuleSyntax` erases.
+*/
+/**
+* Boot/shutdown position relative to core's own connectors.
+*
+* `ConnectorPriority.HTTP` is `5` and `ConnectorPriority.STORAGE` is `6`
+* (`core/src/connectors/types.ts:187-188`), and the manager sorts on a plain
+* numeric compare (`core/src/connectors/connectors-manager.ts:46`) — so `5.5`
+* is "immediately after http, before everything else".
+*
+* Defined HERE and re-exported by `./web-connector` rather than the other way
+* round: the delegate must publish `priority` synchronously, and reading it
+* from the heavy module would defeat the whole point of the delegate.
+*/
+const WEB_CONNECTOR_PRIORITY = 5.5;
+/**
+* The `@warlock.js/web` package root, derived once from THIS module's location
+* and then passed EXPLICITLY to both halves.
+*
+* `web/src/server/web-connector-factory.ts` → `web/src/server` → `web/src` →
+* `web`; published as `web/esm/server/web-connector-factory.js`, two levels up
+* is the package root under both layouts — the same arithmetic
+* `contribution.ts:136-140` documents.
+*
+* Deriving it here and handing it down means the build contribution never falls
+* back to its own `import.meta.url` guess (`contribution.ts:129-141`): one
+* derivation, one place to be wrong, and `assertWebPackageRoot` verifies it
+* against `<root>/package.json`'s `name` either way.
+*/
+function deriveWebRoot() {
+	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+/**
+* Construct web's connector for `warlock.config.ts > connectors`.
+*
+* @example
+* ```ts
+* export default defineConfig({ connectors: [webConnector()] });
+* ```
+*/
+function webConnector(options = {}) {
+	const { build: buildOptions, ...connectorOptions } = options;
+	const webRoot = connectorOptions.webRoot ?? deriveWebRoot();
+	const build = createWebBuildContribution({
+		...buildOptions,
+		webRoot: buildOptions?.webRoot ?? webRoot
+	});
+	let instance;
+	/**
+	* Load the heavy half on first lifecycle call. `boot()` is always the first
+	* of these to run (`core/src/connectors/connectors-manager.ts:87-93`), so the
+	* import lands in a process that has already committed to serving pages.
+	*/
+	const load = async () => {
+		if (!instance) {
+			const { WebConnector: WebConnectorClass } = await import("./web-connector.mjs");
+			instance = new WebConnectorClass({
+				...connectorOptions,
+				webRoot
+			});
+		}
+		return instance;
+	};
+	return {
+		name: "web",
+		priority: WEB_CONNECTOR_PRIORITY,
+		lifecyclePhase: ConnectorLifecyclePhase.Late,
+		build,
+		isActive: () => instance?.isActive() ?? false,
+		boot: async () => {
+			await (await load()).boot();
+		},
+		start: async () => {
+			await (await load()).start();
+		},
+		restart: async () => {
+			await (await load()).restart();
+		},
+		shutdown: async () => {
+			await instance?.shutdown();
+		},
+		shouldRestart: () => false
+	};
+}
+
+//#endregion
+export { WEB_CONNECTOR_PRIORITY, webConnector };
+//# sourceMappingURL=web-connector-factory.mjs.map

package/esm/server/web-connector-factory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-connector-factory.mjs","names":[],"sources":["../../../../../../../web/src/server/web-connector-factory.ts"],"sourcesContent":["/**\n * `webConnector()` — the ONE thing `warlock.config.ts` imports from\n * `@warlock.js/web/connector`, and the only value the `./connector` barrel\n * adds beyond the build/runtime seams.\n *\n * WHY THIS MODULE EXISTS AT ALL, rather than the barrel exporting\n * `WebConnector` directly: `./web-connector.ts` imports `../vite`\n * (`web-connector.ts:52` → `@babel/parser` + `magic-string`),\n * `../../../core/src/router/router` (`:51`) and `./dev-server` (`:53`, which\n * itself pulls core's http stack and `../vite`) at VALUE level. Re-exporting\n * that class from `web/src/connector/index.ts` would drag every one of those\n * into the static graph of every consuming app's config file — the exact\n * config-load weight the `./connector` subpath was created to prevent.\n *\n * So the factory returns a LAZY DELEGATE: a `Connector` whose identity fields\n * (`name`, `priority`, `lifecyclePhase`, `build`) are plain data available\n * synchronously, and whose lifecycle methods `await import(\"./web-connector\")`\n * on first use. `warlock build` reads `build` off this object and never boots\n * anything, so a build never loads Vite or React through\n * here either. This is the third instance of a pattern the codebase already\n * uses twice — `core/src/connectors/access-connector.ts:39` and\n * `web/src/server/dev-cli.ts:61` — not a new one.\n *\n * KEEP THIS MODULE LIGHT. Its whole value-level static graph is `node:path`,\n * `node:url`, `../../../core/src/connectors/types` (whose own two imports are\n * both `import type` and therefore erased — `core/src/connectors/types.ts:1-2`)\n * and `../build/contribution` (`node:fs` + `node:path` + type-only core).\n * Everything else here is `import type`, which `verbatimModuleSyntax` erases.\n */\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport {\n  type Connector,\n  type ConnectorBuildContribution,\n  ConnectorLifecyclePhase,\n  type ConnectorName,\n} from \"@warlock.js/core\";\nimport { createWebBuildContribution, type WebBuildOptions } from \"../build/contribution\";\nimport type { WebConnector, WebConnectorOptions } from \"./web-connector\";\n\n/**\n * Boot/shutdown position relative to core's own connectors.\n *\n * `ConnectorPriority.HTTP` is `5` and `ConnectorPriority.STORAGE` is `6`\n * (`core/src/connectors/types.ts:187-188`), and the manager sorts on a plain\n * numeric compare (`core/src/connectors/connectors-manager.ts:46`) — so `5.5`\n * is \"immediately after http, before everything else\".\n *\n * Defined HERE and re-exported by `./web-connector` rather than the other way\n * round: the delegate must publish `priority` synchronously, and reading it\n * from the heavy module would defeat the whole point of the delegate.\n */\nexport const WEB_CONNECTOR_PRIORITY = 5.5;\n\nexport type WebConnectorFactoryOptions = WebConnectorOptions & {\n  /**\n   * What web contributes to `warlock build`. Passed straight to\n   * {@link createWebBuildContribution}; JSON-serializable values only — no\n   * plugin or pipeline instances, so a config load never pulls Vite in.\n   */\n  build?: WebBuildOptions;\n};\n\n/**\n * The `@warlock.js/web` package root, derived once from THIS module's location\n * and then passed EXPLICITLY to both halves.\n *\n * `web/src/server/web-connector-factory.ts` → `web/src/server` → `web/src` →\n * `web`; published as `web/esm/server/web-connector-factory.js`, two levels up\n * is the package root under both layouts — the same arithmetic\n * `contribution.ts:136-140` documents.\n *\n * Deriving it here and handing it down means the build contribution never falls\n * back to its own `import.meta.url` guess (`contribution.ts:129-141`): one\n * derivation, one place to be wrong, and `assertWebPackageRoot` verifies it\n * against `<root>/package.json`'s `name` either way.\n */\nfunction deriveWebRoot(): string {\n  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"..\", \"..\");\n}\n\n/**\n * Construct web's connector for `warlock.config.ts > connectors`.\n *\n * @example\n * ```ts\n * export default defineConfig({ connectors: [webConnector()] });\n * ```\n */\nexport function webConnector(options: WebConnectorFactoryOptions = {}): Connector {\n  const { build: buildOptions, ...connectorOptions } = options;\n  const webRoot = connectorOptions.webRoot ?? deriveWebRoot();\n\n  const build: ConnectorBuildContribution = createWebBuildContribution({\n    ...buildOptions,\n    webRoot: buildOptions?.webRoot ?? webRoot,\n  });\n\n  let instance: WebConnector | undefined;\n\n  /**\n   * Load the heavy half on first lifecycle call. `boot()` is always the first\n   * of these to run (`core/src/connectors/connectors-manager.ts:87-93`), so the\n   * import lands in a process that has already committed to serving pages.\n   */\n  const load = async (): Promise<WebConnector> => {\n    if (!instance) {\n      const { WebConnector: WebConnectorClass } = await import(\"./web-connector\");\n\n      instance = new WebConnectorClass({ ...connectorOptions, webRoot });\n    }\n\n    return instance;\n  };\n\n  return {\n    name: \"web\" satisfies ConnectorName,\n    priority: WEB_CONNECTOR_PRIORITY,\n    lifecyclePhase: ConnectorLifecyclePhase.Late,\n    build,\n\n    // Never loads the heavy half: a connector that was never booted is not\n    // active, and answering that must not cost a Vite import.\n    isActive: () => instance?.isActive() ?? false,\n\n    boot: async () => {\n      await (await load()).boot();\n    },\n    start: async () => {\n      await (await load()).start();\n    },\n    restart: async () => {\n      await (await load()).restart();\n    },\n\n    // Both of these are asked of every registered connector, including ones\n    // that never booted — so neither may force the import.\n    shutdown: async () => {\n      await instance?.shutdown();\n    },\n    shouldRestart: () => false,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,MAAa,yBAAyB;;;;;;;;;;;;;;;AAyBtC,SAAS,gBAAwB;CAC/B,OAAO,KAAK,QAAQ,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC,GAAG,MAAM,IAAI;AAC9E;;;;;;;;;AAUA,SAAgB,aAAa,UAAsC,CAAC,GAAc;CAChF,MAAM,EAAE,OAAO,cAAc,GAAG,qBAAqB;CACrD,MAAM,UAAU,iBAAiB,WAAW,cAAc;CAE1D,MAAM,QAAoC,2BAA2B;EACnE,GAAG;EACH,SAAS,cAAc,WAAW;CACpC,CAAC;CAED,IAAI;;;;;;CAOJ,MAAM,OAAO,YAAmC;EAC9C,IAAI,CAAC,UAAU;GACb,MAAM,EAAE,cAAc,sBAAsB,MAAM,OAAO;GAEzD,WAAW,IAAI,kBAAkB;IAAE,GAAG;IAAkB;GAAQ,CAAC;EACnE;EAEA,OAAO;CACT;CAEA,OAAO;EACL,MAAM;EACN,UAAU;EACV,gBAAgB,wBAAwB;EACxC;EAIA,gBAAgB,UAAU,SAAS,KAAK;EAExC,MAAM,YAAY;GAChB,OAAO,MAAM,KAAK,EAAC,CAAE,KAAK;EAC5B;EACA,OAAO,YAAY;GACjB,OAAO,MAAM,KAAK,EAAC,CAAE,MAAM;EAC7B;EACA,SAAS,YAAY;GACnB,OAAO,MAAM,KAAK,EAAC,CAAE,QAAQ;EAC/B;EAIA,UAAU,YAAY;GACpB,MAAM,UAAU,SAAS;EAC3B;EACA,qBAAqB;CACvB;AACF"}

package/esm/server/web-connector.d.mts

@@ -0,0 +1,34 @@
+import { BaseConnector, ConnectorLifecyclePhase } from "@warlock.js/core";
+import { Alias, PluginOption } from "vite";
+
+//#region ../web/src/server/web-connector.d.ts
+type WebConnectorOptions = {
+  /**
+   * Vite's `root` — the application directory that owns `src/`, `package.json`
+   * and `tsconfig.json`. Rooting Vite at the APP (not at the `web` package) is
+   * what makes the app's own bare specifiers and dependency-optimizer scan
+   * resolve correctly. Defaults to `process.cwd()`, which is where `warlock dev`
+   * already runs.
+   */
+  appRoot?: string; /** `<appRoot>/src` by default. Pages are `<appSrcRoot>/app/**\/*.page.tsx`. */
+  appSrcRoot?: string; /** The single global app-root file. `<appSrcRoot>/web/root.tsx` by default. */
+  appFile?: string;
+  /**
+   * Root of the `@warlock.js/web` package, used to locate the hydration client
+   * entry. Derived from this module's own location by default — a caller only
+   * sets it when the package is not laid out normally.
+   */
+  webRoot?: string;
+  /**
+   * Extra `resolve.alias` entries, prepended to the app-convention aliases
+   * (`web/*` → `src/web`, `app/*` → `src/app`) so a caller can win a conflict.
+   * A normal application needs none of these; a monorepo checkout with unbuilt
+   * workspace packages does.
+   */
+  resolveAlias?: Alias[]; /** Extra `ssr.external` entries, appended to {@link CORE_OPTIONAL_PEERS}. */
+  ssrExternal?: string[]; /** Extra Vite plugins, appended after the client-boundary gates. */
+  plugins?: PluginOption[];
+};
+//#endregion
+export { WebConnectorOptions };
+//# sourceMappingURL=web-connector.d.mts.map