@statorjs/stator 2.0.2 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "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 (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "2.0.2"
+    "@statorjs/stator": "2.1.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/compiler/client-emit.ts

@@ -1,6 +1,7 @@
 import ts from 'typescript'
 import { elementMarkerSelector } from '../wire/island-markers.ts'
 import type { ClientDirective, ClientElement } from './client-script.ts'
+import { CLIENT_AUTHOR_GLOBALS, CLIENT_LOWERING_TARGETS, importLine } from './emit-names.ts'
 
 /**
  * Phase 3b stage 5 — emit the client entry module for a client component: the
@@ -13,8 +14,10 @@ import type { ClientDirective, ClientElement } from './client-script.ts'
  * class as written; the subclass overrides `setup()`.
  */
 
-const PRIMITIVES =
-  "import { StatorElement, defineElement, use, machine, bind, bindSlot, effect, dispatch, attrValue, setAttr } from '@statorjs/stator/client'"
+const PRIMITIVES = importLine(
+  [...CLIENT_AUTHOR_GLOBALS, ...CLIENT_LOWERING_TARGETS],
+  '@statorjs/stator/client',
+)
 
 export interface EmitClientInput {
   /** The author's `<script>` source. */

package/src/compiler/compile.ts

@@ -8,6 +8,12 @@ import {
   pascalToKebab,
 } from './client-script.ts'
 import { CompileError, type DiagnosticLocation, locAt } from './diagnostics.ts'
+import {
+  ISLAND_SHELL_EXTRAS,
+  importLine,
+  TEMPLATE_AUTHOR_GLOBALS,
+  TEMPLATE_LOWERING_TARGETS,
+} from './emit-names.ts'
 import { scopeHash } from './hash.ts'
 import { type LowerMeta, lowerTemplate } from './lower.ts'
 import { splitStator } from './split.ts'
@@ -47,8 +53,19 @@ export interface CompileResult {
   clientTag?: string
 }
 
-const PRIMITIVES_IMPORT =
-  "import { html, read, each, itemBind, when, match, defer, on, classList, styleList, spreadAttrs } from '@statorjs/stator/template'"
+const PRIMITIVES_IMPORT = importLine(
+  [...TEMPLATE_AUTHOR_GLOBALS, ...TEMPLATE_LOWERING_TARGETS],
+  '@statorjs/stator/template',
+)
+
+const SHELL_PRIMITIVES_IMPORT = importLine(
+  [
+    ...TEMPLATE_AUTHOR_GLOBALS,
+    ...TEMPLATE_LOWERING_TARGETS.filter((n) => n !== 'itemBind'),
+    ...ISLAND_SHELL_EXTRAS,
+  ],
+  '@statorjs/stator/template',
+)
 
 export interface CompileOptions {
   /** Stable id for the component (file path). Used for the scope hash so the
@@ -81,24 +98,17 @@ export function compile(source: string, opts: CompileOptions = {}): CompileResul
   const script = scripts.join('\n')
   if (script.trim()) {
     if (analyzeScriptClasses(script).length > 0) {
-      // An island's shell renders from props — there is no frontmatter
-      // execution on this path, and silently discarding the fence produced
-      // either a dangling-identifier crash at render or dead code that
-      // looked alive. Surface it instead.
-      if (frontmatter.trim()) {
-        throw new CompileError(
-          `stator: an island file (a template with a StatorElement <script>) can't have ` +
-            `frontmatter — the fence would never run: the island's shell renders from props. ` +
-            `Move the server work into the route or component that renders this island and ` +
-            `pass the results as props.`,
-          locAt(source, 0, opts.id),
-        )
-      }
+      // The island's SERVER FENCE (2.1): runs per shell render, on the
+      // server only, with its bindings in template scope. The <script>
+      // never sees it, in either direction.
+      const fm = processFrontmatter(frontmatter, 'island', source, opts.id)
       return compileClient(template, script, {
         hash,
         scopeAttr,
         styles,
         file: opts.id,
+        fm,
+        source,
       })
     }
     throw new CompileError(
@@ -152,7 +162,16 @@ export function compile(source: string, opts: CompileOptions = {}): CompileResul
 function compileClient(
   template: string,
   script: string,
-  ctx: { hash: string; scopeAttr?: string; styles: string[]; file?: string },
+  ctx: {
+    hash: string
+    scopeAttr?: string
+    styles: string[]
+    file?: string
+    /** The island's processed server fence (2.1) — empty parts when absent. */
+    fm?: FrontmatterParts
+    /** Original source, for located collision diagnostics. */
+    source?: string
+  },
 ): CompileResult {
   const classes = analyzeScriptClasses(script)
   const root = extractClientRoot(template, ctx.file)
@@ -162,6 +181,22 @@ function compileClient(
   analyzeClient(script, tags, { file: ctx.file })
 
   const cls = classes.find((c) => pascalToKebab(c.name) === root.tag)
+
+  // A fence binding sharing a name with a `use()` field is ambiguous by
+  // construction (client wiring keys template identifiers on the use-field
+  // set) — a located error, not a precedence rule.
+  if (ctx.fm && cls) {
+    const fenceNames = fenceBindingNames(ctx.fm)
+    for (const field of cls.useFields.keys()) {
+      if (fenceNames.has(field)) {
+        throw new CompileError(
+          `stator: "${field}" is both a fence binding and a use() field — the template ` +
+            `couldn't tell the server value from the client machine. Rename one.`,
+          ctx.source ? locAt(ctx.source, 0, ctx.file) : undefined,
+        )
+      }
+    }
+  }
   if (!cls) {
     // analyzeClient validated the tag↔class match just above; reaching here is a bug.
     throw new CompileError(
@@ -199,9 +234,13 @@ function compileClient(
   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, defer, on, classList, styleList, spreadAttrs, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
+    SHELL_PRIMITIVES_IMPORT,
+    ...(ctx.fm?.hoisted ? [ctx.fm.hoisted] : []),
     '',
     `export default function (props = {}) {`,
+    // The fence body runs here — per shell render, server only, ahead of
+    // the template so its bindings are in scope for the interpolations.
+    ...(ctx.fm?.body ? [ctx.fm.body] : []),
     `  const __inner = ${innerExpr}`,
     `  const __attrs = clientShellAttrs(props, ${attrDecl}, ${JSON.stringify(root.rootAttrs)})`,
     `  return createHtmlFragment(\`<${root.tag}\${__attrs}${rootScope}>\` + __inner.html + \`</${root.tag}>\`)`,
@@ -324,7 +363,7 @@ const VALID_PRAGMAS = new Set(['live'])
  */
 function processFrontmatter(
   fm: string,
-  kind: 'route' | 'component',
+  kind: 'route' | 'component' | 'island',
   source: string,
   file?: string,
 ): FrontmatterParts {
@@ -355,6 +394,14 @@ function processFrontmatter(
     const repls: Array<[start: number, end: number, replacement: string]> = []
     const visit = (n: ts.Node): void => {
       if (ts.isCallExpression(n) && isStatorCall(n, 'props')) {
+        if (kind === 'island') {
+          throw new CompileError(
+            "stator: Stator.props() is not available in an island's fence — island props are " +
+              'declared by `static attrs` on the element class, and richer values arrive ' +
+              'through the hydrate pattern (the shell renders with the props of its use site).',
+            locInFm(n),
+          )
+        }
         if (kind === 'route') {
           throw new CompileError(
             'stator: Stator.props() is not available in a route page (a route has no parent props). ' +
@@ -387,6 +434,12 @@ function processFrontmatter(
         return
       }
       if (ts.isCallExpression(n) && isStatorCall(n, 'forwarded')) {
+        if (kind === 'island') {
+          throw new CompileError(
+            "stator: Stator.forwarded() is not available in an island's fence.",
+            locInFm(n),
+          )
+        }
         if (kind === 'route') {
           throw new CompileError(
             'stator: Stator.forwarded() is only available in a component — it reads a directive ' +
@@ -435,6 +488,41 @@ function processFrontmatter(
   }
 }
 
+/** Top-level names a fence declares — imports (default/named/namespace),
+ *  consts/lets, functions, classes — for the fence-vs-use()-field collision
+ *  check. Parsed from the processed parts (hoisted + body). */
+function fenceBindingNames(fm: FrontmatterParts): Set<string> {
+  const names = new Set<string>()
+  const sf = ts.createSourceFile(
+    'fence.ts',
+    `${fm.hoisted}\n${fm.body}`,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  )
+  const bind = (n: ts.BindingName): void => {
+    if (ts.isIdentifier(n)) names.add(n.text)
+    else for (const el of n.elements) if (ts.isBindingElement(el)) bind(el.name)
+  }
+  for (const stmt of sf.statements) {
+    if (ts.isImportDeclaration(stmt) && stmt.importClause) {
+      const c = stmt.importClause
+      if (c.name) names.add(c.name.text)
+      if (c.namedBindings) {
+        if (ts.isNamespaceImport(c.namedBindings)) names.add(c.namedBindings.name.text)
+        else for (const s of c.namedBindings.elements) names.add(s.name.text)
+      }
+    } else if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) bind(d.name)
+    } else if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      names.add(stmt.name.text)
+    } else if (ts.isClassDeclaration(stmt) && stmt.name) {
+      names.add(stmt.name.text)
+    }
+  }
+  return names
+}
+
 function emitComponent(fm: FrontmatterParts, htmlExpr: string, meta: LowerMeta): string {
   let param = ''
   if (fm.propsType && meta.usesChildren) param = `props: ${fm.propsType} & { children?: any }`
@@ -469,7 +557,7 @@ function emitRoute(fm: FrontmatterParts, htmlExpr: string, _meta: LowerMeta): st
 /** Parse `// @stator <flag>` comment pragmas from the frontmatter text. */
 function parsePragmas(
   fm: string,
-  kind: 'route' | 'component',
+  kind: 'route' | 'component' | 'island',
   source: string,
   file?: string,
 ): Set<string> {
@@ -494,7 +582,11 @@ function parsePragmas(
   return out
 }
 
-function requireRoute(what: string, kind: 'route' | 'component', loc: DiagnosticLocation): void {
+function requireRoute(
+  what: string,
+  kind: 'route' | 'component' | 'island',
+  loc: DiagnosticLocation,
+): void {
   if (kind !== 'route') {
     throw new CompileError(
       `stator: ${what} is only available in a route page, not a component. ` +

package/src/compiler/emit-names.ts

@@ -0,0 +1,48 @@
+/** The names the compiler auto-injects into emitted modules — single source
+ *  of truth for the emitters (compile.ts, client-emit.ts) AND the language
+ *  server (virtual-code.ts), which must inject the same globals in-editor: a
+ *  name injected in one place but not the other hides a missing-import bug,
+ *  and a name injected that authors also legitimately import collides with
+ *  their import (`raw` is NOT a global — authors import it — which is why it
+ *  appears in no list here).
+ *
+ *  Author globals are names template/script authors may write directly;
+ *  lowering targets are names only the compiler's output references. */
+
+/** Template names authors write: control flow + display + directive values. */
+export const TEMPLATE_AUTHOR_GLOBALS = [
+  'read',
+  'each',
+  'when',
+  'match',
+  'defer',
+  'on',
+  'classList',
+  'styleList',
+] as const
+
+/** Template names only lowered code references. `itemBind` needs server
+ *  render state, so it is a SERVER-module target only — client-island shells
+ *  never emit it (see lower.ts, keyed-row lowering). */
+export const TEMPLATE_LOWERING_TARGETS = ['html', 'itemBind', 'spreadAttrs'] as const
+
+/** Extra lowering targets for a client island's server SHELL module. */
+export const ISLAND_SHELL_EXTRAS = ['createHtmlFragment', 'clientShellAttrs'] as const
+
+/** Client-module names island authors write in a `<script>`. */
+export const CLIENT_AUTHOR_GLOBALS = [
+  'StatorElement',
+  'use',
+  'machine',
+  'defineElement',
+  'bind',
+  'effect',
+  'dispatch',
+] as const
+
+/** Client-module names only lowered code references. */
+export const CLIENT_LOWERING_TARGETS = ['bindSlot', 'attrValue', 'setAttr'] as const
+
+export function importLine(names: readonly string[], from: string): string {
+  return `import { ${names.join(', ')} } from '${from}'`
+}

package/src/compiler/virtual-code.ts

@@ -21,6 +21,7 @@
 import ts from 'typescript'
 import { analyzeScriptClasses } from './client-script.ts'
 import { statorPropsType } from './dts.ts'
+import { CLIENT_AUTHOR_GLOBALS, TEMPLATE_AUTHOR_GLOBALS } from './emit-names.ts'
 import { type ScannedRegions, scanRegions } from './split.ts'
 
 /** A contiguous run mapping generated code back to source, 1:1 over its length. */
@@ -44,21 +45,11 @@ export interface VirtualCodeResult {
   styles: VirtualFile[]
 }
 
-// Must mirror the RUNTIME's auto-injected globals exactly (compile.ts
-// PRIMITIVES_IMPORT / client-emit.ts): a name injected here but not at
-// runtime hides a missing-import bug; a name in both collides with the
-// author's legitimate import (`raw` is NOT a runtime global — authors
-// import it — which is why it must not be in this list).
-const TEMPLATE_GLOBALS = ['read', 'each', 'when', 'match', 'defer', 'on', 'classList', 'styleList']
-const CLIENT_GLOBALS = [
-  'StatorElement',
-  'use',
-  'machine',
-  'defineElement',
-  'bind',
-  'effect',
-  'dispatch',
-]
+// The editor injects the AUTHOR-visible subsets only — lowering targets are
+// names authors never write, so injecting them here would shadow nothing and
+// pollute completions. Shared with the emitters via emit-names.ts.
+const TEMPLATE_GLOBALS = TEMPLATE_AUTHOR_GLOBALS
+const CLIENT_GLOBALS = CLIENT_AUTHOR_GLOBALS
 
 /** Local names the user's code already binds from `modulePath` imports —
  *  the runtime strips such habit-imports; the virtual emit (which must keep
@@ -79,7 +70,7 @@ function userImportedLocals(code: string, modulePath: string): Set<string> {
   return locals
 }
 
-function injectImports(globals: string[], modulePath: string, userCode: string): string {
+function injectImports(globals: readonly string[], modulePath: string, userCode: string): string {
   const bound = userImportedLocals(userCode, modulePath)
   const missing = globals.filter((g) => !bound.has(g))
   return missing.length > 0 ? `import { ${missing.join(', ')} } from '${modulePath}';\n` : ''
@@ -367,6 +358,28 @@ function buildClientTsx(regions: ScannedRegions): VirtualFile {
     AMBIENT_TYPE_IMPORTS +
     STATOR_AMBIENT
 
+  // The island's SERVER FENCE (2.1): typed here so the editor checks it, but
+  // wrapped so its bindings don't leak into the <script>'s scope (at runtime
+  // the two never meet). Hoisted imports that also appear verbatim in the
+  // script are skipped — same module, one binding.
+  const fm = regions.frontmatter?.content ?? ''
+  if (fm.trim()) {
+    const fmOffset = regions.frontmatter?.contentOffset ?? 0
+    const { hoisted, body } = splitFrontmatter(fm, fmOffset)
+    for (const seg of hoisted) {
+      if (userScript.includes(seg.text.trim())) continue
+      push(mappings, seg.sourceOffset, code.length, seg.text.length)
+      code += `${seg.text}\n`
+    }
+    code += 'function __statorFence(props: Record<string, unknown>) {\n'
+    for (const seg of body) {
+      code += '  '
+      push(mappings, seg.sourceOffset, code.length, seg.text.length)
+      code += `${seg.text}\n`
+    }
+    code += '}\nvoid __statorFence\n'
+  }
+
   for (const script of regions.scripts) {
     push(mappings, script.contentOffset, code.length, script.content.length)
     code += `${script.content}\n`