fse-ssr 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# fse-ssr
+
+Compile-to-Tera SSR bindings for [full_stack_engine](https://github.com/StevenUster/full_stack_engine)'s
+Astro starter. Author `.astro` templates in native TypeScript against
+`ssr<T>()` placeholders; a build-time Astro/Vite integration compiles the
+expressions that touch them into the equivalent Tera syntax, so the built
+HTML is exactly what the Rust backend's Tera renderer expects — no template
+syntax ever appears in frontend source.
+
+This package is not generically reusable outside apps built on
+full_stack_engine: it assumes the framework's `render_tpl` context shape and
+the `<script type="application/json" id="__fse-props__">` placeholder emitted
+by its `Layout.astro`. See the starter's [README](../starter/README.md#server-rendered-data-in-templates-fse-ssr)
+for usage and the supported expression grammar.
+
+## Entry points
+
+- `fse-ssr` — the Astro integration (`astro.config.mjs`).
+- `fse-ssr/ssr` — `ssr<T>()` and its types, for use inside `.astro` files.
+- `fse-ssr/client` — `pageProps<T>()`, for browser/island code.
+
+## Development
+
+```bash
+bun install
+bun run build   # tsc, one-shot
+bun run dev     # tsc --watch
+```
+
+This package is standalone — it isn't linked into the starter via a
+workspace. To try local changes in the starter before publishing a new
+version, `bun publish` a prerelease (or use `bun pm pack` + install the
+tarball) and bump the starter's `fse-ssr` dependency to it.
+
+## Publishing
+
+```bash
+bun run build
+bun publish
+```

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+/**
+ * fse-ssr browser runtime.
+ *
+ * The Rust server serializes each page's full render context into
+ * `<script type="application/json" id="__fse-props__">` (see the framework's
+ * `render_template`). Client code — islands, inline scripts — reads it here,
+ * so no extra request is needed for the data the page was rendered with.
+ */
+import type { GlobalSsrContext } from "./types";
+/** Typed page props, parsed once from the embedded JSON blob. */
+export declare function pageProps<T = Record<string, never>>(): T & GlobalSsrContext;

package/dist/client.js

@@ -0,0 +1,9 @@
+let cached;
+/** Typed page props, parsed once from the embedded JSON blob. */
+export function pageProps() {
+    if (cached === undefined) {
+        const el = document.getElementById("__fse-props__");
+        cached = el?.textContent ? JSON.parse(el.textContent) : {};
+    }
+    return cached;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,24 @@
+import type { GlobalSsrContext, Ssr } from "./types";
+export type { GlobalSsrContext, Ssr, SsrList, SsrValue, Translations } from "./types";
+/**
+ * Typed SSR placeholders for the page's render context. Interpolate them in
+ * the template like ordinary values; the built HTML contains the matching
+ * Tera expressions and the server substitutes the real data per request.
+ */
+export declare function ssr<T = Record<string, never>>(): Ssr<T & GlobalSsrContext>;
+/** Renders one interpolated template chunk. */
+export declare function __fseChunk(v: unknown): unknown;
+/** Drop-in replacement for Astro's `addAttribute` that understands SSR markers. */
+export declare function __fseAddAttribute(value: unknown, key: string, shouldEscape?: boolean, tagName?: string): unknown;
+/** `a === b`, `a < b`, … — compiles to a Tera comparison when SSR values are involved. */
+export declare function __fseBin(op: string, l: unknown, r: unknown): unknown;
+/** `a && b` / `a || b` with a lazily evaluated right side. */
+export declare function __fseLogic(op: "&&" | "||", l: unknown, rThunk: () => unknown): unknown;
+/** `t ? a : b` — compiles to `{% if %}…{% else %}…{% endif %}` for SSR tests. */
+export declare function __fseCond(test: unknown, consThunk: () => unknown, altThunk: () => unknown): unknown;
+/** `!x` — compiles to `not (…)` for SSR values. */
+export declare function __fseNot(v: unknown): unknown;
+/** `a ?? b` — compiles to Tera's `default` filter for SSR values. */
+export declare function __fseNullish(l: unknown, rThunk: () => unknown): unknown;
+/** Guards build-time `if` statements against accidental SSR-value tests. */
+export declare function __fseGuardIf(test: unknown): unknown;

package/dist/runtime.js

@@ -0,0 +1,377 @@
+/**
+ * fse-ssr build-time runtime.
+ *
+ * `ssr<T>()` returns proxies that stand in for server data while Astro
+ * renders the static HTML. Interpolating a proxy emits the matching Tera
+ * expression (`{{ path }}`); `.map()` emits a `{% for %}` loop. Comparisons
+ * and conditionals can't be intercepted by proxies (JS operators aren't
+ * overloadable), so the fse-ssr Astro integration rewrites the compiled
+ * template's expressions to the `__fse*` helpers below, which fall back to
+ * plain JavaScript semantics whenever no SSR placeholder is involved.
+ *
+ * This module runs only while Astro renders (build / dev server) — it never
+ * ships to the browser. Island code reads values from the package's `/client`
+ * entry.
+ */
+import { addAttribute as astroAddAttribute, markHTMLString, } from "astro/runtime/server/index.js";
+const KIND = Symbol("fse-ssr.kind");
+const EXPR = Symbol("fse-ssr.expr");
+class FseSsrError extends Error {
+    constructor(message) {
+        super(`[fse-ssr] ${message}`);
+        this.name = "FseSsrError";
+    }
+}
+function kindOf(v) {
+    if (v === null || (typeof v !== "object" && typeof v !== "function")) {
+        return undefined;
+    }
+    return v[KIND];
+}
+const isProxy = (v) => kindOf(v) === "value";
+const isMarker = (v) => kindOf(v) !== undefined;
+function exprOfProxy(v) {
+    return v[EXPR];
+}
+const raw = (s) => markHTMLString(s);
+// ─── Tera expression helpers ────────────────────────────────────────────────
+/** Serializes a build-time literal for use inside a Tera expression. */
+function teraLiteral(v) {
+    if (isProxy(v))
+        return exprOfProxy(v);
+    if (typeof v === "string") {
+        if (!/^[^'\\\n\r]*$/.test(v)) {
+            throw new FseSsrError(`String literal ${JSON.stringify(v)} can't be used in an SSR expression (quotes/backslashes are not supported).`);
+        }
+        return `'${v}'`;
+    }
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    throw new FseSsrError(`Value of type ${typeof v} can't be used in an SSR expression.`);
+}
+/**
+ * Truthiness test for a bare value: guarded with `default(value=false)` so a
+ * key that is absent from the request context reads as false instead of
+ * failing the whole render.
+ */
+function bareCond(expr) {
+    return expr.includes("|") ? expr : `${expr} | default(value=false)`;
+}
+/** Condition tree for anything usable as a boolean. */
+function condNodeOf(v) {
+    switch (kindOf(v)) {
+        case "value":
+            return { k: "truthy", expr: bareCond(exprOfProxy(v)) };
+        case "cond":
+            return v.node;
+        case "logic": {
+            const m = v;
+            return { k: m.op, parts: [condNodeOf(m.left), condNodeOf(m.value)] };
+        }
+        default:
+            throw new FseSsrError("This value can't be used as a server-side condition. Use an SSR value or a comparison of SSR values.");
+    }
+}
+const INVERTED_OP = {
+    "==": "!=",
+    "!=": "==",
+    "<": ">=",
+    ">=": "<",
+    ">": "<=",
+    "<=": ">",
+};
+function negate(n) {
+    switch (n.k) {
+        case "truthy":
+            return { k: "not", part: n };
+        case "not":
+            return n.part;
+        case "cmp":
+            return { ...n, op: INVERTED_OP[n.op] };
+        case "and":
+            return { k: "or", parts: n.parts.map(negate) };
+        case "or":
+            return { k: "and", parts: n.parts.map(negate) };
+    }
+}
+function flatten(k, parts) {
+    return parts.flatMap((p) => (p.k === k ? flatten(k, p.parts) : [p]));
+}
+/**
+ * Emits a Tera condition. Tera's precedence matches JS (`and` binds tighter
+ * than `or`), but there are no parentheses to override it, so an `or` nested
+ * inside an `and` cannot be expressed and fails the build.
+ */
+function renderCond(n) {
+    switch (n.k) {
+        case "truthy":
+            return n.expr;
+        case "cmp":
+            return `${n.l} ${n.op} ${n.r}`;
+        case "not":
+            return n.part.k === "truthy" ? `not ${n.part.expr}` : renderCond(negate(n.part));
+        case "or":
+            return flatten("or", n.parts).map(renderCond).join(" or ");
+        case "and": {
+            const parts = flatten("and", n.parts);
+            if (parts.some((p) => p.k === "or")) {
+                throw new FseSsrError("`(a || b) && c` can't be expressed in Tera (it has no grouping parentheses). " +
+                    "Distribute the condition, e.g. `(a && c) || (b && c)`, or compute a flag in the service.");
+            }
+            return parts.map(renderCond).join(" and ");
+        }
+    }
+}
+/** Tera condition string for anything usable as a boolean. */
+function condExprOf(v) {
+    return renderCond(condNodeOf(v));
+}
+// ─── Value proxies ──────────────────────────────────────────────────────────
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// A proxy coerced to a string and used as a computed key, e.g.
+// `t.roles[row.role]` where `row.role` is itself an SSR value.
+const COERCED_KEY = /^\{\{ (.+) \}\}$/;
+let loopDepth = 0;
+function valueProxy(expr) {
+    return new Proxy({}, {
+        get(_target, key) {
+            if (key === KIND)
+                return "value";
+            if (key === EXPR)
+                return expr;
+            if (key === Symbol.toPrimitive || key === "toString" || key === "valueOf") {
+                return () => `{{ ${expr} }}`;
+            }
+            // Safety net: if a proxy reaches Astro's renderer unwrapped, Astro
+            // treats anything tagged HTMLString as raw markup and stringifies it,
+            // which yields the correct `{{ path }}` output.
+            if (key === Symbol.toStringTag)
+                return "HTMLString";
+            if (typeof key === "symbol")
+                return undefined;
+            // Astro probes children for these; answering with a child proxy
+            // would make it await / stream us.
+            if (key === "then" || key === "getReader" || key === "toJSON") {
+                return undefined;
+            }
+            if (key === "map") {
+                return (cb) => loopBlock(expr, cb);
+            }
+            if (key === "length")
+                return valueProxy(`${expr} | length`);
+            if (expr.includes("|")) {
+                throw new FseSsrError(`Can't access ".${String(key)}" on the filtered expression "${expr}".`);
+            }
+            const coerced = COERCED_KEY.exec(key);
+            if (coerced)
+                return valueProxy(`${expr}[${coerced[1]}]`);
+            if (IDENT.test(key) || /^\d+$/.test(key)) {
+                return valueProxy(expr === "" ? key : `${expr}.${key}`);
+            }
+            throw new FseSsrError(`"${key}" is not a valid SSR property name (on "${expr}").`);
+        },
+        has(_target, key) {
+            return typeof key !== "symbol" && key !== "then" && key !== "getReader";
+        },
+    });
+}
+function block(parts) {
+    return { [KIND]: "block", parts };
+}
+function loopBlock(listExpr, cb) {
+    const name = `it${loopDepth}`;
+    loopDepth += 1;
+    try {
+        const body = cb(valueProxy(name), valueProxy("loop.index0"), valueProxy(listExpr));
+        return block([raw(`{% for ${name} in ${listExpr} %}`), body, raw("{% endfor %}")]);
+    }
+    finally {
+        loopDepth -= 1;
+    }
+}
+/**
+ * Typed SSR placeholders for the page's render context. Interpolate them in
+ * the template like ordinary values; the built HTML contains the matching
+ * Tera expressions and the server substitutes the real data per request.
+ */
+export function ssr() {
+    return valueProxy("");
+}
+// ─── Helpers injected by the build-time transform ───────────────────────────
+// Each helper preserves plain JavaScript semantics when no SSR placeholder is
+// involved, so rewriting every expression in a compiled .astro module is safe.
+/** Renders one interpolated template chunk. */
+export function __fseChunk(v) {
+    switch (kindOf(v)) {
+        case undefined:
+            return v;
+        case "value":
+            return raw(`{{ ${exprOfProxy(v)} }}`);
+        case "block":
+            return v.parts.map(__fseChunk);
+        case "logic": {
+            const m = v;
+            if (m.op === "and") {
+                return __fseChunk(block([raw(`{% if ${condExprOf(m.left)} %}`), m.value, raw("{% endif %}")]));
+            }
+            // `{a || fallback}`: render `a` when truthy, the fallback otherwise.
+            if (!isProxy(m.left)) {
+                throw new FseSsrError('"cond || fallback" needs an SSR value on the left to know what to render when it is truthy.');
+            }
+            return __fseChunk(block([
+                raw(`{% if ${condExprOf(m.left)} %}{{ ${exprOfProxy(m.left)} }}{% else %}`),
+                m.value,
+                raw("{% endif %}"),
+            ]));
+        }
+        case "ternary": {
+            const m = v;
+            return __fseChunk(block([
+                raw(`{% if ${renderCond(m.cond)} %}`),
+                m.cons,
+                raw("{% else %}"),
+                m.alt,
+                raw("{% endif %}"),
+            ]));
+        }
+        default:
+            throw new FseSsrError("A bare comparison can't be rendered as content. Use `{cond && <...>}` or `{cond ? a : b}`.");
+    }
+}
+// Keep in sync with Astro's boolean-attribute list (runtime/server/render/util.js).
+const BOOLEAN_ATTRS = /^(?:allowfullscreen|async|autofocus|autoplay|checked|controls|default|defer|disabled|disablepictureinpicture|disableremoteplayback|formnovalidate|hidden|inert|loop|muted|nomodule|novalidate|open|playsinline|readonly|required|reversed|scoped|seamless|selected|itemscope)$/i;
+function attrText(v) {
+    if (isProxy(v))
+        return `{{ ${exprOfProxy(v)} }}`;
+    if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+        return String(v).replace(/&/g, "&#38;").replace(/"/g, "&#34;");
+    }
+    throw new FseSsrError(`Value of type ${typeof v} can't be rendered inside an SSR attribute.`);
+}
+/** Drop-in replacement for Astro's `addAttribute` that understands SSR markers. */
+export function __fseAddAttribute(value, key, shouldEscape, tagName) {
+    const kind = kindOf(value);
+    if (kind === undefined) {
+        if (key === "class:list" && Array.isArray(value)) {
+            value = value.map((entry) => isProxy(entry) ? `{{ ${exprOfProxy(entry)} }}` : entry);
+        }
+        return astroAddAttribute(value, key, shouldEscape, tagName);
+    }
+    if (BOOLEAN_ATTRS.test(key)) {
+        return raw(`{% if ${condExprOf(value)} %} ${key}{% endif %}`);
+    }
+    if (kind === "value") {
+        return raw(` ${key}="{{ ${exprOfProxy(value)} }}"`);
+    }
+    if (kind === "ternary") {
+        const m = value;
+        return raw(` ${key}="{% if ${renderCond(m.cond)} %}${attrText(m.cons)}{% else %}${attrText(m.alt)}{% endif %}"`);
+    }
+    throw new FseSsrError(`This SSR expression can't be used for the "${key}" attribute.`);
+}
+/** `a === b`, `a < b`, … — compiles to a Tera comparison when SSR values are involved. */
+export function __fseBin(op, l, r) {
+    if ((isMarker(l) || isMarker(r)) &&
+        l !== undefined &&
+        l !== null &&
+        r !== undefined &&
+        r !== null) {
+        const tera = {
+            "===": "==",
+            "==": "==",
+            "!==": "!=",
+            "!=": "!=",
+            "<": "<",
+            "<=": "<=",
+            ">": ">",
+            ">=": ">=",
+        };
+        const teraOp = tera[op];
+        if (!teraOp) {
+            throw new FseSsrError(`Operator "${op}" is not supported on SSR values.`);
+        }
+        const marker = {
+            [KIND]: "cond",
+            node: { k: "cmp", op: teraOp, l: teraLiteral(l), r: teraLiteral(r) },
+        };
+        return marker;
+    }
+    /* eslint-disable eqeqeq */
+    switch (op) {
+        case "===":
+            return l === r;
+        case "!==":
+            return l !== r;
+        case "==":
+            return l == r;
+        case "!=":
+            return l != r;
+        case "<":
+            return l < r;
+        case "<=":
+            return l <= r;
+        case ">":
+            return l > r;
+        case ">=":
+            return l >= r;
+        default:
+            throw new FseSsrError(`Unknown operator "${op}".`);
+    }
+    /* eslint-enable eqeqeq */
+}
+/** `a && b` / `a || b` with a lazily evaluated right side. */
+export function __fseLogic(op, l, rThunk) {
+    if (isMarker(l)) {
+        const marker = {
+            [KIND]: "logic",
+            op: op === "&&" ? "and" : "or",
+            left: l,
+            value: rThunk(),
+        };
+        return marker;
+    }
+    if (op === "&&")
+        return l ? rThunk() : l;
+    return l ? l : rThunk();
+}
+/** `t ? a : b` — compiles to `{% if %}…{% else %}…{% endif %}` for SSR tests. */
+export function __fseCond(test, consThunk, altThunk) {
+    if (isMarker(test)) {
+        const marker = {
+            [KIND]: "ternary",
+            cond: condNodeOf(test),
+            cons: consThunk(),
+            alt: altThunk(),
+        };
+        return marker;
+    }
+    return test ? consThunk() : altThunk();
+}
+/** `!x` — compiles to `not (…)` for SSR values. */
+export function __fseNot(v) {
+    if (isMarker(v)) {
+        const marker = { [KIND]: "cond", node: negate(condNodeOf(v)) };
+        return marker;
+    }
+    return !v;
+}
+/** `a ?? b` — compiles to Tera's `default` filter for SSR values. */
+export function __fseNullish(l, rThunk) {
+    if (isProxy(l)) {
+        return valueProxy(`${exprOfProxy(l)} | default(value=${teraLiteral(rThunk())})`);
+    }
+    if (isMarker(l)) {
+        throw new FseSsrError('"??" is only supported directly on SSR values.');
+    }
+    return l ?? rThunk();
+}
+/** Guards build-time `if` statements against accidental SSR-value tests. */
+export function __fseGuardIf(test) {
+    if (isMarker(test)) {
+        throw new FseSsrError("SSR values can't drive build-time `if` statements in frontmatter. " +
+            "Move the condition into the template: {cond && <...>} or {cond ? a : b}.");
+    }
+    return test;
+}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Public types for fse-ssr.
+ *
+ * `ssr<T>()` hands the template a tree of typed placeholders. To the type
+ * checker they behave like the real values (an `SsrValue<string>` is
+ * assignable wherever a `string` is expected, can be compared with `===`,
+ * used in template literals, …). At build time each placeholder compiles to
+ * the matching Tera expression, so the server fills in the real value on
+ * every request.
+ */
+declare const SSR_BRAND: unique symbol;
+/**
+ * The app's `t.*` shape. Intentionally empty here — the fse-ssr Astro
+ * integration generates a `declare module "…/ssr" { interface Translations
+ * {...} }` augmentation from the app's own locale JSON (see
+ * `.astro/fse-ssr-translations.d.ts` in a consuming project), so `t.*`
+ * accesses are typed per app without this package knowing any app's shape.
+ */
+export interface Translations {
+}
+/** A server-rendered scalar: types like `T`, renders as `{{ path }}`. */
+export type SsrValue<T> = T & {
+    readonly [SSR_BRAND]?: true;
+};
+/**
+ * A server-rendered list: `.map()` compiles to a Tera `{% for %}` loop whose
+ * callback runs exactly once at build time with a placeholder item.
+ */
+export interface SsrList<E> {
+    map<R>(cb: (item: Ssr<E>, index: SsrValue<number>) => R): R;
+    /** Compiles to `path | length`. */
+    readonly length: SsrValue<number>;
+}
+/** Maps a plain props interface to its SSR-placeholder counterpart. */
+export type Ssr<T> = 0 extends 1 & T ? T : [T] extends [(infer E)[]] ? SsrList<E> : [T] extends [string | number | boolean | null | undefined] ? SsrValue<T> : T extends object ? {
+    [K in keyof T]: Ssr<T[K]>;
+} : SsrValue<T>;
+/**
+ * Context every page receives automatically (see the app's
+ * `global_context_injector` and the framework's `inject_locale_context`).
+ */
+export interface GlobalSsrContext {
+    t: Translations;
+    lang: string;
+    /** Every locale keyed by language code, for client-side use. */
+    i18n: Record<string, unknown>;
+    /** JWT claims when a valid token cookie is present. */
+    user?: {
+        sub: string;
+        role: string;
+        [k: string]: unknown;
+    };
+    can_read_users?: boolean;
+}
+export {};

package/dist/types.js

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

package/integration.mjs

@@ -0,0 +1,257 @@
+/**
+ * fse-ssr Astro integration.
+ *
+ * Astro compiles each .astro file to a JS module whose template is a tagged
+ * template literal — conditionals, comparisons and attribute values appear in
+ * it as plain JS expressions. This integration rewrites those expressions to
+ * the `__fse*` helpers exported from this package's `/ssr` entry, which keep
+ * normal JavaScript semantics unless an SSR placeholder is involved, in which
+ * case they emit Tera syntax into the built HTML.
+ *
+ * It also generates a `Translations` declaration-merge file from the app's
+ * locale JSON so `t.*` accesses are type-checked per app.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import _generate from "@babel/generator";
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+import * as t from "@babel/types";
+
+const traverse = _traverse.default ?? _traverse;
+const generate = _generate.default ?? _generate;
+
+// Read once so the injected helper import always matches this package's
+// actual published name, even if it's renamed later.
+const PKG_NAME = JSON.parse(
+  readFileSync(fileURLToPath(new URL("./package.json", import.meta.url)), "utf8"),
+).name;
+const SSR_SPECIFIER = `${PKG_NAME}/ssr`;
+
+const HELPERS = [
+  "__fseChunk",
+  "__fseAddAttribute",
+  "__fseBin",
+  "__fseLogic",
+  "__fseCond",
+  "__fseNot",
+  "__fseNullish",
+  "__fseGuardIf",
+];
+
+const BIN_OPS = new Set(["===", "!==", "==", "!=", "<", "<=", ">", ">="]);
+
+/** True if the expression awaits/yields at its own function level (thunking it would be invalid). */
+function containsAwaitOrYield(path) {
+  let found = false;
+  path.traverse({
+    AwaitExpression() {
+      found = true;
+    },
+    YieldExpression() {
+      found = true;
+    },
+    Function(p) {
+      p.skip();
+    },
+  });
+  return found;
+}
+
+export function transformAstroModule(code) {
+  if (!code.includes("astro/compiler-runtime")) return null;
+
+  const ast = parse(code, {
+    sourceType: "module",
+    plugins: ["typescript", "jsx"],
+  });
+
+  let renderLocal = null;
+  let addAttributeLocal = null;
+  for (const node of ast.program.body) {
+    if (node.type === "ImportDeclaration" && node.source.value === "astro/compiler-runtime") {
+      for (const spec of node.specifiers) {
+        if (spec.type === "ImportSpecifier" && spec.imported.type === "Identifier") {
+          if (spec.imported.name === "render") renderLocal = spec.local.name;
+          if (spec.imported.name === "addAttribute") addAttributeLocal = spec.local.name;
+        }
+      }
+    }
+  }
+  if (!renderLocal) return null;
+
+  let used = false;
+  const injected = new WeakSet();
+  const helperCall = (name, args) => {
+    used = true;
+    const node = t.callExpression(t.identifier(name), args);
+    injected.add(node);
+    return node;
+  };
+  const thunk = (expr) => t.arrowFunctionExpression([], expr);
+
+  traverse(ast, {
+    // Wrap every `${…}` slot of the render template so proxies and markers
+    // become raw Tera output instead of reaching Astro's renderer directly.
+    TaggedTemplateExpression(path) {
+      const tag = path.node.tag;
+      if (tag.type !== "Identifier" || tag.name !== renderLocal) return;
+      path.node.quasi.expressions = path.node.quasi.expressions.map((expr) =>
+        injected.has(expr) ? expr : helperCall("__fseChunk", [expr]),
+      );
+    },
+    CallExpression(path) {
+      const callee = path.node.callee;
+      if (
+        addAttributeLocal &&
+        callee.type === "Identifier" &&
+        callee.name === addAttributeLocal &&
+        !injected.has(path.node)
+      ) {
+        path.node.callee = t.identifier("__fseAddAttribute");
+        injected.add(path.node);
+        used = true;
+      }
+    },
+    BinaryExpression(path) {
+      if (!BIN_OPS.has(path.node.operator)) return;
+      if (path.node.left.type === "PrivateName") return;
+      path.replaceWith(
+        helperCall("__fseBin", [
+          t.stringLiteral(path.node.operator),
+          path.node.left,
+          path.node.right,
+        ]),
+      );
+    },
+    LogicalExpression(path) {
+      if (containsAwaitOrYield(path.get("right"))) return;
+      const { operator, left, right } = path.node;
+      if (operator === "&&" || operator === "||") {
+        path.replaceWith(
+          helperCall("__fseLogic", [t.stringLiteral(operator), left, thunk(right)]),
+        );
+      } else if (operator === "??") {
+        path.replaceWith(helperCall("__fseNullish", [left, thunk(right)]));
+      }
+    },
+    ConditionalExpression(path) {
+      if (
+        containsAwaitOrYield(path.get("consequent")) ||
+        containsAwaitOrYield(path.get("alternate"))
+      ) {
+        return;
+      }
+      path.replaceWith(
+        helperCall("__fseCond", [
+          path.node.test,
+          thunk(path.node.consequent),
+          thunk(path.node.alternate),
+        ]),
+      );
+    },
+    UnaryExpression(path) {
+      if (path.node.operator !== "!") return;
+      if (injected.has(path.node)) return;
+      path.replaceWith(helperCall("__fseNot", [path.node.argument]));
+    },
+    // SSR values are only meaningful inside the template; a build-time `if`
+    // testing one would silently take the truthy branch, so fail loudly.
+    IfStatement(path) {
+      if (injected.has(path.node.test)) return;
+      path.node.test = helperCall("__fseGuardIf", [path.node.test]);
+    },
+  });
+
+  if (!used) return null;
+
+  ast.program.body.unshift(
+    t.importDeclaration(
+      HELPERS.map((h) => t.importSpecifier(t.identifier(h), t.identifier(h))),
+      t.stringLiteral(SSR_SPECIFIER),
+    ),
+  );
+
+  return generate(ast, { retainLines: false }, code);
+}
+
+function vitePlugin() {
+  return {
+    name: PKG_NAME,
+    enforce: "post",
+    transform(code, id) {
+      // The bare .astro id is the compiled component; variants with a query
+      // (?astro&type=script/style) are extracted assets and must stay untouched.
+      if (!id.endsWith(".astro")) return null;
+      const result = transformAstroModule(code);
+      return result ? { code: result.code, map: result.map ?? null } : null;
+    },
+  };
+}
+
+function tsType(value) {
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const fields = Object.entries(value)
+      .map(([k, v]) => `${JSON.stringify(k)}: ${tsType(v)};`)
+      .join(" ");
+    return `{ ${fields} }`;
+  }
+  return "unknown";
+}
+
+// Generated into the *consuming* project's `.astro/` (Astro's own convention
+// for build-generated type files — gitignored, regenerated on every run),
+// never into this package, since the shape is app-specific.
+function generateTranslationTypes(rootUrl, localesPath, defaultLocale, logger) {
+  const localeFile = fileURLToPath(new URL(`${localesPath}/${defaultLocale}.json`, rootUrl));
+  const outFile = fileURLToPath(new URL("./.astro/fse-ssr-translations.d.ts", rootUrl));
+  let locale;
+  try {
+    locale = JSON.parse(readFileSync(localeFile, "utf8"));
+  } catch (err) {
+    logger.warn(`Could not read ${localeFile}: ${err.message} — t.* will be untyped.`);
+    locale = null;
+  }
+  const body = locale ? tsType(locale) : "Record<string, unknown>";
+  // Declaration merging: augments the `Translations` interface this package
+  // exports from its `/ssr` entry, instead of exporting an app-specific type
+  // from a generically-published package.
+  const content =
+    `// Generated by ${PKG_NAME} from ${localesPath}/${defaultLocale}.json — do not edit.\n` +
+    `import "${SSR_SPECIFIER}";\n\n` +
+    `declare module "${SSR_SPECIFIER}" {\n` +
+    `  interface Translations ${body}\n` +
+    `}\n`;
+  try {
+    if (readFileSync(outFile, "utf8") === content) return;
+  } catch {
+    // First run: the file (and possibly `.astro/`) doesn't exist yet.
+  }
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, content);
+}
+
+/**
+ * @param {{ locales?: string, defaultLocale?: string }} [options]
+ *   `locales`: path to the locale directory, relative to the Astro project
+ *   root (default "../../locales" — the starter layout).
+ */
+export default function fseSsr(options = {}) {
+  const { locales = "../../locales", defaultLocale = "en" } = options;
+  return {
+    name: PKG_NAME,
+    hooks: {
+      "astro:config:setup": ({ config, updateConfig, logger }) => {
+        generateTranslationTypes(config.root, locales, defaultLocale, logger);
+        updateConfig({
+          vite: { plugins: [vitePlugin()] },
+        });
+      },
+    },
+  };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "fse-ssr",
+  "version": "0.1.0",
+  "description": "Compile-to-Tera SSR bindings for full_stack_engine's Astro starter: author native TypeScript in .astro files, get Tera output at build time.",
+  "type": "module",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StevenUster/full_stack_engine.git",
+    "directory": "fse-ssr"
+  },
+  "files": [
+    "dist",
+    "integration.mjs"
+  ],
+  "exports": {
+    ".": "./integration.mjs",
+    "./ssr": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch --preserveWatchOutput"
+  },
+  "peerDependencies": {
+    "astro": ">=5.0.0"
+  },
+  "dependencies": {
+    "@babel/generator": "^8.0.0",
+    "@babel/parser": "^8.0.0",
+    "@babel/traverse": "^8.0.0",
+    "@babel/types": "^8.0.0"
+  },
+  "devDependencies": {
+    "astro": "5.17.1",
+    "typescript": "^5.9.3"
+  }
+}