@statorjs/stator 1.0.0

package/src/compiler/compile.ts

@@ -0,0 +1,459 @@
+import ts from 'typescript'
+import { emitClientModule } from './client-emit.ts'
+import {
+  analyzeClient,
+  analyzeScriptClasses,
+  type ClientDirective,
+  isCustomElementTag,
+  pascalToKebab,
+} from './client-script.ts'
+import { CompileError, type DiagnosticLocation, locAt } from './diagnostics.ts'
+import { scopeHash } from './hash.ts'
+import { type LowerMeta, lowerTemplate } from './lower.ts'
+import { splitStator } from './split.ts'
+import { scopeCss } from './styles.ts'
+
+/**
+ * Assemble a `.stator` source into the server `.ts` module the runtime
+ * consumes. Phase 3a: server module only (template + frontmatter). Styles and
+ * the client `<script>` are layered in later stages.
+ *
+ * Frontmatter handling:
+ *   - import / type / interface declarations hoist to the module top
+ *   - the template runtime primitives are auto-injected (authors write JSX +
+ *     `{read(...)}`, never `import ... from '@statorjs/stator/template'` for these)
+ *   - other statements (notably `const { x } = Stator.props<P>()`) move inside
+ *     the rendered function, with `Stator.props<P>()` rewritten to the `props`
+ *     parameter and `P` lifted to the parameter's type
+ */
+
+export interface CompileResult {
+  /** The server render module source (shell render for a client component). */
+  serverCode: string
+  /** Per-component scope hash (the `data-s-<hash>` marker uses it). */
+  scopeHash: string
+  /** Scoped CSS, ready for the Vite CSS pipeline. Empty when there's no
+   *  `<style>`. */
+  css: string
+  /** Raw client `<script>` regions, as authored. */
+  scripts: string[]
+  /** True when this `.stator` is a client component (whole-file custom element). */
+  isClient: boolean
+  /** The generated client entry module (Phase 3b) — the `StatorElement` subclass
+   *  + `setup()` + `defineElement`. Empty for server components. */
+  clientCode: string
+  /** Custom-element tag this client component defines (e.g. `quantity-stepper`),
+   *  or undefined for a server component. */
+  clientTag?: string
+}
+
+const PRIMITIVES_IMPORT =
+  "import { html, read, each, when, match, on, classList, styleList } from '@statorjs/stator/template'"
+
+export interface CompileOptions {
+  /** Stable id for the component (file path). Used for the scope hash so the
+   *  hash is stable across edits to unrelated files; falls back to the source.
+   *  Also the diagnostics file path. */
+  id?: string
+  /** Whether this file is a route page or a reusable component. Gates the
+   *  frontmatter capability matrix (request/response, reads, props, pragmas).
+   *  Defaults to 'component'. The Vite plugin / build sets it from the directory. */
+  kind?: 'route' | 'component'
+  /** Resolve a component identifier (used in this file) to the named regions it
+   *  declares, for cross-file `child="x"` validation. The Vite plugin / build
+   *  supplies this (reads sibling `.stator` files). Omitted → validation skipped. */
+  resolveRegions?: (componentName: string) => Set<string> | null
+}
+
+export function compile(source: string, opts: CompileOptions = {}): CompileResult {
+  const { frontmatter, template, styles, scripts, scriptOffsets, templateOffset } =
+    splitStator(source)
+  const kind = opts.kind ?? 'component'
+
+  const hasStyles = styles.length > 0
+  const hash = scopeHash(opts.id ?? source)
+  const scopeAttr = hasStyles ? `data-s-${hash}` : undefined
+
+  // An inline `<script>` makes this a *client component* (a whole-file custom
+  // element) — a different compile path entirely. It must export a
+  // `StatorElement`; one that doesn't is a malformed component, not literal
+  // markup, so we surface it rather than silently dropping the script.
+  const script = scripts.join('\n')
+  if (script.trim()) {
+    if (analyzeScriptClasses(script).length > 0) {
+      return compileClient(template, script, {
+        hash,
+        scopeAttr,
+        styles,
+        file: opts.id,
+      })
+    }
+    throw new CompileError(
+      `stator: this <script> exports no StatorElement subclass. An inline <script> in a ` +
+        `.stator file is compiled as a client component — add ` +
+        `\`export class … extends StatorElement { … }\`. To emit a literal script instead, ` +
+        `mark it \`<script is:inline>…</script>\` (verbatim inline) or use ` +
+        `\`<script src="…">\` (external file).`,
+      locAt(source, scriptOffsets[0] ?? 0, opts.id),
+    )
+  }
+
+  const meta: LowerMeta = {
+    usesChildren: false,
+    regions: new Set(),
+    components: new Set(),
+    customElements: new Set(),
+    refs: new Set(),
+  }
+  const htmlExpr = lowerTemplate(template, {
+    scopeAttr,
+    source,
+    templateOffset,
+    file: opts.id,
+    meta,
+    resolveRegions: opts.resolveRegions,
+  })
+  const css = hasStyles ? scopeCss(styles.join('\n'), hash) : ''
+
+  const fm = processFrontmatter(frontmatter, kind, source, opts.id)
+  const serverCode =
+    kind === 'route' ? emitRoute(fm, htmlExpr, meta) : emitComponent(fm, htmlExpr, meta)
+
+  return {
+    serverCode,
+    scopeHash: hash,
+    css,
+    scripts,
+    isClient: false,
+    clientCode: '',
+  }
+}
+
+/**
+ * Compile a client component: its template root is the custom element, the
+ * `<script>` defines the matching class. Produces (i) a server shell render
+ * module — `(props) => HtmlFragment` rendering the custom-element tag with the
+ * declared attrs + inner shell (markers + children) — and (ii) the client entry
+ * module (the `StatorElement` subclass + wiring).
+ */
+function compileClient(
+  template: string,
+  script: string,
+  ctx: { hash: string; scopeAttr?: string; styles: string[]; file?: string },
+): CompileResult {
+  const classes = analyzeScriptClasses(script)
+  const root = extractClientRoot(template, ctx.file)
+
+  // Name-match validation (both directions, hyphen rule).
+  const tags = new Set([root.tag])
+  analyzeClient(script, tags, { file: ctx.file })
+
+  const cls = classes.find((c) => pascalToKebab(c.name) === root.tag)
+  if (!cls) {
+    // analyzeClient validated the tag↔class match just above; reaching here is a bug.
+    throw new CompileError(
+      `stator: internal — no exported class matches root <${root.tag}> after name validation`,
+    )
+  }
+
+  // Lower the inner shell in client mode: collect bind:/on:, strip them, inject
+  // markers. Plain expressions (props access, maps with nested JSX, read())
+  // flow through to the SHELL and evaluate server-side per use — the hydrate
+  // pattern; see the client-components guide.
+  const directives: ClientDirective[] = []
+  const meta: LowerMeta = {
+    usesChildren: false,
+    regions: new Set(),
+    components: new Set(),
+    customElements: new Set(),
+    refs: new Set(),
+  }
+  // Client components scope styles by DESCENDANT of the root (the class may
+  // create DOM at runtime — per-element attrs could never reach it), so the
+  // inner template needs no per-element stamping: only the root carries the
+  // scope attribute.
+  const innerExpr = lowerTemplate(root.inner, {
+    file: ctx.file,
+    meta,
+    client: { useFields: new Set(cls.useFields.keys()), directives },
+  })
+
+  const css = ctx.styles.length
+    ? scopeCss(ctx.styles.join('\n'), ctx.hash, { strategy: 'descendant', rootTag: root.tag })
+    : ''
+
+  // Server shell module: <tag {attrs}{scope}>{inner}</tag>.
+  const attrDecl = `{ ${[...cls.staticAttrs].map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')} }`
+  const rootScope = ctx.scopeAttr ? ` data-s-${ctx.hash}` : ''
+  const serverCode = [
+    "import { html, read, each, when, match, on, classList, styleList, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
+    '',
+    `export default function (props = {}) {`,
+    `  const __inner = ${innerExpr}`,
+    `  const __attrs = clientShellAttrs(props, ${attrDecl})`,
+    `  return createHtmlFragment(\`<${root.tag}\${__attrs}${rootScope}>\` + __inner.html + \`</${root.tag}>\`)`,
+    '}',
+    '',
+  ].join('\n')
+
+  const clientCode = emitClientModule({
+    script,
+    element: { tag: root.tag, className: cls.name },
+    directives,
+    members: cls.members,
+  })
+
+  return {
+    serverCode,
+    scopeHash: ctx.hash,
+    css,
+    scripts: [script],
+    isClient: true,
+    clientCode,
+    clientTag: root.tag,
+  }
+}
+
+/** Parse a client template, returning the custom-element root tag and the inner
+ *  source (its children). Enforces "root must be the custom element". */
+function extractClientRoot(template: string, file?: string): { tag: string; inner: string } {
+  const wrapped = `const __t = (<>${template}</>);`
+  const sf = ts.createSourceFile('t.tsx', wrapped, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+  let fragment: ts.JsxFragment | undefined
+  const find = (n: ts.Node): void => {
+    if (ts.isJsxFragment(n)) {
+      fragment = n
+      return
+    }
+    ts.forEachChild(n, find)
+  }
+  find(sf)
+  const elements = (fragment?.children ?? []).filter(
+    (c) => ts.isJsxElement(c) || ts.isJsxSelfClosingElement(c),
+  )
+  if (elements.length !== 1) {
+    throw new CompileError(
+      'stator: a client component must have a single custom-element root.',
+      file ? { file, line: 1, column: 1, frame: '' } : undefined,
+    )
+  }
+  const rootEl = elements[0]!
+  if (ts.isJsxSelfClosingElement(rootEl)) {
+    const tag = rootEl.tagName.getText(sf)
+    requireCustomRoot(tag, file)
+    return { tag, inner: '' }
+  }
+  const el = rootEl as ts.JsxElement
+  const tag = el.openingElement.tagName.getText(sf)
+  requireCustomRoot(tag, file)
+  const inner = wrapped.slice(el.openingElement.getEnd(), el.closingElement.getStart())
+  return { tag, inner }
+}
+
+function requireCustomRoot(tag: string, file?: string): void {
+  if (!isCustomElementTag(tag)) {
+    throw new CompileError(
+      `stator: a client component's root must be a custom element (a hyphenated tag like ` +
+        `<my-widget>), found <${tag}>. A nested custom element under server chrome isn't allowed.`,
+      file ? { file, line: 1, column: 1, frame: '' } : undefined,
+    )
+  }
+}
+
+interface FrontmatterParts {
+  hoisted: string
+  body: string
+  propsType?: string
+  /** Route only: the machine identifiers from `Stator.reads([...])`. */
+  reads: string[]
+  /** Route only: pragma flags (`// @stator live`). */
+  pragmas: Set<string>
+}
+
+const VALID_PRAGMAS = new Set(['live'])
+
+/**
+ * Split frontmatter into hoisted declarations (imports/types) and function-body
+ * statements, rewriting the `Stator.*` markers per file kind and enforcing the
+ * capability matrix.
+ *
+ * Component: `Stator.props<P>()` → `props`. Route/request/response/pragmas are
+ * errors. Route: `Stator.reads([A,B])` RHS → `[__ctx[A.name], __ctx[B.name]]`
+ * (and `[A,B]` captured for the `reads:` config); `Stator.request` → `__req`;
+ * `Stator.response` → `__ctx.response`. `Stator.props` is an error.
+ */
+function processFrontmatter(
+  fm: string,
+  kind: 'route' | 'component',
+  source: string,
+  file?: string,
+): FrontmatterParts {
+  const pragmas = parsePragmas(fm, kind, source, file)
+  if (!fm.trim()) return { hoisted: '', body: '', reads: [], pragmas }
+
+  const sf = ts.createSourceFile('fm.ts', fm, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  const hoisted: string[] = []
+  const body: string[] = []
+  let propsType: string | undefined
+  const reads: string[] = []
+
+  const locInFm = (node: ts.Node): DiagnosticLocation =>
+    locAt(source, fmOffset(source) + node.getStart(sf), file)
+
+  for (const stmt of sf.statements) {
+    if (
+      ts.isImportDeclaration(stmt) ||
+      ts.isTypeAliasDeclaration(stmt) ||
+      ts.isInterfaceDeclaration(stmt)
+    ) {
+      hoisted.push(stmt.getText(sf))
+      continue
+    }
+
+    const stmtStart = stmt.getStart(sf)
+    let text = stmt.getText(sf)
+    const repls: Array<[start: number, end: number, replacement: string]> = []
+    const visit = (n: ts.Node): void => {
+      if (ts.isCallExpression(n) && isStatorCall(n, 'props')) {
+        if (kind === 'route') {
+          throw new CompileError(
+            'stator: Stator.props() is not available in a route page (a route has no parent props). ' +
+              'Use Stator.reads([...]) to access machines.',
+            locInFm(n),
+          )
+        }
+        if (n.typeArguments && n.typeArguments.length > 0) {
+          propsType = n.typeArguments[0]!.getText(sf)
+        }
+        repls.push([n.getStart(sf), n.getEnd(), 'props'])
+        return
+      }
+      if (ts.isCallExpression(n) && isStatorCall(n, 'reads')) {
+        if (kind !== 'route') {
+          throw new CompileError(
+            'stator: Stator.reads() is only available in a route page. ' +
+              'A component receives machines as props.',
+            locInFm(n),
+          )
+        }
+        const arg = n.arguments[0]
+        if (!arg || !ts.isArrayLiteralExpression(arg)) {
+          throw new CompileError('stator: Stator.reads(...) takes an array of machines', locInFm(n))
+        }
+        const ids = arg.elements.map((el) => el.getText(sf))
+        reads.push(...ids)
+        const bound = `[${ids.map((id) => `__ctx[${id}.name]`).join(', ')}]`
+        repls.push([n.getStart(sf), n.getEnd(), bound])
+        return
+      }
+      if (ts.isPropertyAccessExpression(n) && isStatorMember(n, 'request')) {
+        requireRoute('Stator.request', kind, locInFm(n))
+        repls.push([n.getStart(sf), n.getEnd(), '__req'])
+        return
+      }
+      if (ts.isPropertyAccessExpression(n) && isStatorMember(n, 'response')) {
+        requireRoute('Stator.response', kind, locInFm(n))
+        repls.push([n.getStart(sf), n.getEnd(), '__ctx.response'])
+        return
+      }
+      ts.forEachChild(n, visit)
+    }
+    visit(stmt)
+    repls.sort((a, b) => b[0] - a[0])
+    for (const [start, end, replacement] of repls) {
+      text = text.slice(0, start - stmtStart) + replacement + text.slice(end - stmtStart)
+    }
+    body.push(`  ${text}`)
+  }
+
+  return {
+    hoisted: hoisted.join('\n'),
+    body: body.join('\n'),
+    propsType,
+    reads,
+    pragmas,
+  }
+}
+
+function emitComponent(fm: FrontmatterParts, htmlExpr: string, meta: LowerMeta): string {
+  let param = ''
+  if (fm.propsType && meta.usesChildren) param = `props: ${fm.propsType} & { children?: any }`
+  else if (fm.propsType) param = `props: ${fm.propsType}`
+  else if (meta.usesChildren) param = `props: { children?: any }`
+
+  const lines = [PRIMITIVES_IMPORT]
+  if (fm.hoisted) lines.push(fm.hoisted)
+  lines.push('')
+  lines.push(`export default function (${param}) {`)
+  if (fm.body) lines.push(fm.body)
+  lines.push(`  return ${htmlExpr}`)
+  lines.push('}')
+  return `${lines.join('\n')}\n`
+}
+
+function emitRoute(fm: FrontmatterParts, htmlExpr: string, _meta: LowerMeta): string {
+  const lines = [PRIMITIVES_IMPORT, "import { defineRoute } from '@statorjs/stator/server'"]
+  if (fm.hoisted) lines.push(fm.hoisted)
+  lines.push('')
+  lines.push('export const GET = defineRoute({')
+  lines.push(`  reads: [${fm.reads.join(', ')}],`)
+  if (fm.pragmas.has('live')) lines.push('  live: true,')
+  lines.push('  render: (__ctx, __req) => {')
+  if (fm.body) lines.push(fm.body)
+  lines.push(`    return ${htmlExpr}`)
+  lines.push('  },')
+  lines.push('})')
+  return `${lines.join('\n')}\n`
+}
+
+/** Parse `// @stator <flag>` comment pragmas from the frontmatter text. */
+function parsePragmas(
+  fm: string,
+  kind: 'route' | 'component',
+  source: string,
+  file?: string,
+): Set<string> {
+  const out = new Set<string>()
+  const re = /\/\/\s*@stator\s+(\S+)/g
+  for (const m of fm.matchAll(re)) {
+    const flag = m[1]!
+    if (!VALID_PRAGMAS.has(flag)) {
+      throw new CompileError(
+        `stator: unknown pragma "// @stator ${flag}". Known flags: ${[...VALID_PRAGMAS].join(', ')}.`,
+        locAt(source, fmOffset(source) + m.index, file),
+      )
+    }
+    if (kind !== 'route') {
+      throw new CompileError(
+        `stator: "// @stator ${flag}" is only valid in a route page, not a component.`,
+        locAt(source, fmOffset(source) + m.index, file),
+      )
+    }
+    out.add(flag)
+  }
+  return out
+}
+
+function requireRoute(what: string, kind: 'route' | 'component', loc: DiagnosticLocation): void {
+  if (kind !== 'route') {
+    throw new CompileError(
+      `stator: ${what} is only available in a route page, not a component. ` +
+        `Read it in the route and pass the value down as a prop.`,
+      loc,
+    )
+  }
+}
+
+/** Character offset of the frontmatter body in the original source (after the
+ *  opening `---\n`). 4 = `---\n`; good enough for diagnostics line/col. */
+function fmOffset(source: string): number {
+  return source.startsWith('---') ? source.indexOf('\n') + 1 : 0
+}
+
+function isStatorCall(call: ts.CallExpression, member: string): boolean {
+  return ts.isPropertyAccessExpression(call.expression) && isStatorMember(call.expression, member)
+}
+
+function isStatorMember(e: ts.PropertyAccessExpression, member: string): boolean {
+  return ts.isIdentifier(e.expression) && e.expression.text === 'Stator' && e.name.text === member
+}

package/src/compiler/diagnostics.ts

@@ -0,0 +1,65 @@
+/**
+ * Compiler diagnostics: a located `CompileError` plus helpers to turn a
+ * character offset in the original `.stator` source into a line/column + code
+ * frame. Every compiler stage throws `CompileError`; the Vite plugin maps its
+ * `loc` to Vite's error shape so the dev overlay and terminal show
+ * file:line:column with a snippet.
+ */
+
+export interface DiagnosticLocation {
+  file?: string
+  /** 1-based line in the original `.stator` source. */
+  line: number
+  /** 1-based column. */
+  column: number
+  /** Rendered code-frame snippet (a few lines around the caret). */
+  frame: string
+}
+
+export class CompileError extends Error {
+  readonly loc?: DiagnosticLocation
+  constructor(message: string, loc?: DiagnosticLocation) {
+    super(message)
+    this.name = 'CompileError'
+    this.loc = loc
+  }
+}
+
+/** 1-based line/column for a character offset in `source`. */
+export function offsetToLineCol(source: string, offset: number): { line: number; column: number } {
+  const clamped = Math.max(0, Math.min(offset, source.length))
+  let line = 1
+  let lastNewline = -1
+  for (let i = 0; i < clamped; i++) {
+    if (source.charCodeAt(i) === 10 /* \n */) {
+      line++
+      lastNewline = i
+    }
+  }
+  return { line, column: clamped - lastNewline }
+}
+
+/** A code frame: the offending line with a caret under the column, plus one
+ *  line of context on each side. */
+export function codeFrame(source: string, line: number, column: number): string {
+  const lines = source.split('\n')
+  const start = Math.max(1, line - 1)
+  const end = Math.min(lines.length, line + 1)
+  const gutterWidth = String(end).length
+  const out: string[] = []
+  for (let n = start; n <= end; n++) {
+    const gutter = String(n).padStart(gutterWidth)
+    const marker = n === line ? '>' : ' '
+    out.push(`${marker} ${gutter} | ${lines[n - 1] ?? ''}`)
+    if (n === line) {
+      out.push(`  ${' '.repeat(gutterWidth)} | ${' '.repeat(Math.max(0, column - 1))}^`)
+    }
+  }
+  return out.join('\n')
+}
+
+/** Build a `DiagnosticLocation` from a character offset in the original source. */
+export function locAt(source: string, offset: number, file?: string): DiagnosticLocation {
+  const { line, column } = offsetToLineCol(source, offset)
+  return { file, line, column, frame: codeFrame(source, line, column) }
+}

package/src/compiler/dts.ts

@@ -0,0 +1,87 @@
+import ts from 'typescript'
+import { splitStator } from './split.ts'
+
+/**
+ * Generate a `<name>.stator.d.ts` for a component, giving callers real prop
+ * types. TS resolves `import X from './x.stator'` to this specific `.d.ts` (which
+ * beats the `*.stator` ambient wildcard), so `<X prop={...}/>` is type-checked.
+ *
+ * The `.d.ts` carries the component's frontmatter type imports (so the props
+ * type's references resolve) plus the default-export signature derived from
+ * `Stator.props<P>()` (+ a loose `children` bag when the body uses `<children>`).
+ *
+ * Routes don't get a `.d.ts` — they export `GET`, not a callable render
+ * function — so `generateDts` returns null for `kind: 'route'`.
+ */
+export function generateDts(
+  source: string,
+  opts: { kind?: 'route' | 'component' } = {},
+): string | null {
+  if ((opts.kind ?? 'component') === 'route') return null
+
+  const { frontmatter, template } = splitStator(source)
+  const { hoisted, propsType } = extractFrontmatterTypes(frontmatter)
+  const propsT = componentPropsType(propsType, template)
+
+  const lines = ["import type { HtmlFragment } from '@statorjs/stator/template'"]
+  if (hoisted) lines.push(hoisted)
+  lines.push('')
+  lines.push(`declare const _default: (props: ${propsT}) => HtmlFragment`)
+  lines.push('export default _default')
+  return `${lines.join('\n')}\n`
+}
+
+/**
+ * The full props type for a component's public signature: the
+ * `Stator.props<P>()` type argument (verbatim source text — inline literal or
+ * a named reference), widened with a children bag when the body renders
+ * `<children>`. A component that declares no props accepts none
+ * (`Record<string, never>`). Shared by the `.d.ts` generator (tsc) and the
+ * language-server virtual emit (editor), so the two can't disagree.
+ */
+export function componentPropsType(propsType: string | undefined, template: string): string {
+  const usesChildren = /<children[\s/>]/.test(template)
+  if (propsType) return usesChildren ? `${propsType} & { children?: any }` : propsType
+  return usesChildren ? '{ children?: any }' : 'Record<string, never>'
+}
+
+/** Collect the import/type/interface declarations from frontmatter (for the
+ *  `.d.ts` to re-state) and the `Stator.props<P>()` type argument. */
+export function extractFrontmatterTypes(fm: string): {
+  hoisted: string
+  propsType?: string
+} {
+  if (!fm.trim()) return { hoisted: '' }
+  const sf = ts.createSourceFile('fm.ts', fm, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+  const hoisted: string[] = []
+  let propsType: string | undefined
+
+  for (const stmt of sf.statements) {
+    if (
+      ts.isImportDeclaration(stmt) ||
+      ts.isTypeAliasDeclaration(stmt) ||
+      ts.isInterfaceDeclaration(stmt)
+    ) {
+      hoisted.push(stmt.getText(sf))
+      continue
+    }
+    const visit = (n: ts.Node): void => {
+      if (
+        ts.isCallExpression(n) &&
+        ts.isPropertyAccessExpression(n.expression) &&
+        ts.isIdentifier(n.expression.expression) &&
+        n.expression.expression.text === 'Stator' &&
+        n.expression.name.text === 'props' &&
+        n.typeArguments &&
+        n.typeArguments.length > 0
+      ) {
+        propsType = n.typeArguments[0]!.getText(sf)
+        return
+      }
+      ts.forEachChild(n, visit)
+    }
+    visit(stmt)
+  }
+
+  return { hoisted: hoisted.join('\n'), propsType }
+}

package/src/compiler/hash.ts

@@ -0,0 +1,8 @@
+import { createHash } from 'node:crypto'
+
+/** Deterministic per-component scope hash. Derived from a stable identifier
+ *  (the file path when compiling a real file, else the source). 8 hex chars is
+ *  ample to avoid collisions across a project's component set. */
+export function scopeHash(input: string): string {
+  return createHash('sha256').update(input).digest('hex').slice(0, 8)
+}

package/src/compiler/index.ts

@@ -0,0 +1,48 @@
+/**
+ * The `.stator` compiler. A pure, bundler-agnostic source-to-source transform:
+ * a `.stator` file in, the `.ts` modules the existing runtime already consumes
+ * out. No Vite imports here — the Vite plugin (`@statorjs/stator/vite`) is a thin
+ * adapter over this surface.
+ *
+ * See spec: stator-compiler-and-vite-plugin-implementation-plan.
+ */
+
+export type { EmitClientInput } from './client-emit.ts'
+export { emitClientModule, rewriteMembers } from './client-emit.ts'
+export type {
+  ClientAnalysis,
+  ClientDirective,
+  ClientElement,
+  ScriptClass,
+} from './client-script.ts'
+export {
+  analyzeClient,
+  analyzeScriptClasses,
+  inferDeps,
+  isCustomElementTag,
+  kebabToPascal,
+  pascalToKebab,
+} from './client-script.ts'
+export type { CompileOptions, CompileResult } from './compile.ts'
+export { compile } from './compile.ts'
+export type { DiagnosticLocation } from './diagnostics.ts'
+export {
+  CompileError,
+  codeFrame,
+  locAt,
+  offsetToLineCol,
+} from './diagnostics.ts'
+export { generateDts } from './dts.ts'
+export { scopeHash } from './hash.ts'
+export type { LowerMeta, LowerOptions } from './lower.ts'
+export { lowerTemplate } from './lower.ts'
+export { componentImportSpecifier, declaredRegions } from './regions.ts'
+export type { ParsedStator, ScannedRegions, SourceRegion } from './split.ts'
+export { scanRegions, splitStator } from './split.ts'
+export { scopeCss } from './styles.ts'
+export type {
+  VirtualCodeResult,
+  VirtualFile,
+  VirtualMapping,
+} from './virtual-code.ts'
+export { toVirtualCode } from './virtual-code.ts'