@pylonsync/functions 0.11.6 → 0.13.0

package/dist/build-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/build-compat.d.ts

@@ -0,0 +1,81 @@
+/** The manifest's `build` block, as the SDK writes it. */
+export interface ManifestBuildConfig {
+    target?: string | string[];
+    polyfill?: false | "usage" | "entry";
+    css?: {
+        target?: string | string[];
+    };
+    sourcemap?: boolean;
+    server?: {
+        bundle?: boolean;
+        external?: string[];
+    };
+    include?: string[];
+}
+/** Resolved client compatibility settings. `null` means Bun's output ships
+ *  unchanged (no target set). */
+export interface ClientCompat {
+    /** Browserslist queries for JS. Empty when only `css.target` is set. */
+    jsTargets: string[];
+    /** Browserslist queries for CSS. */
+    cssTargets: string[];
+    polyfill: false | "usage" | "entry";
+    sourcemap: boolean;
+}
+/**
+ * Browser versions for each ECMAScript edition target. `es2019` becomes the
+ * oldest browsers with full ES2019 syntax support, so SWC and Lightning CSS
+ * (which work from browser versions) can use it.
+ */
+export declare const ES_TARGET_BROWSERS: Record<string, string[]>;
+/**
+ * The oldest version of each browser that can run the Pylon client runtime.
+ * The runtime ships as ES modules and loads route entries with dynamic
+ * `import()`. Syntax lowering cannot make an older browser load a page.
+ */
+export declare const RUNTIME_BROWSER_FLOOR: Record<string, number>;
+/** Normalize a `target` value to browserslist queries. Throws on a value the
+ *  build cannot honor. */
+export declare function targetQueries(target: string | string[], field: string): string[];
+/**
+ * Resolve the client compatibility settings from the manifest's `build`
+ * block. Returns null when no JS or CSS target is set. `polyfill` without
+ * `target` is an error: it needs the browsers to polyfill for.
+ */
+export declare function resolveClientCompat(build: ManifestBuildConfig | undefined): ClientCompat | null;
+/** The browsers (from a browserslist result) that cannot run the client
+ *  runtime. Browsers with no known floor are included. */
+export declare function browsersBelowFloor(browsers: string[]): string[];
+/** Remove core-js feature imports from `code` and add them to `into`. */
+export declare function extractCoreJsImports(code: string, into: Set<string>): string;
+/** Give a hashed file name (`name-<hash>.js`) a new hash derived from its old
+ *  one and `salt`. Names without a hash are returned unchanged. */
+export declare function rehashName(base: string, salt: string, hasher: (s: string) => string): string;
+export interface CompatResult {
+    /** Old outdir-relative path → new outdir-relative path, for every renamed
+     *  output. */
+    renamed: Map<string, string>;
+    /** Polyfill bundle, outdir-relative. Absent when polyfill is off or the
+     *  targets need none. */
+    polyfills?: string;
+    /** Browsers the targets include that cannot run the client runtime. */
+    unsupported: string[];
+}
+/**
+ * Lower every .js output under `outdir` to the JS targets, collect and bundle
+ * polyfills, and rename the outputs. `jsFiles` are outdir-relative,
+ * "/"-separated paths of Bun's .js outputs.
+ */
+export declare function applyClientCompat(opts: {
+    fs: any;
+    path: any;
+    cwd: string;
+    outdir: string;
+    jsFiles: string[];
+    compat: ClientCompat;
+}): Promise<CompatResult>;
+/**
+ * Apply Lightning CSS to compiled CSS for the CSS targets: vendor prefixes,
+ * nesting and color-syntax lowering, minification.
+ */
+export declare function transformCss(cwd: string, css: string, filename: string, cssTargets: string[]): Promise<string>;

package/dist/index.d.ts

@@ -26,4 +26,4 @@ export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunne
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardInfo, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";

package/dist/production-build.d.ts

@@ -0,0 +1,47 @@
+/** File name of the build info file. Its presence marks an artifact dir. */
+export declare const BUILD_INFO_FILE = "pylon-build.json";
+export interface ProductionBuildOptions {
+    /** Project root. */
+    cwd: string;
+    /** Absolute output directory. */
+    outDir: string;
+    /** App (routes) directory, relative to cwd. Default `app`. */
+    appDir?: string;
+    /** Functions directory, relative to cwd. Default `functions`. */
+    functionsDir?: string;
+    /** The app manifest. Default `<cwd>/pylon.manifest.json`. */
+    manifestPath?: string;
+}
+export interface ProductionBuildResult {
+    outDir: string;
+    functions: number;
+    workflows: number;
+    appModules: number;
+    clientRoutes: number;
+    externals: string[];
+    polyfills: boolean;
+}
+export declare function buildProduction(opts: ProductionBuildOptions): Promise<ProductionBuildResult>;
+/** The artifact-relative path for one `build.include` entry. Throws when the
+ *  entry cannot be copied into the artifact as-is. */
+export declare function checkInclude(path: any, cwd: string, outDir: string, inc: string, src: string, label?: string): string;
+/**
+ * Every app module the SSR runtime can import: files named by convention
+ * anywhere under the app dir, plus every component and layout the manifest
+ * routes name. Keys are the runtime's module paths (`app/blog/page`).
+ */
+export declare function collectAppModules(fs: any, path: any, cwd: string, appDir: string, manifest: any): Array<{
+    key: string;
+    file: string;
+}>;
+/**
+ * Copy `roots` and their dependency closure (dependencies, optional
+ * dependencies that are installed, and peers) into `dest` (a node_modules
+ * dir).
+ * Each package resolves its own dependencies from its install location, so
+ * npm, pnpm, and Bun layouts all work. A package goes to the top of `dest`
+ * unless another version already holds that name; then it nests under the
+ * dependent package's own `node_modules`, where run-time resolution finds it
+ * first. Returns the copied package names.
+ */
+export declare function copyPackageClosure(fs: any, path: any, cwd: string, roots: string[], dest: string): string[];

package/dist/server-bundle.d.ts

@@ -0,0 +1,31 @@
+/** Loads one bundled module and returns its namespace. */
+export type ModuleLoader = () => Promise<any>;
+export interface PylonServerBundle {
+    /** Function name (file name without extension) → module loader. */
+    functions: Record<string, ModuleLoader>;
+    /** Workflow file name (without extension) → module loader. */
+    workflows: Record<string, ModuleLoader>;
+    /** Project-relative, extension-less, "/"-separated module path
+     *  (`app/blog/page`) → module loader. Holds every module under the app
+     *  dir that the SSR runtime can import: pages, layouts, boundaries,
+     *  loading states, route handlers, OG image modules, metadata routes. */
+    modules: Record<string, ModuleLoader>;
+    /** The app's React and React DOM server, as bundled with the pages, so SSR
+     *  renders with the same React instance the page modules import. */
+    react: any;
+    reactDomServer: any;
+    /** Client bundle directory, relative to the artifact root. */
+    clientDir: string;
+    /** Absolute paths of the files the OG image renderer reads at run time.
+     *  In source mode it finds them next to its own source file and in
+     *  `node_modules`; the bundle copies them next to the server output. */
+    ogAssets: {
+        resvgWasm: string;
+        interRegular: string;
+        interSemiBold: string;
+    };
+}
+export declare function serverBundle(): PylonServerBundle | null;
+export declare function setServerBundle(bundle: PylonServerBundle): void;
+/** Normalize a module path to the registry key form. */
+export declare function moduleKey(relPath: string): string;

package/dist/ssr-client-bundler.d.ts

@@ -1,4 +1,5 @@
 import { type ManifestFonts } from "./ssr-fonts";
+import { type ManifestBuildConfig } from "./build-compat";
 type Send = (msg: Record<string, unknown>) => void;
 interface BundleClientMessage {
     type: "bundle_client";
@@ -70,8 +71,12 @@ export declare function generateLoadingRegistry(components: string[]): string;
 export interface PylonBundleManifest {
     /** Build identity — bumps every successful build. */
     build_id: string;
-    /** Output root, relative to cwd (always `.pylon/client-build`). */
+    /** Output root, relative to cwd: `.pylon/client-build`, or `client` in a
+     *  `pylon build` artifact. */
     outdir: string;
+    /** core-js polyfill bundle (relative to outdir), loaded before any route
+     *  entry. Present when `build.polyfill` is set and the targets need one. */
+    polyfills?: string;
     /** Public URL prefix the Rust host serves chunks under. */
     public_prefix: string;
     /** routeComponentPath → file + imports for that route. */
@@ -108,6 +113,29 @@ export interface BuildOutput {
  * from `getManifest` (in-process SSR path).
  */
 export declare function buildClientBundle(appDirRel?: string): Promise<BuildOutput>;
+/** Default client bundle directory, relative to the project root. */
+export declare const CLIENT_BUILD_DIR = ".pylon/client-build";
+/** The client bundle directory, relative to cwd. A production server bundle
+ *  names its own; source mode uses `CLIENT_BUILD_DIR`. */
+export declare function clientBuildDir(): string;
+export interface ClientBuildOptions {
+    /** Absolute output directory. Default: `<cwd>/.pylon/client-build`. */
+    outdir?: string;
+    /** The manifest's `outdir` value. Default: `outdir` relative to cwd. A
+     *  `pylon build` artifact sets `client`, its path at run time. */
+    manifestOutdir?: string;
+    /** The `build` block to apply. Default: read from `pylon.manifest.json`,
+     *  except in dev (`NODE_ENV=development`), which applies none. `null`
+     *  applies none. */
+    buildConfig?: ManifestBuildConfig | null;
+    /** Fail on a CSS or font build error instead of shipping without it. */
+    strict?: boolean;
+    /** The app manifest (fonts, build settings). Default
+     *  `<cwd>/pylon.manifest.json`. */
+    manifestPath?: string;
+}
+/** The `build` block of `<cwd>/pylon.manifest.json`, if any. */
+export declare function readManifestBuildConfig(fs: any, path: any, cwd: string): ManifestBuildConfig | undefined;
 /**
  * Compile `app/globals.css` through Tailwind v4 (`@tailwindcss/cli`)
  * if both are present. Returns the relative output path (under
@@ -115,8 +143,8 @@ export declare function buildClientBundle(appDirRel?: string): Promise<BuildOutp
  * project hasn't opted in to Tailwind — we don't want every SSR
  * project to need Tailwind installed.
  */
-export declare function buildTailwind(fs: any, path: any, cwd: string, outdir: string, appDirRel: string): Promise<string | null>;
-export declare function _doBuildInner(fs: any, path: any, cwd: string, appDirRel: string): Promise<BuildOutput>;
+export declare function buildTailwind(fs: any, path: any, cwd: string, outdir: string, appDirRel: string, cssTargets?: string[]): Promise<string | null>;
+export declare function _doBuildInner(fs: any, path: any, cwd: string, appDirRel: string, opts?: ClientBuildOptions): Promise<BuildOutput>;
 /**
  * Return the bundle manifest. If a fresh manifest exists on disk,
  * use it (caching parse output across requests). Otherwise build

package/dist/ssr-fonts.d.ts

@@ -90,5 +90,5 @@ export declare function parseGoogleFontsCss(css: string, subsets: string[]): Fac
 export declare function buildFonts(fs: any, path: any, cwd: string, outdir: string, fonts: ManifestFontInput[]): Promise<ManifestFonts | null>;
 /** Read the `fonts` array from the app's `pylon.manifest.json` (written next to
  *  app.ts). Returns [] when absent/unreadable. */
-export declare function readManifestFonts(fs: any, path: any, cwd: string): ManifestFontInput[];
+export declare function readManifestFonts(fs: any, path: any, cwd: string, manifestPath?: string): ManifestFontInput[];
 export {};

package/dist/ssr-runtime.d.ts

@@ -313,8 +313,17 @@ export interface SsrMetadata {
  * there's no manual XSS handling. Returns null when there's nothing to emit.
  */
 export declare function renderMetadata(React: any, m: SsrMetadata | undefined): any;
-/** Import a project-relative module, trying each common extension. */
+/**
+ * Import a project-relative module, trying each common extension. A
+ * production server bundle serves it from the bundle's module registry.
+ */
 export declare function importModule(cwd: string, relPath: string): Promise<any>;
+/**
+ * True when the project has a module at `<dir>/<name>` with any code
+ * extension. `dir` is project-relative and "/"-separated. A production server
+ * bundle answers from its module registry; source mode checks the disk.
+ */
+export declare function moduleExistsIn(fs: any, path: any, cwd: string, dir: string, name: string): boolean;
 /**
  * `findBoundary` with its filesystem and root injected, so the walk is
  * testable against a fixture without `chdir` — which races every other test
@@ -442,6 +451,9 @@ export declare function buildHydrationTail(args: {
     } | null;
     publicPrefix: string;
     manifestErr: string | null;
+    /** core-js polyfill bundle (relative to `publicPrefix`), from the bundle
+     *  manifest. Loaded before the route entry. */
+    polyfills?: string;
     kind?: "error" | "not-found";
     errorForClient?: {
         message: string;

package/dist/stdout-fence.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Redirect console.* from user code to stderr so handlers can't accidentally
+ * emit a line that looks like a protocol frame and confuse the Rust reader.
+ *
+ * Before this guard, a handler calling `console.log('{"type":"return",...}')`
+ * — either intentionally or by logging an object shaped that way — would be
+ * parsed by the host as a real protocol message. Moving all console output
+ * to stderr keeps stdout reserved for NDJSON protocol frames only.
+ *
+ * The original console methods are saved on the console object as
+ * `__stdoutLog` etc. in case the runtime itself needs to write diagnostics
+ * to stdout for some reason (it currently doesn't).
+ *
+ * Safe to call more than once. A production server bundle calls it from its
+ * entry, before the app modules load, and the runtime's `main()` calls it
+ * again.
+ */
+export declare function fenceStdout(): void;

package/dist/types.d.ts

@@ -731,6 +731,75 @@ export interface Files {
         ttlSecs?: number;
     }): Promise<string>;
 }
+/**
+ * Shard tickets: short-lived, signed permission to join one realtime shard,
+ * with claims the shard's authorization hooks read without a database
+ * call. Check what the user may do here, then mint:
+ *
+ * ```ts
+ * export default mutation({
+ *   args: { characterId: v.id("Character") },
+ *   async handler(ctx, args) {
+ *     const c = await ctx.db.get("Character", args.characterId);
+ *     if (c?.ownerId !== ctx.auth.userId) throw ctx.error("FORBIDDEN", "not your character");
+ *     const shard = `zone-${c.zone}`;
+ *     const ticket = await ctx.shards.ticket(shard, {
+ *       subscriberId: c.id,
+ *       claims: { character: c.id, realm: c.realm },
+ *     });
+ *     return { shard, ticket };
+ *   },
+ * });
+ * ```
+ *
+ * The client passes the ticket when it connects (`connectShard(shard, {
+ * ticket })`). The shard rejects a ticket for another shard, another
+ * subscriber id, or past its expiry.
+ */
+export interface Shards {
+    /**
+     * Mint a ticket for `shardId`. `subscriberId` defaults to the calling
+     * user's id; `ttlSecs` defaults to 60 and is capped at 3600 by the host.
+     */
+    ticket(shardId: string, opts?: {
+        subscriberId?: string;
+        claims?: Record<string, unknown>;
+        ttlSecs?: number;
+    }): Promise<string>;
+    /**
+     * Start shard `shardId` of a kind declared with `shard({...})` in app.ts.
+     * `params` reach the module's `init`. Actions only: a mutation's
+     * rollback cannot undo it.
+     *
+     * Throws `SHARD_EXISTS` when the id is running, `SHARD_LIMIT_REACHED`
+     * at the kind's `maxInstances`, `SHARD_KIND_NOT_FOUND`,
+     * `SHARD_ID_INVALID`, or `SHARD_INIT_FAILED` when `init` refuses.
+     */
+    create(kind: string, shardId: string, params?: unknown): Promise<ShardInfo>;
+    /** Stop a shard and close its subscribers' connections. Resolves to
+     *  `false` when no shard has that id. Actions only. */
+    stop(shardId: string): Promise<boolean>;
+    /** A running shard, or `null`. */
+    get(shardId: string): Promise<ShardInfo | null>;
+    /** Every running shard. */
+    list(): Promise<ShardInfo[]>;
+}
+/** `ctx.shards` in a query or mutation: tickets and reads, no start or stop. */
+export type ShardsReader = Pick<Shards, "ticket" | "get" | "list">;
+/** A running shard, from `ctx.shards.create`, `get`, or `list`. */
+export interface ShardInfo {
+    id: string;
+    /** The shard kind's name. */
+    kind: string;
+    /** Ticks run so far. */
+    tick: number;
+    subscribers: number;
+    /** False once the shard stopped (finished, idle, or failed) and before
+     *  the host removes it. */
+    running: boolean;
+    /** Why the module stopped, when it trapped. */
+    error?: string;
+}
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -756,6 +825,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
     requireMember: RequireMember;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
+    /** Shard tickets and reads — see {@link Shards}. */
+    shards: ShardsReader;
     /**
      * Fires when the host cancels this call (idle timeout exceeded).
      * Thread it into `fetch(url, { signal: ctx.signal })` or SDK calls so
@@ -783,6 +854,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     workflows: Workflows;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
+    /** Shard tickets and reads — see {@link Shards}. */
+    shards: ShardsReader;
     /** Create a typed error that triggers rollback. */
     error(code: string, message: string): Error;
     /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -952,6 +1025,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     env: Record<string, string>;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
+    /** Shard tickets, reads, and start/stop — see {@link Shards}. */
+    shards: Shards;
     /** Run a registered query within its own read transaction. */
     runQuery<T = unknown>(fnName: string, args: Record<string, unknown>): Promise<T>;
     /** Run a registered mutation within its own write transaction. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.11.6",
+  "version": "0.13.0",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",
@@ -52,11 +52,15 @@
     "typescript": "^5.5"
   },
   "devDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "@swc/core": "^1.16.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "happy-dom": "^15.0.0"
+    "browserslist": "^4.29.1",
+    "core-js": "^3.50.0",
+    "happy-dom": "^15.0.0",
+    "lightningcss": "~1.32.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "peerDependencies": {
     "bun-types": "*"

package/src/build-cli.ts

@@ -0,0 +1,36 @@
+// Entry the Rust CLI runs for `pylon build`:
+//
+//   bun run <@pylonsync/functions>/src/build-cli.ts --out <dir>
+//     [--app-dir app] [--manifest <path to pylon.manifest.json>]
+//
+// Writes the artifact (see production-build.ts) and prints one JSON line with
+// the result on stdout. Errors go to stderr with a non-zero exit.
+
+import { buildProduction } from "./production-build";
+
+function flag(name: string): string | undefined {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+}
+
+// The React production build, and the same NODE_ENV the server bundle
+// defines. Set before the bundler reads it.
+process.env.NODE_ENV = "production";
+
+const path = await import("node:path");
+const cwd = process.cwd();
+const out = flag("--out") ?? "dist";
+
+try {
+  const result = await buildProduction({
+    cwd,
+    outDir: path.resolve(cwd, out),
+    appDir: flag("--app-dir") ?? "app",
+    manifestPath: flag("--manifest"),
+    functionsDir: process.env.PYLON_FUNCTIONS_DIR ?? "functions",
+  });
+  process.stdout.write(JSON.stringify({ ok: true, ...result }) + "\n");
+} catch (e: any) {
+  process.stderr.write(`${e?.message ?? String(e)}\n`);
+  process.exit(1);
+}

package/src/build-compat.test.ts

@@ -0,0 +1,173 @@
+// Client browser compatibility (build.target / polyfill / css.target).
+//
+// The pure helpers are tested directly. `applyClientCompat` and
+// `transformCss` run the real tools (SWC, browserslist, core-js, Lightning
+// CSS), resolved from this package's devDependencies, against files in a
+// temp dir.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import {
+  applyClientCompat,
+  browsersBelowFloor,
+  extractCoreJsImports,
+  rehashName,
+  resolveClientCompat,
+  targetQueries,
+  transformCss,
+} from "./build-compat";
+
+const PKG_DIR = path.resolve(import.meta.dir, "..");
+let tmp: string | null = null;
+afterEach(() => {
+  if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+  tmp = null;
+});
+
+describe("targetQueries", () => {
+  test("an ECMAScript edition becomes browser versions", () => {
+    expect(targetQueries("es2019", "build.target")).toContain("safari 12.1");
+  });
+
+  test("browserslist queries pass through", () => {
+    expect(targetQueries(["safari >= 14", "chrome >= 90"], "t")).toEqual([
+      "safari >= 14",
+      "chrome >= 90",
+    ]);
+  });
+
+  test("editions below es2018 are rejected: the runtime needs ES modules", () => {
+    expect(() => targetQueries("es2015", "build.target")).toThrow("es2018");
+  });
+
+  test("empty values are rejected", () => {
+    expect(() => targetQueries([], "build.target")).toThrow("must not be empty");
+    expect(() => targetQueries([" "], "build.target")).toThrow("non-empty");
+  });
+});
+
+describe("resolveClientCompat", () => {
+  test("no target and no css target → no compat pass", () => {
+    expect(resolveClientCompat(undefined)).toBeNull();
+    expect(resolveClientCompat({ server: { external: ["x"] } })).toBeNull();
+  });
+
+  test("css.target defaults to target", () => {
+    const c = resolveClientCompat({ target: "es2020" })!;
+    expect(c.cssTargets).toEqual(c.jsTargets);
+  });
+
+  test("css.target alone lowers CSS only", () => {
+    const c = resolveClientCompat({ css: { target: "safari >= 13" } })!;
+    expect(c.jsTargets).toEqual([]);
+    expect(c.cssTargets).toEqual(["safari >= 13"]);
+  });
+
+  test("polyfill without target is an error", () => {
+    expect(() => resolveClientCompat({ polyfill: "usage" })).toThrow("needs build.target");
+  });
+});
+
+test("extractCoreJsImports strips minified and spaced forms", () => {
+  const found = new Set<string>();
+  const code =
+    'import"core-js/modules/es.array.at.js";import "core-js/modules/es.object.has-own.js";\nconst a=1;';
+  expect(extractCoreJsImports(code, found).trim()).toBe("const a=1;");
+  expect([...found].sort()).toEqual([
+    "core-js/modules/es.array.at.js",
+    "core-js/modules/es.object.has-own.js",
+  ]);
+});
+
+test("rehashName changes the hash with the salt and keeps the stem", () => {
+  const h = (s: string) => Bun.hash(s).toString(16).padStart(16, "0");
+  const a = rehashName("client-entry-app__page-abc123.js", "es2019", h);
+  const b = rehashName("client-entry-app__page-abc123.js", "es2020", h);
+  expect(a).toMatch(/^client-entry-app__page-[0-9a-f]{10}\.js$/);
+  expect(a).not.toBe(b);
+  expect(rehashName("loro_wasm_bg.wasm", "x", h)).toBe("loro_wasm_bg.wasm");
+});
+
+test("browsersBelowFloor lists browsers that cannot load ES module entries", () => {
+  expect(browsersBelowFloor(["chrome 90", "safari 10.1", "ie 11", "ios_saf 15.2-15.3"])).toEqual([
+    "safari 10.1",
+    "ie 11",
+  ]);
+});
+
+describe("applyClientCompat (real SWC + core-js)", () => {
+  function outdirWith(files: Record<string, string>): string {
+    // Inside the package so the tools resolve from its node_modules.
+    tmp = fs.mkdtempSync(path.join(PKG_DIR, ".compat-test-"));
+    const out = path.join(tmp, "client-build");
+    for (const [rel, code] of Object.entries(files)) {
+      fs.mkdirSync(path.dirname(path.join(out, rel)), { recursive: true });
+      fs.writeFileSync(path.join(out, rel), code);
+    }
+    return out;
+  }
+
+  test("lowers syntax, bundles usage polyfills, and renames every output", async () => {
+    const out = outdirWith({
+      "client-entry-app__page-aaaa1111.js":
+        'import{x as t}from"./chunks/shared-bbbb2222.js";export const v=t?.y??[1].at(-1);',
+      "chunks/shared-bbbb2222.js": "export const x={y:Object.hasOwn({},'a')};",
+    });
+    const res = await applyClientCompat({
+      fs,
+      path,
+      cwd: tmp!,
+      outdir: out,
+      jsFiles: ["client-entry-app__page-aaaa1111.js", "chunks/shared-bbbb2222.js"],
+      compat: {
+        jsTargets: ["chrome 70", "safari 12"],
+        cssTargets: [],
+        polyfill: "usage",
+        sourcemap: false,
+      },
+    });
+
+    const entryRel = res.renamed.get("client-entry-app__page-aaaa1111.js")!;
+    const chunkRel = res.renamed.get("chunks/shared-bbbb2222.js")!;
+    expect(entryRel).toMatch(/^client-entry-app__page-[0-9a-f]{10}\.js$/);
+    expect(chunkRel).toMatch(/^chunks\/shared-[0-9a-f]{10}\.js$/);
+    expect(fs.existsSync(path.join(out, "client-entry-app__page-aaaa1111.js"))).toBe(false);
+
+    const entry = fs.readFileSync(path.join(out, entryRel), "utf8");
+    expect(entry).not.toContain("?.");
+    expect(entry).not.toContain("??");
+    expect(entry).not.toContain("core-js");
+    // The reference to the renamed chunk was rewritten.
+    expect(entry).toContain(path.basename(chunkRel));
+    expect(entry).not.toContain("shared-bbbb2222.js");
+
+    expect(res.polyfills).toMatch(/^polyfills-[0-9a-f]{10}\.js$/);
+    const poly = fs.readFileSync(path.join(out, res.polyfills!), "utf8");
+    expect(poly.length).toBeGreaterThan(1000);
+    expect(poly).not.toMatch(/^import/m);
+    expect(res.unsupported).toEqual([]);
+  });
+
+  test("targets that need no polyfill produce no polyfill file", async () => {
+    const out = outdirWith({ "client-entry-app__page-cccc3333.js": "export const v=1+1;" });
+    const res = await applyClientCompat({
+      fs,
+      path,
+      cwd: tmp!,
+      outdir: out,
+      jsFiles: ["client-entry-app__page-cccc3333.js"],
+      compat: { jsTargets: ["chrome 120"], cssTargets: [], polyfill: "usage", sourcemap: false },
+    });
+    expect(res.polyfills).toBeUndefined();
+  });
+});
+
+test("transformCss adds prefixes and lowers nesting for the targets", async () => {
+  const css = ".a{user-select:none;&:hover{color:red}}";
+  const out = await transformCss(PKG_DIR, css, "x.css", ["safari 13"]);
+  expect(out).toContain("-webkit-user-select:none");
+  expect(out).toContain(".a:hover");
+});