catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/test/errors/index.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect } from "vitest"
+import {
+    ERROR_CODES,
+    CatalystError,
+    createError,
+    wrapForeignError,
+    wrapSSRError,
+    wrapProviderError,
+    formatError,
+} from "../../src/errors/index.js"
+
+// Framework-level (Tier 1) behavioral contract tests for errors/index.js —
+// the "external contributor can't quietly change core behavior" lock. These
+// fail the moment formatting/wrapping semantics drift from what's documented
+// here, independent of the registry's actual content (see registry.test.js
+// for that).
+
+describe("createError()", () => {
+    it("uses registry defaults when no overrides are given", () => {
+        const err = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+        expect(err).toBeInstanceOf(CatalystError)
+        expect(err.code).toBe(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+        expect(err.category).toBe("PREFLIGHT")
+        expect(err.message).toBe("config not found in config folder")
+        expect(err.details).toBe("A config object must be exported from the config folder in your project root.")
+        expect(err.suggestedAction).toContain("config/config.json")
+        expect(err.docUrl).toBe("https://github.com/tata1mg/catalyst-core/blob/main/errors/PREFLIGHT/PREFLIGHT-001.md")
+        expect(err.cause).toBeUndefined()
+    })
+
+    it("overrides message/details/suggestedAction when provided", () => {
+        const err = createError(ERROR_CODES.PREFLIGHT_CONFIG_KEY_MISSING, {
+            details: "NODE_SERVER_PORT key not found inside config.json",
+        })
+        expect(err.details).toBe("NODE_SERVER_PORT key not found inside config.json")
+        // message/suggestedAction fall back to the registry default when not overridden
+        expect(err.message).toBe("required key missing inside config.json")
+    })
+
+    it("attaches cause only when explicitly provided (not even as undefined-valued own property)", () => {
+        const withoutCause = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+        expect("cause" in withoutCause).toBe(false)
+
+        const original = new Error("boom")
+        const withCause = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING, { cause: original })
+        expect(withCause.cause).toBe(original)
+    })
+
+    it("falls back to the UNKNOWN-category generic definition for an unrecognized code", () => {
+        const err = createError("NOT-A-REAL-CODE")
+        expect(err.category).toBe("UNKNOWN")
+        expect(err.code).toBe("NOT-A-REAL-CODE")
+    })
+
+    it("sets name to CatalystError and is a real Error instance", () => {
+        const err = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+        expect(err.name).toBe("CatalystError")
+        expect(err).toBeInstanceOf(Error)
+    })
+})
+
+describe("wrapForeignError()", () => {
+    it("maps BUNDLE/IOS/ANDROID stages to their per-stage wrapper code", () => {
+        expect(wrapForeignError("BUNDLE", new Error()).code).toBe(ERROR_CODES.BUNDLE_UPSTREAM_ERROR)
+        expect(wrapForeignError("IOS", new Error()).code).toBe(ERROR_CODES.IOS_UPSTREAM_ERROR)
+        expect(wrapForeignError("ANDROID", new Error()).code).toBe(ERROR_CODES.ANDROID_UPSTREAM_ERROR)
+    })
+
+    it("throws on an unknown stage rather than silently producing a bad code", () => {
+        expect(() => wrapForeignError("NOT_A_STAGE", new Error())).toThrow(/unknown stage/)
+    })
+
+    it("preserves the original error as cause, never reinterpreting its message", () => {
+        const original = new Error("EACCES: permission denied")
+        const wrapped = wrapForeignError("BUNDLE", original)
+        expect(wrapped.cause).toBe(original)
+        expect(wrapped.message).not.toBe(original.message)
+    })
+
+    it("shows the upstream named error code when present (e.g. Rollup's PLUGIN_LOAD_ERROR)", () => {
+        // .code isn't part of the standard Error interface — it's a Node
+        // convention (see NodeJS.ErrnoException) that upstream build tools
+        // like Rollup also follow for their own error codes.
+        const original: NodeJS.ErrnoException = new Error("failed to load")
+        original.code = "PLUGIN_LOAD_ERROR"
+        const wrapped = wrapForeignError("BUNDLE", original)
+        expect(wrapped.message).toContain("PLUGIN_LOAD_ERROR")
+    })
+
+    it("does NOT show a bare numeric process exit code as if it were a named upstream code", () => {
+        const original = new Error("process exited") as Error & { code: number }
+        original.code = 1 // numeric, e.g. a spawned child's exit status — not a named identifier
+        const wrapped = wrapForeignError("BUNDLE", original)
+        expect(wrapped.message).not.toContain("1")
+        expect(wrapped.message).toBe("Build failed (upstream: Vite/Rollup)")
+    })
+
+    it("handles an error with no .code at all", () => {
+        const wrapped = wrapForeignError("IOS", new Error("generic failure"))
+        expect(wrapped.message).toBe("Build failed (upstream: Xcode/CocoaPods)")
+    })
+})
+
+describe("wrapSSRError()", () => {
+    it("maps each SSR stage to its RUNTIME-WEB code", () => {
+        expect(wrapSSRError("RENDER", new Error()).code).toBe(ERROR_CODES.RUNTIME_WEB_RENDER_FAILED)
+        expect(wrapSSRError("FETCHER", new Error()).code).toBe(ERROR_CODES.RUNTIME_WEB_FETCHER_FAILED)
+        expect(wrapSSRError("SERVER_SIDE_FUNCTION", new Error()).code).toBe(ERROR_CODES.RUNTIME_WEB_SERVER_SIDE_FUNCTION_FAILED)
+        expect(wrapSSRError("REQUEST_HANDLING", new Error()).code).toBe(ERROR_CODES.RUNTIME_WEB_REQUEST_HANDLING_FAILED)
+    })
+
+    it("throws on an unknown stage rather than silently producing a bad code", () => {
+        expect(() => wrapSSRError("NOT_A_STAGE", new Error())).toThrow(/unknown stage/)
+    })
+
+    it("preserves the original error verbatim as cause — never reinterprets it (could be app code, a dep, or catalyst-core itself)", () => {
+        const original = new TypeError("Cannot read properties of undefined")
+        const wrapped = wrapSSRError("FETCHER", original)
+        expect(wrapped.cause).toBe(original)
+    })
+})
+
+describe("wrapProviderError()", () => {
+    it("constructs a cause carrying provider/status, and includes both in the message", () => {
+        const wrapped = wrapProviderError("openai", 429, '{"error":"rate limited"}')
+        expect(wrapped.code).toBe(ERROR_CODES.AI_UPSTREAM_ERROR)
+        expect(wrapped.cause.provider).toBe("openai")
+        expect(wrapped.cause.status).toBe(429)
+        expect(wrapped.cause.message).toContain("rate limited")
+        expect(wrapped.message).toContain("openai")
+        expect(wrapped.message).toContain("429")
+    })
+})
+
+describe("formatError()", () => {
+    const err = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+    const errWithCause = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING, { cause: new Error("ENOENT: no such file") })
+
+    it("defaults to \"default\" mode when no mode is passed (WebBridge.js's browser call sites rely on this)", () => {
+        expect(formatError(err)).toBe(formatError(err, "default"))
+    })
+
+    it("default mode: single-line-per-field, shows cause message when present", () => {
+        const output = formatError(errWithCause, "default")
+        expect(output).toContain(`[${ERROR_CODES.PREFLIGHT_CONFIG_MISSING}]`)
+        expect(output).toContain("ENOENT: no such file")
+        expect(output).toContain("Suggested action:")
+        expect(output).toContain("Docs:")
+    })
+
+    it("default mode: falls back to details when there is no cause", () => {
+        const output = formatError(err, "default")
+        expect(output).toContain(err.details)
+    })
+
+    it("verbose mode: includes code/category/problem/solution/docs, boxed", () => {
+        const output = formatError(errWithCause, "verbose")
+        expect(output).toContain(`Code: ${ERROR_CODES.PREFLIGHT_CONFIG_MISSING}`)
+        expect(output).toContain("Category: PREFLIGHT")
+        expect(output).toContain("Problem: ENOENT: no such file")
+        expect(output).toContain("Solution:")
+        expect(output).toContain("Docs:")
+        expect(output).toContain("┌")
+        expect(output).toContain("└")
+    })
+
+    it("verbose mode: category falls back to UNKNOWN when the error has none", () => {
+        const bareErr = new CatalystError("SOME-CODE", { message: "x" })
+        const output = formatError(bareErr, "verbose")
+        expect(output).toContain("Category: UNKNOWN")
+    })
+
+    it("debug mode: includes the full cause chain and a stack trace", () => {
+        const inner = new Error("root cause")
+        const middle = new Error("middle layer")
+        middle.cause = inner
+        const wrapped = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING, { cause: middle })
+
+        const output = formatError(wrapped, "debug", { node: "v20.4.0", platform: "darwin" })
+        expect(output).toContain("Caused by: middle layer")
+        expect(output).toContain("  Caused by: root cause")
+        expect(output).toContain("Environment:")
+        expect(output).toContain("node: v20.4.0")
+        expect(output).toContain("Stack trace:")
+    })
+
+    it("debug mode: omits the Environment section when no env is passed", () => {
+        const output = formatError(err, "debug")
+        expect(output).not.toContain("Environment:")
+    })
+
+    it("debug mode: uses the cause's stack when a cause is present, not the wrapper's own stack", () => {
+        const original = new Error("original failure")
+        const wrapped = createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING, { cause: original })
+        const output = formatError(wrapped, "debug")
+        // The wrapper error's own stack frame (this test file) would appear either way,
+        // but the cause's message must be the one whose stack header shows up.
+        expect(output).toContain("original failure")
+    })
+})

package/test/errors/registry.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest"
+import { ERROR_CODES, ERROR_DEFINITIONS, getDefinition, getDocUrl } from "../../src/errors/registry.js"
+
+// Framework-level (Tier 1) contract tests for the error registry itself —
+// not testing any consumer of it. These exist so a malformed new error code
+// fails CI with no human review needed (see issue #340/#411).
+
+const CODE_FORMAT_RE = /^[A-Z][A-Z-]*-\d{3}$/
+
+describe("ERROR_CODES / ERROR_DEFINITIONS shape invariants", () => {
+    const codeEntries = Object.entries(ERROR_CODES)
+    const codeValues = Object.values(ERROR_CODES)
+
+    it("has at least one code defined", () => {
+        expect(codeEntries.length).toBeGreaterThan(0)
+    })
+
+    it("every ERROR_CODES value has a matching ERROR_DEFINITIONS entry", () => {
+        const missing = codeValues.filter((code) => !(code in ERROR_DEFINITIONS))
+        expect(missing).toEqual([])
+    })
+
+    it("every ERROR_DEFINITIONS key corresponds to a declared ERROR_CODES value", () => {
+        const definedCodes = Object.keys(ERROR_DEFINITIONS)
+        const orphaned = definedCodes.filter((code) => !codeValues.includes(code))
+        expect(orphaned).toEqual([])
+    })
+
+    it("code values are unique — no two ERROR_CODES keys share a code string", () => {
+        const seen = new Set()
+        const duplicates = []
+        for (const code of codeValues) {
+            if (seen.has(code)) duplicates.push(code)
+            seen.add(code)
+        }
+        expect(duplicates).toEqual([])
+    })
+
+    it("every code matches the CATEGORY-NNN format", () => {
+        const malformed = codeValues.filter((code) => !CODE_FORMAT_RE.test(code))
+        expect(malformed).toEqual([])
+    })
+
+    it("every code's category prefix matches its definition's category field", () => {
+        const mismatches = []
+        for (const [key, code] of codeEntries) {
+            const def = ERROR_DEFINITIONS[code]
+            if (!def) continue // covered by the "matching entry" test above
+            const prefix = code.slice(0, code.lastIndexOf("-"))
+            if (prefix !== def.category) {
+                mismatches.push(`${key} (${code}): prefix "${prefix}" !== category "${def.category}"`)
+            }
+        }
+        expect(mismatches).toEqual([])
+    })
+
+    it("every definition has all required fields, non-empty", () => {
+        const REQUIRED_FIELDS = ["category", "defaultMessage", "defaultDetails", "suggestedAction"] as const
+        const problems: string[] = []
+        for (const [code, def] of Object.entries(ERROR_DEFINITIONS)) {
+            for (const field of REQUIRED_FIELDS) {
+                const value = def[field]
+                if (typeof value !== "string" || value.trim().length === 0) {
+                    problems.push(`${code}: missing or empty "${field}"`)
+                }
+            }
+        }
+        expect(problems).toEqual([])
+    })
+
+    it("no definition carries a `recoverable` field (dropped per 18530a89 — never reinstate)", () => {
+        const withRecoverable = Object.entries(ERROR_DEFINITIONS)
+            .filter(([, def]) => "recoverable" in def)
+            .map(([code]) => code)
+        expect(withRecoverable).toEqual([])
+    })
+})
+
+describe("getDefinition()", () => {
+    it("returns the real definition for a known code", () => {
+        const def = getDefinition(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+        expect(def.category).toBe("PREFLIGHT")
+        expect(def.defaultMessage).toBe("config not found in config folder")
+    })
+
+    it("falls back to a generic definition for an unrecognized code", () => {
+        const def = getDefinition("NOT-A-REAL-CODE")
+        expect(def).toBeDefined()
+        expect(def.defaultMessage).toBeTruthy()
+        expect(def.suggestedAction).toBeTruthy()
+    })
+
+    it("never mislabels the fallback as RUNTIME-NATIVE — category is always UNKNOWN", () => {
+        const def = getDefinition("NOT-A-REAL-CODE")
+        expect(def.category).toBe("UNKNOWN")
+    })
+})
+
+describe("getDocUrl()", () => {
+    it("builds a repo-blob URL under the code's own category for a known code", () => {
+        const url = getDocUrl(ERROR_CODES.AI_DISABLED)
+        expect(url).toBe("https://github.com/tata1mg/catalyst-core/blob/main/errors/AI/AI-001.md")
+    })
+
+    it("returns null for an unrecognized code rather than a broken URL", () => {
+        expect(getDocUrl("NOT-A-REAL-CODE")).toBeNull()
+    })
+})

package/test/scripts/preflight.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "fs"
+import { tmpdir } from "os"
+import path from "path"
+import { runStaticPreflight } from "../../src/scripts/preflight.js"
+import { ERROR_CODES } from "../../src/errors/registry.js"
+
+// runStaticPreflight(appDir) reads config/config.json + package.json from a
+// real directory and returns an array of CatalystError for every failure it
+// finds (empty = the app would pass). These tests build throwaway app dirs
+// and assert the codes.
+
+const VALID_CONFIG = {
+    NODE_SERVER_HOSTNAME: "localhost",
+    NODE_SERVER_PORT: 3000,
+    BUILD_OUTPUT_PATH: "build",
+    PUBLIC_STATIC_ASSET_PATH: "/assets/",
+    PUBLIC_STATIC_ASSET_URL: "http://localhost:3000",
+    CLIENT_ENV_VARIABLES: [],
+}
+const VALID_PKG = {
+    name: "fixture-app",
+    _moduleAliases: {
+        "@api": "api.js",
+        "@containers": "src/js/containers",
+        "@server": "server",
+        "@config": "config",
+        "@css": "src/static/css",
+        "@routes": "src/js/routes/",
+    },
+}
+
+let appDir: string
+
+function writeApp({ config, pkg }: { config?: unknown; pkg?: unknown }) {
+    if (config !== undefined) {
+        mkdirSync(path.join(appDir, "config"), { recursive: true })
+        writeFileSync(
+            path.join(appDir, "config", "config.json"),
+            typeof config === "string" ? config : JSON.stringify(config)
+        )
+    }
+    if (pkg !== undefined) {
+        writeFileSync(
+            path.join(appDir, "package.json"),
+            typeof pkg === "string" ? pkg : JSON.stringify(pkg)
+        )
+    }
+}
+
+const codes = (dir: string) => runStaticPreflight(dir).map((e) => e.code)
+
+beforeEach(() => {
+    appDir = mkdtempSync(path.join(tmpdir(), "preflight-test-"))
+})
+afterEach(() => {
+    rmSync(appDir, { recursive: true, force: true })
+})
+
+describe("runStaticPreflight", () => {
+    it("returns [] for a fully valid app", () => {
+        writeApp({ config: VALID_CONFIG, pkg: VALID_PKG })
+        expect(runStaticPreflight(appDir)).toEqual([])
+    })
+
+    it("PREFLIGHT-001 when config/config.json is absent", () => {
+        writeApp({ pkg: VALID_PKG })
+        expect(codes(appDir)).toContain(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+    })
+
+    it("PREFLIGHT-001 when config/config.json is malformed JSON", () => {
+        writeApp({ config: "{ not json", pkg: VALID_PKG })
+        expect(codes(appDir)).toContain(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+    })
+
+    it("PREFLIGHT-003 when a required config key is missing", () => {
+        const { NODE_SERVER_PORT: _omit, ...partial } = VALID_CONFIG
+        writeApp({ config: partial, pkg: VALID_PKG })
+        expect(codes(appDir)).toContain(ERROR_CODES.PREFLIGHT_CONFIG_KEY_MISSING)
+    })
+
+    it("PREFLIGHT-004 when package.json is absent", () => {
+        writeApp({ config: VALID_CONFIG })
+        expect(codes(appDir)).toContain(ERROR_CODES.PREFLIGHT_PACKAGE_JSON_MISSING)
+    })
+
+    it("PREFLIGHT-005 when package.json is malformed JSON", () => {
+        writeApp({ config: VALID_CONFIG, pkg: "{ nope" })
+        expect(codes(appDir)).toContain(ERROR_CODES.PREFLIGHT_PACKAGE_JSON_INVALID)
+    })
+
+    it("PREFLIGHT-006 when _moduleAliases is absent", () => {
+        writeApp({ config: VALID_CONFIG, pkg: { name: "x" } })
+        expect(codes(appDir)).toContain(ERROR_CODES.PREFLIGHT_MODULE_ALIAS_MISSING)
+    })
+
+    it("PREFLIGHT-009 when a required alias is missing", () => {
+        const { "@containers": _drop, ...aliases } = VALID_PKG._moduleAliases
+        writeApp({ config: VALID_CONFIG, pkg: { name: "x", _moduleAliases: aliases } })
+        expect(codes(appDir)).toContain(ERROR_CODES.PREFLIGHT_MODULE_ALIAS_KEY_MISSING)
+    })
+
+    it("collects MULTIPLE failures in one pass (config + package.json both broken)", () => {
+        writeApp({}) // neither file written
+        const found = codes(appDir)
+        expect(found).toContain(ERROR_CODES.PREFLIGHT_CONFIG_MISSING)
+        expect(found).toContain(ERROR_CODES.PREFLIGHT_PACKAGE_JSON_MISSING)
+        expect(found.length).toBeGreaterThanOrEqual(2)
+    })
+
+    it("every returned item is a CatalystError with a docUrl", () => {
+        writeApp({})
+        for (const err of runStaticPreflight(appDir)) {
+            expect(err.name).toBe("CatalystError")
+            expect(err.docUrl).toMatch(/\/errors\/PREFLIGHT\/PREFLIGHT-\d{3}\.md$/)
+        }
+    })
+})

package/test/server/ChunkExtractor.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { ChunkExtractor } from "../../src/server/renderer/ChunkExtractor.js"
+
+// Asset bucketing used by handler.jsx's collectAssets / _renderMarkUp
+// (#348 coverage). Critical = <head>, deferred = after </body>.
+
+let savedUrl: string | undefined
+let savedPath: string | undefined
+beforeEach(() => {
+    savedUrl = process.env.PUBLIC_STATIC_ASSET_URL
+    savedPath = process.env.PUBLIC_STATIC_ASSET_PATH
+    process.env.PUBLIC_STATIC_ASSET_URL = "https://cdn.example.com"
+    process.env.PUBLIC_STATIC_ASSET_PATH = "/static/"
+})
+afterEach(() => {
+    if (savedUrl === undefined) delete process.env.PUBLIC_STATIC_ASSET_URL
+    else process.env.PUBLIC_STATIC_ASSET_URL = savedUrl
+    if (savedPath === undefined) delete process.env.PUBLIC_STATIC_ASSET_PATH
+    else process.env.PUBLIC_STATIC_ASSET_PATH = savedPath
+})
+
+describe("ChunkExtractor", () => {
+    it("constructs with empty manifests and yields empty buckets", () => {
+        const ce = new ChunkExtractor()
+        expect(ce.getCriticalAssets()).toEqual({ js: [], css: [] })
+        expect(ce.getDeferredAssets()).toEqual({ js: [], css: [] })
+        expect(ce.getRenderedComponentKeys()).toEqual([])
+    })
+
+    it("loads essential entrypoints from assetManifest into the critical bucket as public URLs", () => {
+        const ce = new ChunkExtractor({
+            assetManifest: {
+                essential: {
+                    entry: { file: "assets/entry-abc.js", css: ["assets/entry-abc.css"] },
+                },
+            },
+        })
+        const critical = ce.getCriticalAssets()
+        expect(critical.js).toEqual(["https://cdn.example.com/static/assets/entry-abc.js"])
+        // CSS stays a relative path (read from disk later, not linked)
+        expect(critical.css).toEqual(["assets/entry-abc.css"])
+    })
+
+    it("preloadRouteCss adds a matched route component's chunk to the critical bucket", () => {
+        const ce = new ChunkExtractor({
+            manifest: { "pages/Home": { file: "assets/home-xyz.js", css: ["assets/home-xyz.css"] } },
+        })
+        ce.preloadRouteCss([
+            { route: { component: { __cacheKey: "pages/Home" } } },
+            { route: {} }, // no component -> skipped, no throw
+            null, // -> skipped
+        ])
+        const critical = ce.getCriticalAssets()
+        expect(critical.js).toEqual(["https://cdn.example.com/static/assets/home-xyz.js"])
+        expect(critical.css).toEqual(["assets/home-xyz.css"])
+    })
+
+    it("addComponent puts discovered chunks in the deferred bucket and tracks the key", () => {
+        const ce = new ChunkExtractor({
+            manifest: { "widgets/Cart": { file: "assets/cart-123.js", css: ["assets/cart-123.css"] } },
+        })
+        ce.addComponent("widgets/Cart")
+        expect(ce.getRenderedComponentKeys()).toEqual(["widgets/Cart"])
+        expect(ce.getDeferredAssets().js).toEqual(["https://cdn.example.com/static/assets/cart-123.js"])
+    })
+
+    it("addComponent falls back to a prefix (hashed) manifest key when the raw key is absent", () => {
+        const ce = new ChunkExtractor({
+            manifest: {
+                "widgets/Modal.a1b2c3.js": { file: "assets/modal-a1b2c3.js", css: ["assets/modal.css"] },
+            },
+        })
+        // raw "widgets/Modal.a1b2c3.js" isn't a key; "widgets/Modal" +
+        // "." prefix-matches it.
+        ce.addComponent("widgets/Modal")
+        expect(ce.getDeferredAssets().js).toEqual([
+            "https://cdn.example.com/static/assets/modal-a1b2c3.js",
+        ])
+    })
+
+    it("addComponent is a no-op (but still tracks the key) when no manifest entry matches at all", () => {
+        const ce = new ChunkExtractor({ manifest: {} })
+        ce.addComponent("widgets/Unknown")
+        expect(ce.getRenderedComponentKeys()).toEqual(["widgets/Unknown"])
+        expect(ce.getDeferredAssets()).toEqual({ js: [], css: [] })
+    })
+
+    it("does not double-count a JS URL already tracked as critical", () => {
+        const ce = new ChunkExtractor({
+            assetManifest: { essential: { e: { file: "assets/shared.js" } } },
+            manifest: { "widgets/Shared": { file: "assets/shared.js" } },
+        })
+        ce.addComponent("widgets/Shared")
+        expect(ce.getDeferredAssets().js).toEqual([])
+        expect(ce.getCriticalAssets().js).toEqual(["https://cdn.example.com/static/assets/shared.js"])
+    })
+})

package/test/server/extract.test.ts

@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import {
+    generateCssLinkStrings,
+    generateModulePreloadLinkElements,
+    generateScriptElements,
+    generateScriptStrings,
+    getCachedDeferredCssPathsForRoute,
+    getDeferredPreloadScriptUrls,
+    getDeferredRouteKey,
+    readCssFromDisk,
+    registerDeferredAssetsForRoute,
+} from "../../src/server/renderer/extract.js"
+
+
+// Pure asset-string / deferred-route-registry helpers pulled in by
+// handler.jsx and _renderMarkUp (#348 coverage). The registry lives on
+// process.deferredAssetsByRoute (module-level Map) — cleared between
+// tests so cases don't leak.
+
+beforeEach(() => {
+    (process as any).deferredAssetsByRoute = new Map()
+})
+afterEach(() => {
+    (process as any).deferredAssetsByRoute = new Map()
+})
+
+describe("getDeferredRouteKey", () => {
+    it("returns the last matched route's path", () => {
+        const matches = [{ route: { path: "/" } }, { route: { path: "/product/:id" } }]
+        expect(getDeferredRouteKey({}, matches)).toBe("/product/:id")
+    })
+    it("returns null for no matches", () => {
+        expect(getDeferredRouteKey({}, [])).toBeNull()
+        expect(getDeferredRouteKey({})).toBeNull()
+    })
+})
+
+describe("registerDeferredAssetsForRoute / getCachedDeferredCssPathsForRoute", () => {
+    it("records new CSS paths once and reports only the not-yet-seen ones", () => {
+        const first = registerDeferredAssetsForRoute("/r", { css: ["a.css", "b.css"] } as any)
+        expect(first.newCssPaths).toEqual(["a.css", "b.css"])
+
+        const second = registerDeferredAssetsForRoute("/r", { css: ["b.css", "c.css"] } as any)
+        expect(second.newCssPaths).toEqual(["c.css"])
+
+        expect(getCachedDeferredCssPathsForRoute("/r").sort()).toEqual(["a.css", "b.css", "c.css"])
+    })
+
+    it("skips JS URLs for bot requests but still records CSS", () => {
+        registerDeferredAssetsForRoute("/r", { css: ["x.css"], js: ["x.js"] } as any, true)
+        expect(getCachedDeferredCssPathsForRoute("/r")).toEqual(["x.css"])
+        expect(getDeferredPreloadScriptUrls("/r")).toEqual([])
+    })
+
+    it("records JS URLs for non-bot requests", () => {
+        registerDeferredAssetsForRoute("/r", { js: ["a.js", "b.js"] } as any, false)
+        expect(getDeferredPreloadScriptUrls("/r").sort()).toEqual(["a.js", "b.js"])
+    })
+
+    it("no-ops for a falsy routeKey", () => {
+        expect(registerDeferredAssetsForRoute(null, { css: ["a.css"] } as any)).toEqual({ newCssPaths: [] })
+        expect(getCachedDeferredCssPathsForRoute(null)).toEqual([])
+    })
+
+    it("skips falsy entries in the css list", () => {
+        const { newCssPaths } = registerDeferredAssetsForRoute("/r", {
+            css: ["a.css", "", null, "b.css"],
+        } as any)
+        expect(newCssPaths).toEqual(["a.css", "b.css"])
+    })
+})
+
+describe("getDeferredPreloadScriptUrls", () => {
+    it("excludes URLs already loaded as critical scripts", () => {
+        registerDeferredAssetsForRoute("/r", { js: ["keep.js", "crit.js"] } as any, false)
+        expect(getDeferredPreloadScriptUrls("/r", ["crit.js"])).toEqual(["keep.js"])
+    })
+    it("returns [] when the route has no record", () => {
+        expect(getDeferredPreloadScriptUrls("/never")).toEqual([])
+    })
+})
+
+describe("HTML / React element generators", () => {
+    it("generateScriptElements dedupes and emits module <script> elements", () => {
+        const els = generateScriptElements(["a.js", "a.js", "b.js"])
+        expect(els).toHaveLength(2)
+        expect(els[0].props).toMatchObject({ type: "module", src: "a.js" })
+    })
+
+    it("generateModulePreloadLinkElements dedupes and honors the key prefix", () => {
+        const els = generateModulePreloadLinkElements(["a.js", "a.js"], "crit")
+        expect(els).toHaveLength(1)
+        expect(els[0].key).toBe("crit-0")
+        expect(els[0].props).toMatchObject({ rel: "modulepreload", href: "a.js" })
+    })
+
+    it("generateCssLinkStrings builds deduped <link rel=stylesheet> strings", () => {
+        expect(generateCssLinkStrings(["a.css", "a.css", "b.css"])).toBe(
+            '<link rel="stylesheet" href="a.css"><link rel="stylesheet" href="b.css">',
+        )
+    })
+
+    it("generateScriptStrings builds deduped module <script> strings", () => {
+        expect(generateScriptStrings(["a.js", "a.js"])).toBe(
+            '<script type="module" src="a.js"></script>',
+        )
+    })
+})
+
+describe("readCssFromDisk", () => {
+    it("returns an empty string when given no paths", () => {
+        expect(readCssFromDisk([], "/whatever")).toBe("")
+    })
+
+    it("returns an empty string (not a throw) when the CSS files do not exist on disk", () => {
+        const out = readCssFromDisk(["does-not-exist.css"], "/tmp/nonexistent-build-dir")
+        expect(out).toBe("")
+    })
+
+    it("skips http(s)-prefixed and duplicate asset entries", () => {
+        // http-prefixed -> not read from disk; duplicate -> read once.
+        const out = readCssFromDisk(
+            ["https://cdn.example.com/x.css", "dup.css", "dup.css", ""],
+            "/tmp/nonexistent-build-dir",
+        )
+        expect(out).toBe("")
+    })
+})

package/test/server/fixtures/template/server/document.jsx

@@ -0,0 +1,19 @@
+import React from "react"
+
+// Minimal CustomDocument for the SSR handler fixture (#348). Mirrors the
+// shape a scaffolded app's server/document exports: a function taking the
+// merged render props and returning the full <html> tree. Renders just
+// enough (the app div via props.jsx, a marker for assertions) to let
+// renderToPipeableStream produce a stream.
+export default function CustomDocument(props) {
+    return (
+        <html lang={props.lang || "en"}>
+            <head>
+                <title>fixture</title>
+            </head>
+            <body>
+                <div data-testid="doc-root">{props.jsx}</div>
+            </body>
+        </html>
+    )
+}