@statorjs/stator 2.11.0-next.0 → 2.11.0-next.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.11.0-next.0",
+  "version": "2.11.0-next.2",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source, loaded natively by its own toolchain — no build step.",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,7 @@
       "types": "./src/components/index.ts",
       "default": "./src/components/index.ts"
     },
+    "./components.css": "./src/components/components.css",
     "./client": {
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"
@@ -100,13 +101,14 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.11.0-next.0"
+    "@statorjs/stator": "2.11.0-next.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:browser": "node browser-tests/tables.mjs",
-    "build:client": "esbuild src/client/runtime.ts --bundle --format=iife --target=es2020 --outfile=dist/client.js"
+    "build:client": "esbuild src/client/runtime.ts --bundle --format=iife --target=es2020 --outfile=dist/client.js",
+    "build:components": "node scripts/compile-components.mjs && biome check --write src/components/"
   }
 }

package/src/build/build.ts

@@ -2,12 +2,12 @@ import { randomUUID } from 'node:crypto'
 import { cp, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { dirname, join, relative, resolve } from 'node:path'
-import { compile, regionResolverFor } from '../compiler/index.ts'
 import { hashMachines } from '../server/machine-hash.ts'
 import { type ArtifactDeps, writeArtifactDeps } from './artifact.ts'
+import { compileComponentFile } from './compile-component.ts'
 import { type CopySet, resolveCopySet } from './copy-set.ts'
 import { bundleIslands, routeIslandMap, walkFiles } from './islands.ts'
-import { sourceId } from './source-id.ts'
+import { routeCssMap } from './route-css.ts'
 
 /**
  * Production build: compile a `.stator` app to a `dist/` of plain `.ts` that the
@@ -17,10 +17,15 @@ import { sourceId } from './source-id.ts'
  *      directories its routes/machines/hooks import from, the root-level files
  *      they open, and `static/`
  *   2. compile each `*.stator` → a sibling `*.stator.ts`, delete the `.stator`,
- *      accumulate scoped CSS; for client components also write the generated
- *      client entry as a sibling `*.stator.client.ts`
+ *      writing any scoped CSS to a sibling `*.stator.css` (one file per
+ *      component, not accumulated — see `route-css.ts`); for client
+ *      components also write the generated client entry as a sibling
+ *      `*.stator.client.ts`
  *   3. rewrite `.stator` import specifiers (`'./x.stator'` → `'./x.stator.ts'`)
- *   4. write the concatenated scoped CSS to `dist/static/components.css`
+ *   4. walk each route's import graph (`routeCssMap`) and write ONE scoped-CSS
+ *      artifact per route under `dist/static/css/`, from exactly the
+ *      components that route reaches — local siblings just written, plus any
+ *      `node_modules` component library's published sibling stylesheet
  *   5. when the app has client components: bundle every island entry through
  *      the `bundleIslands` seam (hashed output written under
  *      `dist/static/assets/`, server-machine imports stubbed to `{ name }`),
@@ -28,10 +33,11 @@ import { sourceId } from './source-id.ts'
  *      write `dist/stator-manifest.json` mapping route files → island script URLs
  *
  * The prod server runs `createApp` over `dist/` with the `headExtras` hook
- * from `loadProductionHead(dist)` — it links `components.css` and injects the
- * manifest's `<script type="module">` tags per route. File discovery + dynamic
- * import work unchanged on the precompiled output; the island bundler is
- * needed only at build time, and only when islands exist.
+ * from `loadProductionHead(dist)` — it links each route's own CSS href from
+ * the manifest's `routeCss` and injects the manifest's island
+ * `<script type="module">` tags per route. File discovery + dynamic import
+ * work unchanged on the precompiled output; the island bundler is needed only
+ * at build time, and only when islands exist.
  */
 
 export interface BuildConfig {
@@ -55,7 +61,7 @@ export interface BuildResult {
   outDir: string
   /** Number of `.stator` files compiled. */
   compiled: number
-  /** True when any component produced scoped CSS (components.css written). */
+  /** True when any route's import graph reached a component with scoped CSS. */
   hasCss: boolean
   /** Number of client components bundled for the browser. */
   islands: number
@@ -83,6 +89,11 @@ export interface StatorManifest {
   islands: Record<string, string>
   /** Route file (dist-relative) → script URLs for every island it reaches. */
   routes: Record<string, string[]>
+  /** Route file (dist-relative) → its own scoped-CSS stylesheet href, only for
+   *  routes whose import graph reaches at least one styled component. Absent
+   *  on a dist built before per-route CSS existed, which `loadProductionHead`
+   *  reads as "no CSS for any route" (byte-identical to an app with none). */
+  routeCss: Record<string, string>
   /** Machine file (relative to `machines/`) → code hash. Consumed by
    *  `stator start` for the snapshot hydration policy; the build fails if a
    *  machine's closure cannot be bundled, so this lands in CI, not at boot. */
@@ -147,28 +158,16 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     await cp(src, dest)
   }
 
-  // Compile every .stator into a sibling .stator.ts; collect CSS and islands.
-  // The sources are deleted only after the whole set compiles — cross-file
-  // region validation reads sibling `.stator` files mid-compile.
+  // Compile every .stator into a sibling .stator.ts (+ a sibling .stator.css
+  // when it has scoped styles — the same per-component shape a library's own
+  // publish-time compile produces, see route-css.ts) and islands. The sources
+  // are deleted only after the whole set compiles — cross-file region
+  // validation reads sibling `.stator` files mid-compile.
   const statorFiles = await walkFiles(outDir, (f) => f.endsWith('.stator'))
-  let css = ''
   const islands: Array<{ rel: string; entry: string }> = []
   for (const file of statorFiles) {
-    const source = await readFile(file, 'utf8')
-    const { id: rel, kind } = sourceId(outDir, file)
-    const result = compile(source, {
-      id: rel,
-      kind,
-      resolveRegions: regionResolverFor(file, source),
-    })
-    await writeFile(`${file}.ts`, result.serverCode)
-    if (result.isClient) {
-      // The generated client entry, written as a sibling so the authored
-      // script's relative imports resolve against the mirrored dist tree.
-      await writeFile(`${file}.client.ts`, result.clientCode)
-      islands.push({ rel, entry: `${file}.client.ts` })
-    }
-    if (result.css) css += `/* ${rel} */\n${result.css}\n`
+    const { rel, isClient, clientFile } = await compileComponentFile(file, outDir)
+    if (isClient) islands.push({ rel, entry: clientFile! })
   }
   for (const file of statorFiles) await rm(file)
 
@@ -180,9 +179,20 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
     if (rewritten !== code) await writeFile(file, rewritten)
   }
 
-  if (css) {
-    await mkdir(join(outDir, 'static'), { recursive: true })
-    await writeFile(join(outDir, 'static', 'components.css'), css)
+  // Route-level, usage-driven CSS: one artifact per route, from exactly the
+  // components that route's own import graph reaches (local siblings just
+  // written above, plus any node_modules component library's published
+  // sibling stylesheet) — not every component anywhere in the app.
+  const routeCss = await routeCssMap({ routesDir: join(outDir, 'routes'), baseDir: outDir })
+  const routeCssHrefs: Record<string, string> = {}
+  for (const [routeFile, text] of routeCss) {
+    const rel = relative(outDir, routeFile)
+      .replace(/\\/g, '/')
+      .replace(/\.(ts|js)$/, '.css')
+    const dest = join(outDir, 'static', 'css', rel)
+    await mkdir(dirname(dest), { recursive: true })
+    await writeFile(dest, text)
+    routeCssHrefs[relative(outDir, routeFile).replace(/\\/g, '/')] = `/static/css/${rel}`
   }
 
   // Machine code hashes for the snapshot hydration policy: one esbuild pass
@@ -217,6 +227,7 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
       ? {
           buildId: randomUUID(),
           ...(await buildClientAssets(outDir, islands)),
+          routeCss: routeCssHrefs,
           machines,
           config: configFile,
           statorVersion,
@@ -225,6 +236,7 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
           buildId: randomUUID(),
           islands: {},
           routes: {},
+          routeCss: routeCssHrefs,
           machines,
           config: configFile,
           statorVersion,
@@ -234,7 +246,7 @@ export async function buildApp(config: BuildConfig): Promise<BuildResult> {
   return {
     outDir,
     compiled: statorFiles.length,
-    hasCss: Boolean(css),
+    hasCss: Object.keys(routeCssHrefs).length > 0,
     islands: islands.length,
     machines: machineFiles.length,
     machineHashMs,

package/src/build/compile-component.ts

@@ -0,0 +1,36 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { compile, regionResolverFor } from '../compiler/index.ts'
+import { sourceId } from './source-id.ts'
+
+export interface CompileComponentResult {
+  /** Path (relative to `baseDir`, `/`-separated) the compiled module carries
+   *  as its identity — seeds its scope hash, labels its diagnostics. */
+  rel: string
+  isClient: boolean
+  /** The written client-entry sibling (`${file}.client.ts`), when `isClient`. */
+  clientFile?: string
+}
+
+/** Compile one `.stator` file to its sibling `.ts` (+ a sibling `.css` when
+ *  it has scoped styles). Used by both `build.ts` and
+ *  `scripts/compile-components.ts`. */
+export async function compileComponentFile(
+  file: string,
+  baseDir: string,
+): Promise<CompileComponentResult> {
+  const source = await readFile(file, 'utf8')
+  const { id: rel, kind } = sourceId(baseDir, file)
+  const result = compile(source, {
+    id: rel,
+    kind,
+    resolveRegions: regionResolverFor(file, source),
+  })
+  await writeFile(`${file}.ts`, result.serverCode)
+  let clientFile: string | undefined
+  if (result.isClient) {
+    clientFile = `${file}.client.ts`
+    await writeFile(clientFile, result.clientCode)
+  }
+  if (result.css) await writeFile(`${file}.css`, result.css)
+  return { rel, isClient: result.isClient, clientFile }
+}

package/src/build/head.ts

@@ -1,11 +1,13 @@
-import { readFile, stat } from 'node:fs/promises'
+import { readFile } from 'node:fs/promises'
 import { join, relative, resolve } from 'node:path'
 import type { StatorManifest } from './build.ts'
 
 /**
- * Production `headExtras` for a built `dist/`: links `components.css` when the
- * build produced one, and injects each route's island `<script type="module">`
- * tags from `stator-manifest.json`. Pass the result to `createApp`:
+ * Production `headExtras` for a built `dist/`: links EACH ROUTE's own scoped-
+ * CSS href (`manifest.routeCss` — only the components that route's import
+ * graph actually reaches, not a global stylesheet shared by every page), and
+ * injects that route's island `<script type="module">` tags. Pass the result
+ * to `createApp`:
  *
  *   const { headExtras, buildId } = await loadProductionHead(dist)
  *   const app = await createApp({ ..., headExtras, buildId })
@@ -30,15 +32,8 @@ export async function loadProductionHead(distDir: string): Promise<{
 }> {
   const dist = resolve(distDir)
 
-  let cssTag = ''
-  try {
-    await stat(join(dist, 'static', 'components.css'))
-    cssTag = '<link rel="stylesheet" href="/static/components.css">'
-  } catch {
-    // no scoped component styles
-  }
-
   let routes: StatorManifest['routes'] = {}
+  let routeCss: StatorManifest['routeCss'] = {}
   let buildId: string | undefined
   let machines: Record<string, string> | undefined
   let config: string | null | undefined
@@ -48,6 +43,7 @@ export async function loadProductionHead(distDir: string): Promise<{
       await readFile(join(dist, 'stator-manifest.json'), 'utf8'),
     ) as StatorManifest
     routes = manifest.routes ?? {}
+    routeCss = manifest.routeCss ?? {}
     buildId = manifest.buildId
     machines = manifest.machines
     config = manifest.config
@@ -58,6 +54,8 @@ export async function loadProductionHead(distDir: string): Promise<{
 
   const headExtras = (filePath: string): string => {
     const rel = relative(dist, resolve(filePath)).replace(/\\/g, '/')
+    const href = routeCss[rel]
+    const cssTag = href ? `<link rel="stylesheet" href="${href}">` : ''
     const scripts = routes[rel] ?? []
     return [cssTag, ...scripts.map((url) => `<script type="module" src="${url}"></script>`)]
       .filter(Boolean)

package/src/build/route-css.ts

@@ -0,0 +1,211 @@
+import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { resolve } from 'node:path'
+import { walkFiles } from './islands.ts'
+
+/**
+ * Per-route scoped CSS (spec
+ * `stator-component-libraries-publish-time-compile-per-component-scoped-css-usage-driven-aggregation`).
+ * A separate reachability walk per route file. A reached module's CSS comes
+ * from its sibling `.css` file, resolved as a filesystem sibling (local) or
+ * through Node's module resolution (a `node_modules` package declaring
+ * `${specifier}.css` in its `exports` map) — `node_modules` is never traced
+ * beyond that one resolution.
+ *
+ * "Reached" is static import-graph reachability, not render-tracing: a
+ * component used only inside an inactive `match`/`when`/`each` arm is still
+ * reached, since a live SSE update can activate that arm later with no fresh
+ * HTTP request — its CSS must already be present at the route's first paint.
+ */
+
+const IMPORT_SPECIFIER_RE = /(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g
+
+export interface Reached {
+  local: Set<string>
+  external: Set<string>
+}
+
+/** Strip `/* *\/` and `//` comments before scanning for import specifiers,
+ *  so a doc-comment usage example isn't mistaken for a real import. Tracks
+ *  string/template-literal state so a `//` or `/*` inside one is left alone.
+ *  Not a full tokenizer (doesn't walk into `${...}` interpolation); errs
+ *  toward under-stripping. */
+function stripComments(code: string): string {
+  let out = ''
+  let i = 0
+  let inString: '"' | "'" | '`' | null = null
+  while (i < code.length) {
+    const c = code[i]!
+    const next = code[i + 1]
+    if (inString) {
+      out += c
+      if (c === '\\' && next !== undefined) {
+        out += next
+        i += 2
+        continue
+      }
+      if (c === inString) inString = null
+      i += 1
+      continue
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      inString = c
+      out += c
+      i += 1
+      continue
+    }
+    if (c === '/' && next === '/') {
+      const nl = code.indexOf('\n', i)
+      i = nl === -1 ? code.length : nl
+      continue
+    }
+    if (c === '/' && next === '*') {
+      const end = code.indexOf('*/', i + 2)
+      i = end === -1 ? code.length : end + 2
+      continue
+    }
+    out += c
+    i += 1
+  }
+  return out
+}
+
+/** A file's import specifiers, split by kind. Relative specifiers are
+ *  resolved and bounded to `baseDir`; bare specifiers are recorded verbatim,
+ *  never resolved or traced further here. */
+async function importsOf(
+  file: string,
+  baseDir: string,
+): Promise<{ local: string[]; external: string[] }> {
+  let code: string
+  try {
+    code = await readFile(file, 'utf8')
+  } catch {
+    return { local: [], external: [] }
+  }
+  code = stripComments(code)
+  const local: string[] = []
+  const external: string[] = []
+  for (const match of code.matchAll(IMPORT_SPECIFIER_RE)) {
+    const spec = match[1]!
+    if (spec.startsWith('.')) {
+      const target = resolve(file, '..', spec)
+      if (target.startsWith(baseDir)) local.push(target)
+    } else if (!spec.startsWith('node:')) {
+      external.push(spec)
+    }
+  }
+  return { local, external }
+}
+
+/** A file's direct bare-specifier imports only — no recursion, no relative
+ *  resolution. Used by `dev-native.ts`'s incremental graph tracking. */
+export async function bareSpecifiersOf(file: string): Promise<string[]> {
+  let code: string
+  try {
+    code = await readFile(file, 'utf8')
+  } catch {
+    return []
+  }
+  code = stripComments(code)
+  const external: string[] = []
+  for (const match of code.matchAll(IMPORT_SPECIFIER_RE)) {
+    const spec = match[1]!
+    if (!spec.startsWith('.') && !spec.startsWith('node:')) external.push(spec)
+  }
+  return external
+}
+
+async function walkReachable(
+  file: string,
+  baseDir: string,
+  seen: Set<string>,
+  out: Reached,
+): Promise<void> {
+  if (seen.has(file)) return
+  seen.add(file)
+  out.local.add(file)
+  const { local, external } = await importsOf(file, baseDir)
+  for (const spec of external) out.external.add(spec)
+  for (const target of local) await walkReachable(target, baseDir, seen, out)
+}
+
+/** Every local file and bare specifier reachable from one entry file's
+ *  import graph. */
+export async function reachableFrom(entryFile: string, baseDir: string): Promise<Reached> {
+  const reached: Reached = { local: new Set(), external: new Set() }
+  await walkReachable(resolve(entryFile), resolve(baseDir), new Set(), reached)
+  return reached
+}
+
+/** A reached local module's sibling CSS — `foo.ts` → `foo.css`. Most reached
+ *  modules have no sibling; that's a silent, expected miss. */
+async function siblingCss(file: string): Promise<string | undefined> {
+  const cssPath = file.replace(/\.(ts|js)$/, '.css')
+  if (cssPath === file) return undefined
+  try {
+    return await readFile(cssPath, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/** A bare specifier's published sibling stylesheet, if its package declares
+ *  one at `${specifier}.css` in its `exports` map. */
+export async function externalCss(specifier: string, fromDir: string): Promise<string | undefined> {
+  try {
+    const require = createRequire(resolve(fromDir, 'noop.cjs'))
+    const path = require.resolve(`${specifier}.css`)
+    return await readFile(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+function relFrom(baseDir: string, file: string): string {
+  return file.slice(baseDir.length + 1).replace(/\\/g, '/')
+}
+
+/** Collect the sibling CSS of everything in a `Reached` set, local and
+ *  external alike — one algorithm, no branching on origin. */
+async function cssOf(reached: Reached, baseDir: string): Promise<string> {
+  let css = ''
+  for (const file of [...reached.local].sort()) {
+    const text = await siblingCss(file)
+    if (text) css += `/* ${relFrom(baseDir, file)} */\n${text}\n`
+  }
+  for (const spec of [...reached.external].sort()) {
+    const text = await externalCss(spec, baseDir)
+    if (text) css += `/* ${spec} */\n${text}\n`
+  }
+  return css
+}
+
+/**
+ * Walk each route file's import graph and collect the sibling CSS of every
+ * reached module, local or external. Returns absolute route file → one
+ * concatenated stylesheet, only for routes that reached any CSS at all.
+ */
+export async function routeCssMap(opts: {
+  routesDir: string
+  baseDir: string
+}): Promise<Map<string, string>> {
+  const baseDir = resolve(opts.baseDir)
+  const routeFiles = await walkFiles(opts.routesDir, (f) => /\.(ts|js|stator)$/.test(f)).catch(
+    () => [] as string[],
+  )
+  const out = new Map<string, string>()
+  for (const routeFile of routeFiles) {
+    const reached = await reachableFrom(routeFile, baseDir)
+    const css = await cssOf(reached, baseDir)
+    if (css) out.set(routeFile, css)
+  }
+  return out
+}
+
+/** The same walk, rooted at a single entry file instead of a routes/
+ *  directory — e.g. a component library's own `components.css`. */
+export async function entryCss(entryFile: string, baseDir: string): Promise<string> {
+  const reached = await reachableFrom(entryFile, baseDir)
+  return cssOf(reached, baseDir)
+}

package/src/compiler/lower.ts

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { isVoidElement } from '../template/void-elements.ts'
 import { elementMarker, ISLAND_MARKER_ATTR, slotMarker } from '../wire/island-markers.ts'
 import { type ClientDirective, inferDeps } from './client-script.ts'
 import { CompileError, type DiagnosticLocation, locAt } from './diagnostics.ts'
@@ -476,7 +477,8 @@ export function lowerTemplate(template: string, opts: LowerOptions = {}): string
         return `\${${lowerComponent(tag, node.attributes, undefined)}}`
       }
       if (meta && tag.includes('-')) meta.customElements.add(tag)
-      return `<${tag}${lowerAttributes(node.attributes)}${scopeSuffix} />`
+      const open = `<${tag}${lowerAttributes(node.attributes)}${scopeSuffix}>`
+      return isVoidElement(tag) ? open : `${open}</${tag}>`
     }
     if (ts.isJsxFragment(node)) return contentOfChildren(node.children)
     throw new CompileError(

package/src/compiler/styles.ts

@@ -156,31 +156,54 @@ function scopeSelectorList(selector: string, attr: string): string {
 
       if (subjectIsGlobal) return
 
-      // Insert the scope attribute after the subject's last simple selector,
-      // before any trailing pseudo-elements (::before, ::after).
-      const nodes = sel.nodes
-      let insertAfter: selectorParser.Node | undefined
-      for (const node of nodes) {
-        if (node.type === 'combinator') {
-          insertAfter = undefined // reset at each combinator; track the subject only
-          continue
-        }
-        if (node.type === 'pseudo' && node.value.startsWith('::')) continue // pseudo-element stays last
-        insertAfter = node
-      }
-      const attrNode = selectorParser.attribute({
-        attribute: attr,
-        value: undefined,
-        raws: {},
-        quoteMark: null,
-      } as never)
-      if (insertAfter) sel.insertAfter(insertAfter as never, attrNode)
-      else sel.append(attrNode)
+      attachScopeAttr(sel, attr)
     })
   })
   return transform.processSync(selector)
 }
 
+function makeAttrNode(attr: string): selectorParser.Attribute {
+  return selectorParser.attribute({
+    attribute: attr,
+    value: undefined,
+    raws: {},
+    quoteMark: null,
+  } as never)
+}
+
+/** Insert the scope attribute after the subject's last simple selector,
+ *  before any trailing pseudo-elements (::before, ::after).
+ *
+ *  `:where(...)` is special-cased: by spec its specificity is always zero
+ *  regardless of its contents, so appending the attribute AFTER it
+ *  (`:where(img)[data-s-h]`) would add a real specificity point and defeat
+ *  that. The attribute goes INSIDE each of `:where()`'s own arguments instead
+ *  (`:where(img[data-s-h])`), recursively, keeping the compiled selector
+ *  genuinely zero-specificity. */
+function attachScopeAttr(sel: selectorParser.Selector, attr: string): void {
+  const nodes = sel.nodes
+  let insertAfter: selectorParser.Node | undefined
+  for (const node of nodes) {
+    if (node.type === 'combinator') {
+      insertAfter = undefined // reset at each combinator; track the subject only
+      continue
+    }
+    if (node.type === 'pseudo' && node.value.startsWith('::')) continue // pseudo-element stays last
+    insertAfter = node
+  }
+  if (!insertAfter) {
+    sel.append(makeAttrNode(attr))
+    return
+  }
+  if (insertAfter.type === 'pseudo' && insertAfter.value === ':where') {
+    for (const inner of insertAfter.nodes) {
+      attachScopeAttr(inner as selectorParser.Selector, attr)
+    }
+    return
+  }
+  sel.insertAfter(insertAfter as never, makeAttrNode(attr))
+}
+
 /** True when the selector's subject compound (after the last combinator) is
  *  inside a `:global(...)`. */
 function isSubjectGlobal(sel: selectorParser.Selector): boolean {

package/src/compiler/virtual-code.ts

@@ -19,6 +19,7 @@
  */
 
 import ts from 'typescript'
+import { VOID_ELEMENTS } from '../template/void-elements.ts'
 import { analyzeScriptClasses } from './client-script.ts'
 import { statorPropsType } from './dts.ts'
 import { CLIENT_AUTHOR_GLOBALS, TEMPLATE_AUTHOR_GLOBALS } from './emit-names.ts'
@@ -186,23 +187,6 @@ function buildServerTsx(regions: ScannedRegions): VirtualFile {
   return { lang: 'tsx', code, mappings }
 }
 
-/** HTML void elements — legal unclosed in templates, not in TSX. */
-const VOID_TAGS = new Set([
-  'area',
-  'base',
-  'br',
-  'col',
-  'embed',
-  'hr',
-  'img',
-  'input',
-  'link',
-  'meta',
-  'source',
-  'track',
-  'wbr',
-])
-
 /**
  * Append the template to the virtual TSX with HTML→TSX compatibility applied
  * AND offset mappings kept exact around every edit:
@@ -270,7 +254,7 @@ function appendTemplateTsx(
         if (ch === '>') break
         j++
       }
-      if (VOID_TAGS.has(tag.toLowerCase()) && j < tpl.length) {
+      if (VOID_ELEMENTS.has(tag.toLowerCase()) && j < tpl.length) {
         // Self-close unless the author already did.
         let k = j - 1
         while (k > i && /\s/.test(tpl[k]!)) k--

package/src/components/components.css

@@ -0,0 +1,8 @@
+/* components/image.stator.ts */
+/* height:auto preserves the aspect ratio the width/height attributes
+     declare; radius, margin, object-fit are the app's call. */
+:where(img[data-s-6e2813d6]) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}

package/src/components/image.stator

@@ -0,0 +1,37 @@
+---
+import { getImage, type ImageProps } from './images.ts'
+
+const p = Stator.props<ImageProps>()
+const {
+  alt,
+  class: className,
+  sizes = '100vw',
+  priority,
+  loading = priority ? 'eager' : 'lazy',
+  fetchpriority = priority ? 'high' : undefined,
+  decoding = 'async',
+} = p
+const img = getImage(p)
+---
+<img
+  src={img.src}
+  srcset={img.srcset ?? undefined}
+  sizes={img.srcset ? sizes : undefined}
+  alt={alt}
+  width={img.width}
+  height={img.height}
+  loading={loading}
+  fetchpriority={fetchpriority}
+  decoding={decoding}
+  class={className}
+/>
+
+<style>
+  /* height:auto preserves the aspect ratio the width/height attributes
+     declare; radius, margin, object-fit are the app's call. */
+  :where(img) {
+    display: block;
+    max-width: 100%;
+    height: auto;
+  }
+</style>

package/src/components/image.stator.css

@@ -0,0 +1,7 @@
+/* height:auto preserves the aspect ratio the width/height attributes
+     declare; radius, margin, object-fit are the app's call. */
+:where(img[data-s-6e2813d6]) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}

package/src/components/image.stator.ts

@@ -0,0 +1,29 @@
+import {
+  classList,
+  defer,
+  each,
+  html,
+  itemBind,
+  match,
+  on,
+  read,
+  spreadAttrs,
+  styleList,
+  when,
+} from '@statorjs/stator/template'
+import { getImage, type ImageProps } from './images.ts'
+
+export default function (props: ImageProps) {
+  const p = props
+  const {
+    alt,
+    class: className,
+    sizes = '100vw',
+    priority,
+    loading = priority ? 'eager' : 'lazy',
+    fetchpriority = priority ? 'high' : undefined,
+    decoding = 'async',
+  } = p
+  const img = getImage(p)
+  return html`<img src="${img.src}" srcset="${img.srcset ?? undefined}" sizes="${img.srcset ? sizes : undefined}" alt="${alt}" width="${img.width}" height="${img.height}" loading="${loading}" fetchpriority="${fetchpriority}" decoding="${decoding}" class="${className}" data-s-6e2813d6>`
+}

package/src/components/images.ts

@@ -1,11 +1,12 @@
 import { DEFAULT_IMAGE_WIDTHS } from '../server/images.ts'
 import { currentImages } from '../server/render-context.ts'
-import { html } from '../template/html.ts'
-import type { HtmlFragment } from '../template/types.ts'
 
 /**
- * `getImage()` + `<Image>`/`<Picture>` — the render half of framework image
- * support (spec `images-are-part-of-stator-*`; endpoint in `server/images.ts`).
+ * `getImage()`/`getPicture()` — pure math over provided dimensions, no
+ * markup (endpoint in `server/images.ts`). The `<Image>`/`<Picture>` markup
+ * components are `image.stator`/`picture.stator` in this directory; these
+ * two plus `SOURCE_TYPES` (the format→mime-type map) stay exported here as
+ * the public escape hatch for a custom art-direction component.
  *
  * `src` is the PUBLIC URL of the original: an image-endpoint path
  * (`/media/2026/08/x.jpg`) gets derived variants — the endpoint's contract is
@@ -154,31 +155,6 @@ export type ImageProps = GetImageOptions &
     class?: string
   }
 
-export function Image(props: ImageProps): HtmlFragment {
-  const {
-    alt,
-    class: className,
-    sizes = '100vw',
-    priority,
-    loading = priority ? 'eager' : 'lazy',
-    fetchpriority = priority ? 'high' : undefined,
-    decoding = 'async',
-  } = props
-  const img = getImage(props)
-  return html`<img
-    src="${img.src}"
-    srcset="${img.srcset ?? undefined}"
-    sizes="${img.srcset ? sizes : undefined}"
-    alt="${alt}"
-    width="${img.width}"
-    height="${img.height}"
-    loading="${loading}"
-    fetchpriority="${fetchpriority}"
-    decoding="${decoding}"
-    class="${className}"
-  />`
-}
-
 /** An art-directed source: under `media`, serve a different GEOMETRY — the
  *  `crop` ratio the endpoint cover-crops to, same vocabulary and same
  *  allowlist as the plain `crop` prop. Reach for `sources` when the geometry
@@ -201,20 +177,45 @@ export type PictureProps = ImageProps & {
   sources?: PictureSource[]
 }
 
-const SOURCE_TYPES: Record<ImageFormat, string> = {
+/** `<source type>` for each delivery format — exported alongside `getPicture`
+ *  so a hand-rolled `<picture>` (art direction the first-party `<Picture>`
+ *  doesn't cover) can build its own `<source>` tags from `getImage`/
+ *  `getPicture` output without re-deriving this mapping. */
+export const SOURCE_TYPES: Record<ImageFormat, string> = {
   jpg: 'image/jpeg',
   png: 'image/png',
   webp: 'image/webp',
   avif: 'image/avif',
 }
 
-export function Picture(props: PictureProps): HtmlFragment {
+/** One resolved `<source>` candidate, most-specific (art-directed) first. */
+export interface ResolvedPictureSource {
+  media?: string
+  format: ImageFormat
+  srcset: string
+  sizes: string
+}
+
+export interface ResolvedPicture {
+  /** `<source>` candidates — empty when `src` is remote or no candidate
+   *  produced a srcset, in which case only `image` (the plain `<img>`) applies. */
+  sources: ResolvedPictureSource[]
+  /** The fallback `<img>`'s own resolved data — same shape `getImage()` returns,
+   *  built from the same props the sources were (`crop` included, so its
+   *  reserved box describes the cropped output rather than the source's own
+   *  shape). */
+  image: ResolvedImage
+}
+
+/** Pure `<picture>` math: every `<source>` candidate's resolved srcset plus
+ *  the fallback `<img>`'s own resolved data — no markup. `<Picture>` renders
+ *  this; a custom art-direction component that needs a different `<picture>`
+ *  shape than `<Picture>` offers can call this directly instead. */
+export function getPicture(props: PictureProps): ResolvedPicture {
   const { formats = ['avif', 'webp'], sources: artSources = [], sizes = '100vw', ...rest } = props
-  // The fallback <img> is built from the same props the sources were — `crop`
-  // included, so its reserved box describes the cropped output rather than the
-  // source's own shape.
   const imageProps = { ...rest, sizes } as ImageProps
-  if (isRemote(rest.src)) return Image(imageProps)
+  const image = getImage(imageProps)
+  if (isRemote(rest.src)) return { sources: [], image }
 
   const storedExt = rest.src.slice(rest.src.lastIndexOf('.') + 1).toLowerCase() as ImageFormat
 
@@ -242,19 +243,11 @@ export function Picture(props: PictureProps): HtmlFragment {
   )
   const plain = formats
     .map((format) => ({
-      media: undefined,
       format,
       srcset: getImage({ ...imageProps, format }).srcset,
       sizes,
     }))
     .filter((s) => s.srcset !== null)
 
-  const all = [...art, ...plain]
-  if (all.length === 0) return Image(imageProps)
-  return html`<picture
-    >${all.map(
-      (s) =>
-        html`<source media="${s.media ?? undefined}" type="${SOURCE_TYPES[s.format]}" srcset="${s.srcset}" sizes="${s.sizes}" />`,
-    )}${Image(imageProps)}</picture
-  >`
+  return { sources: [...art, ...plain] as ResolvedPictureSource[], image }
 }

package/src/components/index.ts

@@ -1,3 +1,6 @@
+// Compiled sibling, not the raw `.stator` source — keep fresh with
+// `pnpm build:components`.
+export { default as Image } from './image.stator.ts'
 export type {
   GetImageOptions,
   ImageFormat,
@@ -6,7 +9,10 @@ export type {
   PictureProps,
   PictureSource,
   ResolvedImage,
+  ResolvedPicture,
+  ResolvedPictureSource,
 } from './images.ts'
-export { getImage, Image, Picture } from './images.ts'
+export { getImage, getPicture, SOURCE_TYPES } from './images.ts'
 export type { JsonLdProps } from './json-ld.ts'
 export { JsonLd, ldToString } from './json-ld.ts'
+export { default as Picture } from './picture.stator.ts'

package/src/components/json-ld.ts

@@ -24,48 +24,27 @@ export function JsonLd(props: JsonLdProps): HtmlFragment {
   return raw(`<script type="application/ld+json">${ldToString(props.json, props.space)}</script>`)
 }
 
-type JsonValueScalar = string | boolean | number
-type JsonValue = JsonValueScalar | Array<JsonValue> | { [key: string]: JsonValue }
-type JsonReplacer = (_: string, value: JsonValue) => JsonValue | undefined
+type JsonValue = string | boolean | number | null | Array<JsonValue> | { [key: string]: JsonValue }
 
-const ESCAPE_ENTITIES = Object.freeze({
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&apos;',
-})
-const ESCAPE_REGEX = new RegExp(`[${Object.keys(ESCAPE_ENTITIES).join('')}]`, 'g')
-const ESCAPE_REPLACER = (t: string): string => ESCAPE_ENTITIES[t as keyof typeof ESCAPE_ENTITIES]
+const stripNulls = (_: string, value: JsonValue): JsonValue | undefined =>
+  value === null ? undefined : value
 
 /**
- * A `JSON.stringify` replacer that strips JSON-LD of HTML sequences illegal in a
- * `<script>` element, per
+ * Escape the serialized JSON for a `<script>` element, per
  * https://www.w3.org/TR/json-ld11/#restrictions-for-contents-of-json-ld-script-elements
- * Escaping `<`/`>` is what guarantees no `</script>` breakout in the raw output.
+ * Script content is raw text to the HTML parser, so HTML entities would reach
+ * consumers literally; JSON `\uXXXX` escapes decode back to the real characters.
+ * Escaping `<` is what guarantees no `</script>` breakout.
  */
-const safeJsonLdReplacer: JsonReplacer = (_: string, value: JsonValue): JsonValue | undefined => {
-  switch (typeof value) {
-    case 'object':
-      // Omit null values.
-      if (value === null) return undefined
-      return value // JSON.stringify recurses, re-applying this replacer.
-    case 'number':
-    case 'boolean':
-    case 'bigint':
-      return value // Not risky.
-    case 'string':
-      return value.replace(ESCAPE_REGEX, ESCAPE_REPLACER)
-    default: {
-      // No other types are expected; JSON.stringify drops an `undefined` return.
-      isNever(value)
-      return undefined
-    }
-  }
+function escapeForScript(json: string): string {
+  return json
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
 }
 
-function isNever(_: never): void {}
-
 function withContext<T extends Thing>(thing: T): WithContext<T> {
   return {
     '@context': 'https://schema.org',
@@ -81,5 +60,5 @@ function asGraph(things: Thing[]): Graph {
  *  JSON-LD string, safe to embed verbatim in a `<script>` element. */
 export function ldToString(json: Thing | Thing[], space?: number | string): string {
   const ld = Array.isArray(json) ? asGraph(json) : withContext(json)
-  return JSON.stringify(ld, safeJsonLdReplacer, space)
+  return escapeForScript(JSON.stringify(ld, stripNulls, space))
 }

package/src/components/picture.stator

@@ -0,0 +1,17 @@
+---
+import { getPicture, SOURCE_TYPES, type PictureProps } from './images.ts'
+import Image from './image.stator'
+
+const p = Stator.props<PictureProps>()
+const { sources } = getPicture(p)
+---
+{sources.length === 0 ? (
+  <Image {...p} />
+) : (
+  <picture>
+    {each(sources, (s) => (
+      <source media={s.media} type={SOURCE_TYPES[s.format]} srcset={s.srcset} sizes={s.sizes} />
+    ))}
+    <Image {...p} />
+  </picture>
+)}

package/src/components/picture.stator.ts

@@ -0,0 +1,21 @@
+import {
+  classList,
+  defer,
+  each,
+  html,
+  itemBind,
+  match,
+  on,
+  read,
+  spreadAttrs,
+  styleList,
+  when,
+} from '@statorjs/stator/template'
+import Image from './image.stator.ts'
+import { getPicture, type PictureProps, SOURCE_TYPES } from './images.ts'
+
+export default function (props: PictureProps) {
+  const p = props
+  const { sources } = getPicture(p)
+  return html`${sources.length === 0 ? html`${Image({ ...p })}` : html`<picture>${each(sources, (s) => html`<source media="${s.media}" type="${SOURCE_TYPES[s.format]}" srcset="${s.srcset}" sizes="${s.sizes}">`)}${Image({ ...p })}</picture>`}`
+}

package/src/server/create-app.ts

@@ -90,8 +90,8 @@ export interface CreateAppConfig extends DeprecatedFlatConfig {
   host?: string
   /** Cross-origin READ policy (CORS); `origins` defaults to `trustedOrigins`. */
   cors?: { origins?: string[]; credentials?: boolean }
-  /** Extra `<head>` HTML per GET route. A production build uses this to link the
-   *  prebuilt `components.css`; ignored if omitted. */
+  /** Extra `<head>` HTML per GET route. A production build uses this to link
+   *  that route's own prebuilt scoped-CSS artifact; ignored if omitted. */
   headExtras?: (filePath: string) => string | Promise<string>
   /** Path to the app's `middleware.ts` (if any). Loaded and validated; its
    *  default export must be `defineMiddleware`/`dangerouslyDefineMiddleware`. */

package/src/server/dev-native.ts

@@ -16,6 +16,7 @@ import {
   routeIslandMap,
   walkFiles,
 } from '../build/islands.ts'
+import { bareSpecifiersOf, externalCss } from '../build/route-css.ts'
 import { sourceId } from '../build/source-id.ts'
 import { CompileError, compile, formatCompileError, regionResolverFor } from '../compiler/index.ts'
 import type { AnyMachineDef, EventOf } from '../engine/index.ts'
@@ -59,8 +60,8 @@ import { InMemoryStore } from './store.ts'
  *    graph serving and renders the error (with its code frame) in an overlay.
  *  - **Scoped CSS + island scripts** — islands bundle through the
  *    `bundleIslands` seam (Vite today, never on the SSR path) and are served
- *    from memory with the concatenated scoped CSS, on the same URLs and with
- *    the same `<head>` shape as production.
+ *    from memory with the concatenated scoped CSS, local and `node_modules`
+ *    alike, on the same URLs and with the same `<head>` shape as production.
  *
  * See spec `toolchain-adapter-seam-and-the-vite-exit`.
  */
@@ -164,6 +165,9 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
   const versions = new Map<string, number>()
   const forward = new Map<string, Set<string>>()
   const importers = new Map<string, Set<string>>()
+  // Bare specifiers each app file imports directly, feeding the CSS
+  // aggregate below via each package's own sibling `.css` (`externalCss`).
+  const externalSpecs = new Map<string, Set<string>>()
   let seq = 0
   const acks = new Map<number, () => void>()
   port1.on('message', (m: { type?: string; id?: number }) => {
@@ -274,11 +278,16 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
     }
   }
   const updateEdges = async (files: string[]): Promise<void> => {
-    for (const f of files) setEdges(f, new Set((await localImports(f, root)).filter(isAppFile)))
+    for (const f of files) {
+      const [local, external] = await Promise.all([localImports(f, root), bareSpecifiersOf(f)])
+      setEdges(f, new Set(local.filter(isAppFile)))
+      externalSpecs.set(f, new Set(external))
+    }
   }
   const buildGraph = async (): Promise<void> => {
     forward.clear()
     importers.clear()
+    externalSpecs.clear()
     await updateEdges(await walkFiles(root, (f) => APP_EXT.test(f), skipDir))
   }
   /** The changed files plus everything that (transitively) imports them. */
@@ -314,10 +323,17 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
     }
   }
   let css = ''
-  const regenCss = (): void => {
-    css = ''
+  const regenCss = async (): Promise<void> => {
+    let next = ''
     for (const [file, info] of infos)
-      if (info.css) css += `/* ${sourceId(root, file).id} */\n${info.css}\n`
+      if (info.css) next += `/* ${sourceId(root, file).id} */\n${info.css}\n`
+    const packages = new Set<string>()
+    for (const specs of externalSpecs.values()) for (const spec of specs) packages.add(spec)
+    for (const spec of [...packages].sort()) {
+      const text = await externalCss(spec, root)
+      if (text) next += `/* ${spec} */\n${text}\n`
+    }
+    css = next
   }
 
   // ── Islands: bundled through the seam, held in memory ──────────────────────
@@ -449,7 +465,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
 
   await scanAll()
   await buildGraph()
-  regenCss()
+  await regenCss()
   await rebundleIslands()
   await rebuildStore()
   await rebuildServer()
@@ -478,7 +494,7 @@ export async function createNativeDevApp(config: DevAppConfig): Promise<NativeDe
       }
       const affected = affectedBy(files)
       await bumpVersions(affected)
-      regenCss()
+      await regenCss()
       const needsBundle =
         structural || files.some((f) => islandGraph.has(norm(f)) || infos.get(f)?.isClient)
       if (needsBundle) {

package/src/template/each.ts

@@ -17,6 +17,7 @@ import {
 } from '../server/render-context.ts'
 import { isReadResult, type ReadResult } from './read.ts'
 import { type HtmlFragment, isHtmlFragment } from './types.ts'
+import { VOID_ELEMENTS } from './void-elements.ts'
 
 export interface EachOptions<T> {
   /** Item identity. When present, list changes emit per-item insert/remove/move
@@ -298,23 +299,6 @@ export function renderKeyedItem<T>(
   return { html, bindings }
 }
 
-const VOID_TAGS = new Set([
-  'area',
-  'base',
-  'br',
-  'col',
-  'embed',
-  'hr',
-  'img',
-  'input',
-  'link',
-  'meta',
-  'param',
-  'source',
-  'track',
-  'wbr',
-])
-
 /**
  * True when `html` consists of exactly one root element (plus optional
  * surrounding whitespace). A small scanner, quote- and comment-aware — not a
@@ -361,7 +345,7 @@ export function isSingleRootElement(html: string): boolean {
     } else {
       const nameMatch = html.slice(i + 1, j).match(/^([a-zA-Z][\w-]*)/)
       const tag = nameMatch ? nameMatch[1]!.toLowerCase() : ''
-      const selfClosing = html[j - 1] === '/' || VOID_TAGS.has(tag)
+      const selfClosing = html[j - 1] === '/' || VOID_ELEMENTS.has(tag)
       if (depth === 0) {
         roots++
         if (roots > 1) return false

package/src/template/html-attributes.ts

@@ -73,6 +73,14 @@ export interface ElementSpecificAttributes {
     autofocus?: boolean
     popovertarget?: string
     popovertargetaction?: 'show' | 'hide' | 'toggle'
+    /** Per-button overrides of the owning form's submission settings — the
+     *  standard way to point one submit button in a multi-action form at a
+     *  different endpoint without a second `<form>`. */
+    formaction?: string
+    formenctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'
+    formmethod?: 'get' | 'post' | 'dialog'
+    formnovalidate?: boolean
+    formtarget?: string
   }
   input: {
     type?: string
@@ -99,6 +107,12 @@ export interface ElementSpecificAttributes {
      *  the form's own DOM subtree (e.g. a per-row control alongside a
      *  page-wide bulk-action form). `button` already carries this. */
     form?: string
+    /** Submission overrides for `type="submit"` / `type="image"`; same as on `button`. */
+    formaction?: string
+    formenctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain'
+    formmethod?: 'get' | 'post' | 'dialog'
+    formnovalidate?: boolean
+    formtarget?: string
   }
   label: { for?: string }
   form: {

package/src/template/void-elements.ts

@@ -0,0 +1,23 @@
+/** HTML void elements: no content, no closing tag, and a trailing `/` is
+ *  meaningless. Every other element must be explicitly closed — browsers
+ *  parse `<div />` as an open tag. `param` is obsolete but still void. */
+export const VOID_ELEMENTS: ReadonlySet<string> = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+])
+
+export function isVoidElement(tag: string): boolean {
+  return VOID_ELEMENTS.has(tag.toLowerCase())
+}