@cascivo/vite-plugin 0.0.0 → 0.1.0

package/README.md

@@ -57,6 +57,27 @@ cascivo layers:
   cascivo.theme, cascivo.blocks, cascivo.override;
 ```
 
+## SSR: `cascivoSsr()`
+
+The published `@cascivo/react` bundle ships per-component CSS as static
+side-effect imports. Bundlers resolve these; a bare server-side ESM loader (Node
+native, workerd) does not and throws `Unknown file extension ".css"` during SSR.
+`cascivoSsr()` marks every `@cascivo/*` package `ssr.noExternal`, so Vite
+processes their CSS imports instead of the runtime loading them raw:
+
+```ts
+// vite.config.ts — for TanStack Start, vite-ssr, Remix on Vite, workerd, …
+import { cascivoSsr } from '@cascivo/vite-plugin'
+
+export default defineConfig({
+  plugins: [cascivoSsr()],
+})
+```
+
+You still import `@cascivo/react/styles.css` + a theme once in your root entry.
+`cascivoSsr()` composes with `cascivoLayers()` in the same `plugins` array. Full
+recipe: [docs/USING-WITH-VITE-SSR.md](https://github.com/cascivo/cascivo/blob/main/docs/USING-WITH-VITE-SSR.md).
+
 ## Scope
 
 - **Vite only.** A webpack/Next.js loader is not included.
@@ -66,7 +87,8 @@ cascivo layers:
 
 ## API
 
-- `cascivoLayers({ imports })` — the Vite plugin.
+- `cascivoLayers({ imports })` — the vendor CSS-layering plugin.
+- `cascivoSsr()` — sets `ssr.noExternal` for every `@cascivo/*` package (SSR/workerd).
 - `wrapCssInLayer(source, layer?)` — the underlying pure transform, exported for testing.
 
 ## Install

package/dist/index.d.mts

@@ -22,6 +22,11 @@ interface VitePlugin {
     code: string;
     map: null;
   } | null | undefined;
+  config?: () => {
+    ssr: {
+      noExternal: RegExp[];
+    };
+  };
 }
 interface CascivoLayersOptions {
   /**
@@ -46,6 +51,27 @@ declare function wrapCssInLayer(source: string, layer?: string): string;
  * own CSS pipeline processes it.
  */
 declare function cascivoLayers(options: CascivoLayersOptions): VitePlugin;
+/**
+ * Matches every `@cascivo/*` package specifier (`@cascivo/react`,
+ * `@cascivo/react/styles.css`, `@cascivo/charts`, …).
+ */
+declare const CASCIVO_PACKAGE_RE: RegExp;
+/**
+ * Vite plugin that marks all `@cascivo/*` packages `ssr.noExternal`.
+ *
+ * The published `@cascivo/react` bundle ships per-component CSS as static
+ * side-effect imports (`import './button.css'`). A bundler resolves those at
+ * build time, but a bare server-side ESM loader (Node native, workerd) does not
+ * and throws `Unknown file extension ".css"`. Setting `ssr.noExternal` tells
+ * Vite to process these packages — CSS imports included — during SSR instead of
+ * leaving them for the runtime to load raw.
+ *
+ * The returned partial config is deep-merged by Vite (which concatenates
+ * `ssr.noExternal` arrays), so this composes with any existing `noExternal` the
+ * user set. Use for TanStack Start, vite-ssr, Remix on Vite, Astro SSR, and
+ * workerd/Cloudflare targets. See docs/USING-WITH-VITE-SSR.md.
+ */
+declare function cascivoSsr(): VitePlugin;
 //#endregion
-export { CascivoLayersOptions, VitePlugin, cascivoLayers, cascivoLayers as default, wrapCssInLayer };
+export { CASCIVO_PACKAGE_RE, CascivoLayersOptions, VitePlugin, cascivoLayers, cascivoLayers as default, cascivoSsr, wrapCssInLayer };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAiBA;;;;;;;;;;;;AAG+D;AAG/D;;UANiB,UAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA,IAAa,IAAA,UAAc,EAAA;IAAiB,IAAA;IAAc,GAAA;EAAA;AAAA;AAAA,UAG3C,oBAAA;EAuDY;;;;;;;EA/C3B,OAAA,EAAS,MAAM;AAAA;;;;;;;iBAoBD,cAAA,CAAe,MAAA,UAAgB,KAAgB;;;;;;iBA2B/C,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,UAAU"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAiBA;;;;;;;;;;;;;;;UAAiB,UAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA,IAAa,IAAA,UAAc,EAAA;IAAiB,IAAA;IAAc,GAAA;EAAA;EAC1D,MAAA;IAAiB,GAAA;MAAO,UAAA,EAAY,MAAM;IAAA;EAAA;AAAA;AAAA,UAG3B,oBAAA;;;;;;;AAuDuD;EA/CtE,OAAA,EAAS,MAAM;AAAA;;;AAkE8B;AAiB/C;;;iBA/DgB,cAAA,CAAe,MAAA,UAAgB,KAAgB;AA+DvB;;;;;AAAA,iBApCxB,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,UAAU;;;;;cAmB3D,kBAAA,EAAkB,MAAgB;;;;;;;;;;;;;;;;iBAiB/B,UAAA,IAAc,UAAU"}

package/dist/index.mjs

@@ -56,7 +56,35 @@ function cascivoLayers(options) {
 		}
 	};
 }
+/**
+* Matches every `@cascivo/*` package specifier (`@cascivo/react`,
+* `@cascivo/react/styles.css`, `@cascivo/charts`, …).
+*/
+const CASCIVO_PACKAGE_RE = /^@cascivo\//;
+/**
+* Vite plugin that marks all `@cascivo/*` packages `ssr.noExternal`.
+*
+* The published `@cascivo/react` bundle ships per-component CSS as static
+* side-effect imports (`import './button.css'`). A bundler resolves those at
+* build time, but a bare server-side ESM loader (Node native, workerd) does not
+* and throws `Unknown file extension ".css"`. Setting `ssr.noExternal` tells
+* Vite to process these packages — CSS imports included — during SSR instead of
+* leaving them for the runtime to load raw.
+*
+* The returned partial config is deep-merged by Vite (which concatenates
+* `ssr.noExternal` arrays), so this composes with any existing `noExternal` the
+* user set. Use for TanStack Start, vite-ssr, Remix on Vite, Astro SSR, and
+* workerd/Cloudflare targets. See docs/USING-WITH-VITE-SSR.md.
+*/
+function cascivoSsr() {
+	return {
+		name: "cascivo:ssr-no-external",
+		config() {
+			return { ssr: { noExternal: [CASCIVO_PACKAGE_RE] } };
+		}
+	};
+}
 //#endregion
-export { cascivoLayers, cascivoLayers as default, wrapCssInLayer };
+export { CASCIVO_PACKAGE_RE, cascivoLayers, cascivoLayers as default, cascivoSsr, wrapCssInLayer };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @cascivo/vite-plugin — layer JS-imported vendor CSS.\n *\n * The native recipe (`@import url('lib.css') layer(vendor)` from a CSS file) is\n * the primary, tooling-free way to tame third-party stylesheets — see\n * docs/THIRD-PARTY-CSS.md. What native CSS cannot do is layer a stylesheet\n * imported from JavaScript (`import 'lib/styles.css'`), which is how most JS\n * libraries ship. This plugin closes exactly that gap: it wraps configured\n * node_modules `.css` imports into a low-priority `@layer` at build time so the\n * cascivo layers always win.\n */\n\n/**\n * The subset of Vite's `Plugin` interface this package implements. Declared\n * structurally so the package doesn't require `vite`'s types to be resolvable;\n * the returned object is assignable to Vite's `Plugin`.\n */\nexport interface VitePlugin {\n  name: string\n  enforce?: 'pre' | 'post'\n  transform?: (code: string, id: string) => { code: string; map: null } | null | undefined\n}\n\nexport interface CascivoLayersOptions {\n  /**\n   * Map a stylesheet's module id (matched against the tail of the resolved id,\n   * e.g. `\"recharts/styles.css\"`) to the cascade layer it should live in\n   * (typically `\"vendor\"`). The layer must be declared before the cascivo\n   * layers in your app's order statement — the scaffold from `cascivo create`\n   * already includes a `vendor` slot.\n   */\n  imports: Record<string, string>\n}\n\nconst IMPORT_RE = /@import\\s+[^;]+;/g\nconst CHARSET_RE = /^\\s*@charset\\s+[^;]+;/i\n\n/** Add `layer(<layer>)` to an `@import` statement that isn't already layered. */\nfunction layerizeImport(stmt: string, layer: string): string {\n  if (/\\blayer\\b/.test(stmt)) return stmt\n  const head = stmt.match(/@import\\s+(?:url\\([^)]*\\)|\"[^\"]*\"|'[^']*')/i)\n  if (!head) return stmt\n  return stmt.replace(head[0], `${head[0]} layer(${layer})`)\n}\n\n/**\n * Wrap a stylesheet's rules in `@layer <layer> { … }`. Because an `@import` may\n * not appear inside a layer block, top-level `@import`s are hoisted out and\n * rewritten to carry `layer(<layer>)` themselves; a leading `@charset` is kept\n * first. Pure string-in/string-out.\n */\nexport function wrapCssInLayer(source: string, layer = 'vendor'): string {\n  let charset = ''\n  let body = source\n  const cm = body.match(CHARSET_RE)\n  if (cm) {\n    charset = `${cm[0].trim()}\\n`\n    body = body.slice(cm[0].length)\n  }\n  const imports: string[] = []\n  body = body.replace(IMPORT_RE, (stmt) => {\n    imports.push(layerizeImport(stmt.trim(), layer))\n    return ''\n  })\n  const importsBlock = imports.length > 0 ? `${imports.join('\\n')}\\n` : ''\n  return `${charset}${importsBlock}@layer ${layer} {\\n${body.trim()}\\n}\\n`\n}\n\n/** Normalize a module id: drop the query/hash and Windows backslashes. */\nfunction normalizeId(id: string): string {\n  return (id.split('?')[0] ?? id).replace(/\\\\/g, '/')\n}\n\n/**\n * Vite plugin that wraps configured node_modules stylesheets in a cascade\n * `@layer`. Runs `enforce: 'pre'` so it transforms the raw CSS before Vite's\n * own CSS pipeline processes it.\n */\nexport function cascivoLayers(options: CascivoLayersOptions): VitePlugin {\n  const entries = Object.entries(options?.imports ?? {})\n  return {\n    name: 'cascivo:vendor-layers',\n    enforce: 'pre',\n    transform(code, id) {\n      const clean = normalizeId(id)\n      if (!clean.endsWith('.css') || !clean.includes('node_modules')) return null\n      const match = entries.find(([key]) => clean.endsWith(key))\n      if (!match) return null\n      return { code: wrapCssInLayer(code, match[1]), map: null }\n    },\n  }\n}\n\nexport default cascivoLayers\n"],"mappings":";AAkCA,MAAM,YAAY;AAClB,MAAM,aAAa;;AAGnB,SAAS,eAAe,MAAc,OAAuB;CAC3D,IAAI,YAAY,KAAK,IAAI,GAAG,OAAO;CACnC,MAAM,OAAO,KAAK,MAAM,6CAA6C;CACrE,IAAI,CAAC,MAAM,OAAO;CAClB,OAAO,KAAK,QAAQ,KAAK,IAAI,GAAG,KAAK,GAAG,SAAS,MAAM,EAAE;AAC3D;;;;;;;AAQA,SAAgB,eAAe,QAAgB,QAAQ,UAAkB;CACvE,IAAI,UAAU;CACd,IAAI,OAAO;CACX,MAAM,KAAK,KAAK,MAAM,UAAU;CAChC,IAAI,IAAI;EACN,UAAU,GAAG,GAAG,EAAE,CAAC,KAAK,EAAE;EAC1B,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC,MAAM;CAChC;CACA,MAAM,UAAoB,CAAC;CAC3B,OAAO,KAAK,QAAQ,YAAY,SAAS;EACvC,QAAQ,KAAK,eAAe,KAAK,KAAK,GAAG,KAAK,CAAC;EAC/C,OAAO;CACT,CAAC;CACD,MAAM,eAAe,QAAQ,SAAS,IAAI,GAAG,QAAQ,KAAK,IAAI,EAAE,MAAM;CACtE,OAAO,GAAG,UAAU,aAAa,SAAS,MAAM,MAAM,KAAK,KAAK,EAAE;AACpE;;AAGA,SAAS,YAAY,IAAoB;CACvC,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,GAAA,CAAI,QAAQ,OAAO,GAAG;AACpD;;;;;;AAOA,SAAgB,cAAc,SAA2C;CACvE,MAAM,UAAU,OAAO,QAAQ,SAAS,WAAW,CAAC,CAAC;CACrD,OAAO;EACL,MAAM;EACN,SAAS;EACT,UAAU,MAAM,IAAI;GAClB,MAAM,QAAQ,YAAY,EAAE;GAC5B,IAAI,CAAC,MAAM,SAAS,MAAM,KAAK,CAAC,MAAM,SAAS,cAAc,GAAG,OAAO;GACvE,MAAM,QAAQ,QAAQ,MAAM,CAAC,SAAS,MAAM,SAAS,GAAG,CAAC;GACzD,IAAI,CAAC,OAAO,OAAO;GACnB,OAAO;IAAE,MAAM,eAAe,MAAM,MAAM,EAAE;IAAG,KAAK;GAAK;EAC3D;CACF;AACF"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @cascivo/vite-plugin — layer JS-imported vendor CSS.\n *\n * The native recipe (`@import url('lib.css') layer(vendor)` from a CSS file) is\n * the primary, tooling-free way to tame third-party stylesheets — see\n * docs/THIRD-PARTY-CSS.md. What native CSS cannot do is layer a stylesheet\n * imported from JavaScript (`import 'lib/styles.css'`), which is how most JS\n * libraries ship. This plugin closes exactly that gap: it wraps configured\n * node_modules `.css` imports into a low-priority `@layer` at build time so the\n * cascivo layers always win.\n */\n\n/**\n * The subset of Vite's `Plugin` interface this package implements. Declared\n * structurally so the package doesn't require `vite`'s types to be resolvable;\n * the returned object is assignable to Vite's `Plugin`.\n */\nexport interface VitePlugin {\n  name: string\n  enforce?: 'pre' | 'post'\n  transform?: (code: string, id: string) => { code: string; map: null } | null | undefined\n  config?: () => { ssr: { noExternal: RegExp[] } }\n}\n\nexport interface CascivoLayersOptions {\n  /**\n   * Map a stylesheet's module id (matched against the tail of the resolved id,\n   * e.g. `\"recharts/styles.css\"`) to the cascade layer it should live in\n   * (typically `\"vendor\"`). The layer must be declared before the cascivo\n   * layers in your app's order statement — the scaffold from `cascivo create`\n   * already includes a `vendor` slot.\n   */\n  imports: Record<string, string>\n}\n\nconst IMPORT_RE = /@import\\s+[^;]+;/g\nconst CHARSET_RE = /^\\s*@charset\\s+[^;]+;/i\n\n/** Add `layer(<layer>)` to an `@import` statement that isn't already layered. */\nfunction layerizeImport(stmt: string, layer: string): string {\n  if (/\\blayer\\b/.test(stmt)) return stmt\n  const head = stmt.match(/@import\\s+(?:url\\([^)]*\\)|\"[^\"]*\"|'[^']*')/i)\n  if (!head) return stmt\n  return stmt.replace(head[0], `${head[0]} layer(${layer})`)\n}\n\n/**\n * Wrap a stylesheet's rules in `@layer <layer> { … }`. Because an `@import` may\n * not appear inside a layer block, top-level `@import`s are hoisted out and\n * rewritten to carry `layer(<layer>)` themselves; a leading `@charset` is kept\n * first. Pure string-in/string-out.\n */\nexport function wrapCssInLayer(source: string, layer = 'vendor'): string {\n  let charset = ''\n  let body = source\n  const cm = body.match(CHARSET_RE)\n  if (cm) {\n    charset = `${cm[0].trim()}\\n`\n    body = body.slice(cm[0].length)\n  }\n  const imports: string[] = []\n  body = body.replace(IMPORT_RE, (stmt) => {\n    imports.push(layerizeImport(stmt.trim(), layer))\n    return ''\n  })\n  const importsBlock = imports.length > 0 ? `${imports.join('\\n')}\\n` : ''\n  return `${charset}${importsBlock}@layer ${layer} {\\n${body.trim()}\\n}\\n`\n}\n\n/** Normalize a module id: drop the query/hash and Windows backslashes. */\nfunction normalizeId(id: string): string {\n  return (id.split('?')[0] ?? id).replace(/\\\\/g, '/')\n}\n\n/**\n * Vite plugin that wraps configured node_modules stylesheets in a cascade\n * `@layer`. Runs `enforce: 'pre'` so it transforms the raw CSS before Vite's\n * own CSS pipeline processes it.\n */\nexport function cascivoLayers(options: CascivoLayersOptions): VitePlugin {\n  const entries = Object.entries(options?.imports ?? {})\n  return {\n    name: 'cascivo:vendor-layers',\n    enforce: 'pre',\n    transform(code, id) {\n      const clean = normalizeId(id)\n      if (!clean.endsWith('.css') || !clean.includes('node_modules')) return null\n      const match = entries.find(([key]) => clean.endsWith(key))\n      if (!match) return null\n      return { code: wrapCssInLayer(code, match[1]), map: null }\n    },\n  }\n}\n\n/**\n * Matches every `@cascivo/*` package specifier (`@cascivo/react`,\n * `@cascivo/react/styles.css`, `@cascivo/charts`, …).\n */\nexport const CASCIVO_PACKAGE_RE = /^@cascivo\\//\n\n/**\n * Vite plugin that marks all `@cascivo/*` packages `ssr.noExternal`.\n *\n * The published `@cascivo/react` bundle ships per-component CSS as static\n * side-effect imports (`import './button.css'`). A bundler resolves those at\n * build time, but a bare server-side ESM loader (Node native, workerd) does not\n * and throws `Unknown file extension \".css\"`. Setting `ssr.noExternal` tells\n * Vite to process these packages — CSS imports included — during SSR instead of\n * leaving them for the runtime to load raw.\n *\n * The returned partial config is deep-merged by Vite (which concatenates\n * `ssr.noExternal` arrays), so this composes with any existing `noExternal` the\n * user set. Use for TanStack Start, vite-ssr, Remix on Vite, Astro SSR, and\n * workerd/Cloudflare targets. See docs/USING-WITH-VITE-SSR.md.\n */\nexport function cascivoSsr(): VitePlugin {\n  return {\n    name: 'cascivo:ssr-no-external',\n    config() {\n      return { ssr: { noExternal: [CASCIVO_PACKAGE_RE] } }\n    },\n  }\n}\n\nexport default cascivoLayers\n"],"mappings":";AAmCA,MAAM,YAAY;AAClB,MAAM,aAAa;;AAGnB,SAAS,eAAe,MAAc,OAAuB;CAC3D,IAAI,YAAY,KAAK,IAAI,GAAG,OAAO;CACnC,MAAM,OAAO,KAAK,MAAM,6CAA6C;CACrE,IAAI,CAAC,MAAM,OAAO;CAClB,OAAO,KAAK,QAAQ,KAAK,IAAI,GAAG,KAAK,GAAG,SAAS,MAAM,EAAE;AAC3D;;;;;;;AAQA,SAAgB,eAAe,QAAgB,QAAQ,UAAkB;CACvE,IAAI,UAAU;CACd,IAAI,OAAO;CACX,MAAM,KAAK,KAAK,MAAM,UAAU;CAChC,IAAI,IAAI;EACN,UAAU,GAAG,GAAG,EAAE,CAAC,KAAK,EAAE;EAC1B,OAAO,KAAK,MAAM,GAAG,EAAE,CAAC,MAAM;CAChC;CACA,MAAM,UAAoB,CAAC;CAC3B,OAAO,KAAK,QAAQ,YAAY,SAAS;EACvC,QAAQ,KAAK,eAAe,KAAK,KAAK,GAAG,KAAK,CAAC;EAC/C,OAAO;CACT,CAAC;CACD,MAAM,eAAe,QAAQ,SAAS,IAAI,GAAG,QAAQ,KAAK,IAAI,EAAE,MAAM;CACtE,OAAO,GAAG,UAAU,aAAa,SAAS,MAAM,MAAM,KAAK,KAAK,EAAE;AACpE;;AAGA,SAAS,YAAY,IAAoB;CACvC,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAC,MAAM,GAAA,CAAI,QAAQ,OAAO,GAAG;AACpD;;;;;;AAOA,SAAgB,cAAc,SAA2C;CACvE,MAAM,UAAU,OAAO,QAAQ,SAAS,WAAW,CAAC,CAAC;CACrD,OAAO;EACL,MAAM;EACN,SAAS;EACT,UAAU,MAAM,IAAI;GAClB,MAAM,QAAQ,YAAY,EAAE;GAC5B,IAAI,CAAC,MAAM,SAAS,MAAM,KAAK,CAAC,MAAM,SAAS,cAAc,GAAG,OAAO;GACvE,MAAM,QAAQ,QAAQ,MAAM,CAAC,SAAS,MAAM,SAAS,GAAG,CAAC;GACzD,IAAI,CAAC,OAAO,OAAO;GACnB,OAAO;IAAE,MAAM,eAAe,MAAM,MAAM,EAAE;IAAG,KAAK;GAAK;EAC3D;CACF;AACF;;;;;AAMA,MAAa,qBAAqB;;;;;;;;;;;;;;;;AAiBlC,SAAgB,aAAyB;CACvC,OAAO;EACL,MAAM;EACN,SAAS;GACP,OAAO,EAAE,KAAK,EAAE,YAAY,CAAC,kBAAkB,EAAE,EAAE;EACrD;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cascivo/vite-plugin",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "private": false,
   "description": "Vite plugin — wrap JS-imported third-party stylesheets into a low-priority CSS @layer",
   "keywords": [

package/readme.body.md

@@ -39,6 +39,27 @@ cascivo layers:
   cascivo.theme, cascivo.blocks, cascivo.override;
 ```
 
+## SSR: `cascivoSsr()`
+
+The published `@cascivo/react` bundle ships per-component CSS as static
+side-effect imports. Bundlers resolve these; a bare server-side ESM loader (Node
+native, workerd) does not and throws `Unknown file extension ".css"` during SSR.
+`cascivoSsr()` marks every `@cascivo/*` package `ssr.noExternal`, so Vite
+processes their CSS imports instead of the runtime loading them raw:
+
+```ts
+// vite.config.ts — for TanStack Start, vite-ssr, Remix on Vite, workerd, …
+import { cascivoSsr } from '@cascivo/vite-plugin'
+
+export default defineConfig({
+  plugins: [cascivoSsr()],
+})
+```
+
+You still import `@cascivo/react/styles.css` + a theme once in your root entry.
+`cascivoSsr()` composes with `cascivoLayers()` in the same `plugins` array. Full
+recipe: [docs/USING-WITH-VITE-SSR.md](https://github.com/cascivo/cascivo/blob/main/docs/USING-WITH-VITE-SSR.md).
+
 ## Scope
 
 - **Vite only.** A webpack/Next.js loader is not included.
@@ -48,5 +69,6 @@ cascivo layers:
 
 ## API
 
-- `cascivoLayers({ imports })` — the Vite plugin.
+- `cascivoLayers({ imports })` — the vendor CSS-layering plugin.
+- `cascivoSsr()` — sets `ssr.noExternal` for every `@cascivo/*` package (SSR/workerd).
 - `wrapCssInLayer(source, layer?)` — the underlying pure transform, exported for testing.