@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/ssg.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Static Site Generation (SSG) with Incremental Static Regeneration (ISR)
+ *
+ * Pre-renders pages at build time for optimal performance and SEO.
+ * Supports on-demand revalidation for dynamic content.
+ *
+ * ## Features
+ *
+ * - Build-time page generation from file-based routes
+ * - Dynamic route handling with getStaticPaths()
+ * - Incremental Static Regeneration (ISR)
+ * - Automatic sitemap generation
+ * - RSS feed generation
+ * - Content source integrations (Markdown, CMS, API)
+ * - Parallel page generation
+ * - Build caching for faster rebuilds
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { generateStaticSite, defineStaticPaths } from 'stx/ssg'
+ *
+ * // Generate entire site
+ * await generateStaticSite({
+ *   pagesDir: 'pages',
+ *   outputDir: 'dist',
+ *   revalidate: 3600, // ISR: revalidate every hour
+ * })
+ * ```
+ *
+ * For dynamic routes, export getStaticPaths in your template:
+ * ```html
+ * <script server>
+ * export async function getStaticPaths() {
+ *   const posts = await fetchPosts()
+ *   return posts.map(post => ({
+ *     params: { slug: post.slug },
+ *     props: { post }
+ *   }))
+ * }
+ * </script>
+ * ```
+ *
+ * @module ssg
+ */
+import type { StxOptions } from './types';
+export interface SSGConfig {
+    /**
+     * Client-side router options, forwarded verbatim to the injected router.
+     *
+     * Read here as `options.router` when the page is generated. Previously typed
+     * only as an `any` cast at the call site, which let `buildApp` omit it
+     * without the compiler noticing — so a project that configured `container`
+     * or `prefetch` got the client's built-in defaults instead.
+     */
+    router?: StxOptions['router'];
+    /** Directory containing pages (default: 'pages') */
+    pagesDir?: string;
+    /**
+     * Directory `@include` resolves against. Defaults to the config's
+     * `partialsDir`.
+     *
+     * `pagesDir`, `publicDir` and `outputDir` were all overridable here and these
+     * two were not, so a caller could point the build at one directory layout and
+     * silently get another for its partials (stacksjs/stx#1921).
+     */
+    partialsDir?: string;
+    /** Directory components resolve against. Defaults to the config's `componentsDir`. */
+    componentsDir?: string;
+    /**
+     * Fail the build when an `@include` cannot be resolved (default: true).
+     *
+     * A failed include renders the error into the page and, before this, left the
+     * build reporting `Failed: 0` with exit 0 — so the only way to find it was to
+     * read the emitted HTML, which is exactly what nobody does when the build says
+     * success. An unresolvable include is not a recoverable condition in a build:
+     * it produces a file you would never knowingly deploy.
+     *
+     * Set `false` for the old behaviour.
+     */
+    failOnIncludeError?: boolean;
+    /** Output directory for generated files (default: 'dist') */
+    outputDir?: string;
+    /** Base URL for the site (default: '/') */
+    baseUrl?: string;
+    /** Site domain for absolute URLs */
+    domain?: string;
+    /** Enable ISR with revalidation time in seconds */
+    revalidate?: number | false;
+    /** Generate sitemap.xml */
+    sitemap?: boolean;
+    /**
+     * Routes to keep out of sitemap.xml (#1866).
+     *
+     * Strings match a URL exactly or as a `/prefix/` when they end in `/`;
+     * RegExps are tested against the URL. A page can also exclude itself with
+     * `definePageMeta({ sitemap: false })` or by declaring a `noindex` robots
+     * meta, which is checked without needing this list.
+     *
+     * @example
+     * ```ts
+     * sitemapExclude: ['/login', '/account/', /^\/admin/]
+     * ```
+     */
+    sitemapExclude?: (string | RegExp)[];
+    /**
+     * Generate robots.txt (default: true).
+     *
+     * Written from the same resolved site URL as the sitemap, with a `Sitemap:`
+     * line pointing at it, and a `Disallow` for every `sitemapExclude` entry —
+     * so the two files cannot disagree about what is public.
+     */
+    robots?: boolean | RobotsConfig;
+    /** Generate RSS feed */
+    rss?: boolean | RSSConfig;
+    /** Parallel page generation limit (default: 10) */
+    concurrency?: number;
+    /** Enable build caching (default: true) */
+    cache?: boolean;
+    /** Cache directory (default: `ssg-cache` inside the state directory) */
+    cacheDir?: string;
+    /** Custom content loaders */
+    contentLoaders?: ContentLoader[];
+    /** Pre-render hooks */
+    hooks?: SSGHooks;
+    /** Minify HTML output (default: true) */
+    minify?: boolean;
+    /** Generate 404 page */
+    generate404?: boolean;
+    /** Additional files to copy to output */
+    publicDir?: string;
+    /** Trailing slash behavior */
+    trailingSlash?: boolean;
+    /** Clean output directory before build */
+    cleanOutput?: boolean;
+    /**
+     * Extra input folded into every page's cache key.
+     *
+     * A page's key is its own file plus the dependencies collected while
+     * rendering it, which covers templates, components and layouts and nothing
+     * else. Anything build-wide — the Css config, an env var the pages read
+     * — is invisible to it, and a build that reports every route `Cached` and
+     * exits 0 gives no signal that it used the old value (#1940).
+     *
+     * Defaults to a digest of the resolved Css config. Set it to add your
+     * own build inputs; set it to a constant to opt out of that default.
+     */
+    cacheSalt?: string;
+    /**
+     * Per-island chunking (#1746): lift each `client="<trigger>"` island's inline
+     * setup script into a content-hashed chunk under `_stx/islands/` that the
+     * runtime fetches only on the hydration trigger. Default `false` (opt-in) —
+     * when off, builds are byte-identical and islands stay inline.
+     */
+    chunkIslands?: boolean;
+    /**
+     * Emit `<link rel="prefetch" as="script">` hints for `visible`/`idle` island
+     * chunks so they warm in cache before the trigger fires (instant hydration,
+     * still no inline JS). `interaction`/`media:` islands are skipped. Requires
+     * `chunkIslands`. Default `false` — trades some idle bandwidth for latency.
+     */
+    prefetchIslands?: boolean;
+    /**
+     * Stamp Subresource Integrity (`sha384`) on island chunks so the runtime pins
+     * them against tampering and a strict CSP can require SRI. Requires
+     * `chunkIslands`. Default `false` — only enable when chunks are served
+     * byte-for-byte unchanged (no CDN/proxy transform).
+     */
+    integrityIslands?: boolean;
+}
+/** robots.txt options for the static build (#1866). */
+export interface RobotsConfig {
+    /** Extra paths to disallow, on top of `sitemapExclude`. */
+    disallow?: string[];
+    /** Paths to explicitly allow. Defaults to `['/']`. */
+    allow?: string[];
+    /** User agent the rules apply to. Defaults to `*`. */
+    userAgent?: string;
+    /** Emit the `Sitemap:` line (default: true when a sitemap is generated). */
+    sitemap?: boolean;
+}
+export interface RSSConfig {
+    title: string;
+    description: string;
+    link: string;
+    language?: string;
+    copyright?: string;
+    /** Function to get items for RSS feed */
+    getItems?: () => Promise<RSSItem[]>;
+}
+export interface RSSItem {
+    title: string;
+    link: string;
+    description?: string;
+    pubDate?: Date;
+    author?: string;
+    categories?: string[];
+    guid?: string;
+}
+export interface StaticPath {
+    /** Route parameters */
+    params: Record<string, string>;
+    /** Props to pass to the page */
+    props?: Record<string, unknown>;
+    /** Page-specific revalidation time (overrides global) */
+    revalidate?: number | false;
+}
+export interface StaticPathsResult {
+    paths: StaticPath[];
+    /** Fallback behavior for paths not returned */
+    fallback?: 'blocking' | 'static' | false;
+}
+export interface ContentLoader {
+    /** Name of the loader */
+    name: string;
+    /** File extensions this loader handles */
+    extensions: string[];
+    /** Load content from file */
+    load: (filePath: string) => Promise<ContentResult>;
+}
+export interface ContentResult {
+    /** Rendered HTML content */
+    content: string;
+    /** Frontmatter/metadata */
+    data: Record<string, unknown>;
+    /** Table of contents (for markdown) */
+    toc?: TocItem[];
+}
+export interface TocItem {
+    id: string;
+    text: string;
+    level: number;
+    children?: TocItem[];
+}
+export interface SSGHooks {
+    /** Called before build starts */
+    onBuildStart?: () => void | Promise<void>;
+    /** Called after build completes */
+    onBuildEnd?: (result: SSGResult) => void | Promise<void>;
+    /** Called before each page is rendered */
+    onPageStart?: (route: string) => void | Promise<void>;
+    /** Called after each page is rendered */
+    onPageEnd?: (route: string, html: string) => void | Promise<void>;
+    /** Called on build error */
+    onError?: (error: Error, route?: string) => void | Promise<void>;
+}
+export interface SSGResult {
+    /** Total pages generated */
+    totalPages: number;
+    /** Successfully generated pages */
+    successCount: number;
+    /** Failed pages */
+    failedCount: number;
+    /** Pages that were cached */
+    cachedCount: number;
+    /** Build time in milliseconds */
+    buildTime: number;
+    /** Generated sitemap path */
+    sitemapPath?: string;
+    /** Generated RSS path */
+    rssPath?: string;
+    /** Individual page results */
+    pages: PageResult[];
+    /** Errors encountered */
+    errors: PageError[];
+    /**
+     * Per-island chunking stats (#1746), present only when `chunkIslands` emitted
+     * any chunks: `count` unique (content-addressed) chunk files and `totalBytes`
+     * of island JS moved out of inline HTML into lazily-fetched chunks.
+     */
+    islandChunks?: {
+        count: number;
+        totalBytes: number;
+    };
+}
+export interface PageResult {
+    route: string;
+    outputPath: string;
+    size: number;
+    cached: boolean;
+    revalidateAt?: number;
+}
+export interface PageError {
+    route: string;
+    error: Error;
+}
+export interface ISRCache {
+    /** Get cached page */
+    get: (route: string) => Promise<CachedPage | null>;
+    /** Set cached page */
+    set: (route: string, page: CachedPage) => Promise<void>;
+    /** Invalidate cached page */
+    invalidate: (route: string) => Promise<void>;
+    /** Invalidate all pages matching pattern */
+    invalidatePattern: (pattern: RegExp) => Promise<void>;
+    /** Check if page needs revalidation */
+    needsRevalidation: (route: string) => Promise<boolean>;
+}
+export interface CachedPage {
+    html: string;
+    generatedAt: number;
+    revalidateAfter: number;
+    etag: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Whether a page declares an `action` — the export that receives its own POST.
+ *
+ * Exported so the rule is testable without running a build. A page action
+ * cannot run in a static build: `action` receives a POST, and a static build
+ * produces files, so there is no server left to receive one (stacksjs/stx#1847).
+ */
+export declare function declaresPageAction(source: string): boolean;
+/**
+ * Generate sitemap.xml
+ */
+/**
+ * Whether a generated page should stay out of sitemap.xml (#1866).
+ *
+ * Three independent ways to say no, because they are declared in three
+ * different places: the build config (`sitemapExclude`), the page itself
+ * (`definePageMeta({ sitemap: false })`), and the page's own robots meta — a
+ * page already marked `noindex` asking to be listed in a sitemap is a
+ * contradiction, and apps were adding that meta by hand precisely because the
+ * sitemap ignored them.
+ */
+export declare function isExcludedFromSitemap(url: string, html: string, pageMeta: Record<string, any> | null | undefined, exclude: (string | RegExp)[]): boolean;
+/**
+ * Generate static site
+ */
+export declare function generateStaticSite(options?: SSGConfig): Promise<SSGResult>;
+/**
+ * Create ISR handler for runtime revalidation
+ */
+export declare function createISRHandler(options?: SSGConfig): {
+    get: (route: string) => Promise<{
+        html: string;
+        headers: Record<string, string>;
+    } | null>;
+    revalidate: (route: string) => Promise<void>;
+    invalidate: (route: string | RegExp) => Promise<void>;
+};
+/**
+ * Define static paths for dynamic routes (used in templates)
+ */
+export declare function defineStaticPaths(pathsFn: () => Promise<StaticPath[]> | StaticPath[]): () => Promise<StaticPathsResult>;
+/**
+ * Create a markdown content loader
+ */
+export declare function createMarkdownLoader(): ContentLoader;
+declare const _default: {
+    generateStaticSite: typeof generateStaticSite;
+    createISRHandler: typeof createISRHandler;
+    defineStaticPaths: typeof defineStaticPaths;
+    createMarkdownLoader: typeof createMarkdownLoader;
+};
+export default _default;

package/dist/ssg.js

@@ -0,0 +1,94 @@
+// @bun
+import{Dk as Fq,yk as Uq,zk as Iq}from"./chunk-71t0yan0.js";import{Ek as Eq,Fk as Tq,Gk as Dq}from"./chunk-58f0mthg.js";import{$k as _q,cl as zq,dl as Aq}from"./chunk-4ww3znrr.js";import{Fm as Oq,Gp as P,To as Bq,_n as l,bo as Hq,dr as n}from"./chunk-y11cxbxd.js";import"./chunk-92mj1t26.js";import"./chunk-8mjdpr94.js";import"./chunk-pkaabd8h.js";import"./chunk-xpp135ad.js";import{tt as Xq}from"./chunk-wrzwgkbx.js";import{yt as d}from"./chunk-5kk8gsj2.js";import"./chunk-38ejahd9.js";import"./chunk-ypmqf7tm.js";import"./chunk-de7fye10.js";import"./chunk-v5e1gxwm.js";import{Nu as Yq,Ou as Vq,Pu as jq,Qu as Gq,Ru as Lq,Su as Nq}from"./chunk-b6ej2fdf.js";import"./chunk-x650vjcp.js";import{gv as y}from"./chunk-qc1f74ek.js";import O from"fs";import j from"path";import{createHash as xq}from"crypto";function yq(q){try{return new Bun.Transpiler({loader:"js",minifyWhitespace:!0}).transformSync(q).replace(/\}(var |let |const |function )/g,"};$1").trim()}catch{return q}}var Pq=/<script\s+type="stx\/island"\s+data-stx-island="([^"]+)"([^>]*)>([\s\S]*?)<\/script>/g;function Cq(q){return Bun.hash(q).toString(16)}function Qq(q,Z={}){if(!q.includes('type="stx/island"'))return{html:q,chunks:[]};let $=new Map,Q=q.replace(Pq,(J,W,z,A)=>{let G=A.trim();if(!G)return J;if(/\bdata-stx-src=/.test(z))return J;if(Z.minify)G=yq(G);let X=Cq(G);if(!$.has(X))$.set(X,G);let B=Z.integrity?` data-stx-integrity="sha384-${xq("sha384").update(G).digest("base64")}"`:"";return`<script type="stx/island" data-stx-island="${W}" data-stx-src="/_stx/islands/${X}.js"${B}${z}></script>`}),K=Array.from($,([J,W])=>({hash:J,code:W}));return{html:Q,chunks:K}}var gq=new Set(["visible","idle"]);function Zq(q){if(!q.includes("data-stx-src="))return q;let Z=new Map,$=/data-stx-scope="([^"]+)"[^>]*?stx-hydrate="([^"]+)"/g,Q;while((Q=$.exec(q))!==null)Z.set(Q[1],Q[2]);let K=new Set,J=/data-stx-island="([^"]+)"[^>]*?data-stx-src="([^"]+)"/g,W;while((W=J.exec(q))!==null)if(gq.has(Z.get(W[1])||""))K.add(W[2]);let z=q.lastIndexOf("</head>");if(K.size===0||z===-1)return q;let A=Array.from(K).filter((G)=>!q.includes(`rel="prefetch" href="${G}"`)).map((G)=>`<link rel="prefetch" href="${G}" as="script">`).join("");if(!A)return q;return q.slice(0,z)+A+q.slice(z)}var fq=["STX_SITE_URL","SITE_URL","URL","VERCEL_URL","CF_PAGES_URL"];function h(q){let Z=q.trim();if(!Z)return null;let $=/^https?:\/\//i.test(Z)?Z:`https://${Z}`;try{return new URL($).origin+new URL($).pathname.replace(/\/$/,"")}catch{return null}}function mq(q){for(let Z of fq){let $=q[Z];if(!$)continue;let Q=h($);if(Q)return{url:Q,source:"env",via:Z}}return null}function $q(q){if(!q||typeof q!=="object")return null;let Z=q,$=Z.site?.url??Z.url??Z.app?.url;return typeof $==="string"?h($):null}async function dq(q){let{existsSync:Z}=await import("fs"),$=await import("path");for(let Q of["site.config.ts","site.config.js",".config/site.config.ts"]){let K=$.resolve(q,Q);if(!Z(K))continue;try{let J=await import(K),W=$q(J.default??J);if(W)return W}catch{}}return null}async function Kq(q={}){let Z=q.cwd??process.cwd(),$=q.env??process.env;if(q.explicit){let W=h(q.explicit);if(W)return{url:W,source:"option"}}let Q=$q(q.stxConfig);if(Q)return{url:Q,source:"stx.config",via:"site.url"};let K=await dq(Z);if(K)return{url:K,source:"site.config",via:"url"};let J=mq($);if(J)return J;return{url:"http://localhost",source:"fallback"}}function Wq(){return["No site URL configured \u2014 sitemap.xml and robots.txt will point at http://localhost.","  Set one in stx.config.ts (site: { url: 'https://example.com' }), in site.config.ts,","  via --domain, or with SITE_URL in the build environment."].join(`
+`)}class wq{cacheDir;cache=new Map;loaded=!1;salt;constructor(q,Z=""){this.cacheDir=q,this.salt=Z}async load(){if(this.loaded)return;let q=j.join(this.cacheDir,"build-cache.json");if(await Bun.file(q).exists())try{let Z=JSON.parse(await Bun.file(q).text());for(let[$,Q]of Object.entries(Z))this.cache.set($,Q)}catch{}this.loaded=!0}async save(){await O.promises.mkdir(this.cacheDir,{recursive:!0});let q=j.join(this.cacheDir,"build-cache.json"),Z={};for(let[$,Q]of this.cache)Z[$]=Q;await Bun.write(q,JSON.stringify(Z))}getHash(q,Z){let $=O.statSync(q),Q=`${this.salt}|${q}:${$.mtimeMs}`;for(let J of Z)if(O.existsSync(J)){let W=O.statSync(J);Q+=`:${J}:${W.mtimeMs}`}let K=0;for(let J=0;J<Q.length;J++){let W=Q.charCodeAt(J);K=(K<<5)-K+W,K=K&K}return Math.abs(K).toString(36)}get(q,Z){let $=this.cache.get(q);if(!$)return null;let Q=this.getHash(Z,$.dependencies??[]);if($.hash!==Q)return this.cache.delete(q),null;return $.html}set(q,Z,$,Q){let K=this.getHash(Z,$);this.cache.set(q,{hash:K,html:Q,generatedAt:Date.now(),dependencies:$})}}class Rq{cacheDir;constructor(q){this.cacheDir=q}getFilePath(q){let Z=q.replace(/[^a-zA-Z0-9]/g,"_")+".json";return j.join(this.cacheDir,"isr",Z)}async get(q){let Z=this.getFilePath(q);if(!await Bun.file(Z).exists())return null;try{return JSON.parse(await Bun.file(Z).text())}catch{return null}}async set(q,Z){let $=this.getFilePath(q);await O.promises.mkdir(j.dirname($),{recursive:!0}),await Bun.write($,JSON.stringify(Z))}async invalidate(q){let Z=this.getFilePath(q);if(await Bun.file(Z).exists())await O.promises.unlink(Z)}async invalidatePattern(q){let Z=j.join(this.cacheDir,"isr");if(!O.existsSync(Z))return;let $=await O.promises.readdir(Z);for(let Q of $){let K=Q.replace(/_/g,"/").replace(".json","");if(q.test(K))await O.promises.unlink(j.join(Z,Q))}}async needsRevalidation(q){let Z=await this.get(q);if(!Z)return!0;return Date.now()>Z.revalidateAfter}}async function pq(q){try{let $=(await Bun.file(q).text()).match(/<script\s+server\b[^>]*>([\s\S]*?)<\/script>/i);if(!$)return null;let Q=$[1];if(!Q.includes("getStaticPaths"))return null;let K=Q.match(/(?:export\s+)?(?:async\s+)?function\s+getStaticPaths\s*\([^)]*\)\s*\{([\s\S]*?)\n[\t ]*\}/);if(!K)return null;return await Function(`
+      return (async function getStaticPaths() {
+        ${K[1]}
+      })()
+    `)()}catch(Z){return console.error(`Error extracting static paths from ${q}:`,Z),null}}async function uq(q){let Z=[];if(!q.isDynamic)Z.push({url:q.pattern,params:{}});else{let $=await pq(q.filePath);if(!$||$.paths.length===0)return console.warn(`Warning: Dynamic route ${q.pattern} has no getStaticPaths or returned empty paths`),Z;for(let Q of $.paths){let K=q.pattern;for(let[J,W]of Object.entries(Q.params))K=K.replace(`:${J}`,W).replace(`:${J}*`,W);Z.push({url:K,params:Q.params,props:Q.props,revalidate:Q.revalidate})}}return Z}async function hq(q){let Z=[q.replace(/\.stx$/,".data.ts"),q.replace(/\.stx$/,".data.js"),q+".data.ts",q+".data.js"];for(let $ of Z)if(await Bun.file($).exists())try{let Q=await import($);if(typeof Q.default==="function")return await Q.default();else if(typeof Q.default==="object")return Q.default;else if(typeof Q.getData==="function")return await Q.getData();else{let{default:K,...J}=Q;return J}}catch(Q){console.error(`Error loading data file ${$}:`,Q)}return null}async function cq(q,Z,$){let Q=q.match(/<script\s+server\b[^>]*>([\s\S]*?)<\/script>/i);if(!Q)return null;let K=Q[1];if(!K.includes("getStaticProps"))return null;try{let J=K.match(/(?:export\s+)?(?:async\s+)?function\s+getStaticProps\s*\([^)]*\)\s*\{([\s\S]*?)\n\}/);if(!J)return null;return await Function("params",`
+      return (async function getStaticProps() {
+        ${J[1]}
+      })()
+    `)(Z)}catch(J){return console.error(`Error executing getStaticProps in ${$}:`,J),null}}function lq(q){return/(?:^|[^\w$.])(?:export\s+)?(?:async\s+)?function\s+action\s*\(/.test(q)||/(?:^|[^\w$.])(?:export\s+)?(?:const|let|var)\s+action\s*=/.test(q)}async function Mq(q,Z,$={},Q,K){let J=await Bun.file(q.filePath).text(),W=await hq(q.filePath),z=await cq(J,Z,q.filePath),A={...W||{},...z||{},...$,params:Z,$route:{path:q.pattern,params:Z}},G=new Set,X=[],B={...K,...Q.partialsDir?{partialsDir:Q.partialsDir}:{},...Q.componentsDir?{componentsDir:Q.componentsDir}:{},debug:!1,cache:!1,autoShell:!0,onIncludeError:(_)=>{X.push(`${j.relative(process.cwd(),_.templatePath)}: ${_.message}
+    resolved against partialsDir: ${_.partialsDir}`)}};if(lq(J))console.warn(`Warning: ${q.pattern} exports a page action, which cannot run in a static build. Its form will submit to a file. Serve this route with the production server, or point the form's action at a route handler.`);let L=await P(J,A,q.filePath,B,G);for(let _ of[q.filePath,...G])for(let F of _q(_))G.add(F);if(Object.keys(Z).length>0){let _=`<script>if(window.stx)window.stx._rp=${JSON.stringify(Z)};else window.__stx_rp=${JSON.stringify(Z)};</script>`;if(L.includes("</head>"))L=L.replace("</head>",`${_}
+</head>`);else L=`${_}
+${L}`}if(L=await Hq(L,{router:Q.router}),L=await Xq(L),Q.minify!==!1)return{html:nq(L),dependencies:Array.from(G),includeFailures:X};return{html:L,dependencies:Array.from(G),includeFailures:X}}function nq(q){let Z=[],$=0,Q=/(<script[^>]*>)([\s\S]*?)(<\/script>)/gi,K;while((K=Q.exec(q))!==null){let W=q.slice($,K.index);Z.push(W.replace(/<!--(?!\[if)[\s\S]*?-->/g,"").replace(/\s+/g," ").replace(/>\s+</g,"><"));let z=K[1],A=K[2],G=K[3];A=A.replace(/([^:"\\'`])\/\/(?!\/)(?![*!])([^\n]*)/g,"$1"),Z.push(z+A+G),$=K.index+K[0].length}let J=q.slice($);return Z.push(J.replace(/<!--(?!\[if)[\s\S]*?-->/g,"").replace(/\s+/g," ").replace(/>\s+</g,"><")),Z.join("").trim()}function iq(q){let Z=0;for(let $=0;$<q.length;$++){let Q=q.charCodeAt($);Z=(Z<<5)-Z+Q,Z=Z&Z}return`"${Math.abs(Z).toString(36)}"`}function sq(q,Z,$,Q){if($?.sitemap===!1)return!0;if(/<meta[^>]+name=["']robots["'][^>]+content=["'][^"']*noindex/i.test(Z))return!0;return Q.some((K)=>{if(K instanceof RegExp)return K.test(q);return K.endsWith("/")?q===K.slice(0,-1)||q.startsWith(K):q===K})}function oq(q,Z){return`<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${q.map((Q)=>{let K=new URL(Q.loc,Z).href,J=`  <url>
+    <loc>${T(K)}</loc>`;if(Q.lastmod)J+=`
+    <lastmod>${Q.lastmod}</lastmod>`;if(Q.changefreq)J+=`
+    <changefreq>${Q.changefreq}</changefreq>`;if(Q.priority!==void 0)J+=`
+    <priority>${Q.priority}</priority>`;return J+=`
+  </url>`,J}).join(`
+`)}
+</urlset>`}function T(q){return q.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&apos;")}function rq(q,Z){let $=Z.map((Q)=>{let K="    <item>";if(K+=`
+      <title>${T(Q.title)}</title>`,K+=`
+      <link>${T(Q.link)}</link>`,Q.description)K+=`
+      <description>${T(Q.description)}</description>`;if(Q.pubDate)K+=`
+      <pubDate>${Q.pubDate.toUTCString()}</pubDate>`;if(Q.author)K+=`
+      <author>${T(Q.author)}</author>`;if(Q.categories)for(let J of Q.categories)K+=`
+      <category>${T(J)}</category>`;if(Q.guid)K+=`
+      <guid>${T(Q.guid)}</guid>`;return K+=`
+    </item>`,K});return`<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${T(q.title)}</title>
+    <link>${T(q.link)}</link>
+    <description>${T(q.description)}</description>
+    ${q.language?`<language>${q.language}</language>`:""}
+    ${q.copyright?`<copyright>${T(q.copyright)}</copyright>`:""}
+    <lastBuildDate>${new Date().toUTCString()}</lastBuildDate>
+    <atom:link href="${q.link}/rss.xml" rel="self" type="application/rss+xml"/>
+${$.join(`
+`)}
+  </channel>
+</rss>`}async function aq(q={}){let Z=Date.now();Aq();let $=await n(process.cwd()),Q=$.build||{},K=await Kq({explicit:q.domain||Q.domain,stxConfig:$});if(K.source==="fallback"&&(q.sitemap??Q.sitemap??!0))console.warn(Wq());let J={router:q.router??$?.router??{},pagesDir:q.pagesDir||Q.pagesDir||"pages",outputDir:q.outputDir||Q.outputDir||"dist",baseUrl:q.baseUrl||Q.baseUrl||"/",domain:K.url,revalidate:q.revalidate??Q.revalidate??!1,sitemap:q.sitemap??Q.sitemap??!0,sitemapExclude:q.sitemapExclude||Q.sitemapExclude||[],robots:q.robots??Q.robots??!0,rss:q.rss??Q.rss??!1,concurrency:q.concurrency||Q.concurrency||10,cache:q.cache??Q.cache??!0,cacheDir:q.cacheDir||Q.cacheDir||d(process.cwd(),"ssg-cache"),contentLoaders:q.contentLoaders||[],hooks:q.hooks||{},minify:q.minify??Q.minify??!0,generate404:q.generate404??Q.generate404??!0,publicDir:q.publicDir||Q.publicDir||"public",trailingSlash:q.trailingSlash??Q.trailingSlash??!1,cleanOutput:q.cleanOutput??Q.cleanOutput??!0,cacheSalt:q.cacheSalt??"",partialsDir:q.partialsDir||$?.partialsDir||"",componentsDir:q.componentsDir||$?.componentsDir||"",failOnIncludeError:q.failOnIncludeError??!0,chunkIslands:q.chunkIslands===!0,prefetchIslands:q.prefetchIslands===!0,integrityIslands:q.integrityIslands===!0},W={totalPages:0,successCount:0,failedCount:0,cachedCount:0,buildTime:0,pages:[],errors:[]},z=new Set,A=0,G={},X={};await J.hooks.onBuildStart?.();try{if(J.cleanOutput&&O.existsSync(J.outputDir))await O.promises.rm(J.outputDir,{recursive:!0});await O.promises.mkdir(J.outputDir,{recursive:!0});let L=J.cacheSalt;if(!L){let{resolveUserCssConfig:Y,fingerprintConfig:N}=await import("./chunk-2tk1zkrz.js");try{L=N(await Y(process.cwd()))}catch{}}let{prepareImageDelivery:_}=await import("./chunk-mxfh1nxg.js"),F=await _(J.publicDir,J.outputDir);if(F.count>0)console.log(`Optimized ${F.count} image(s) for responsive delivery`),L=[L,F.fingerprint].filter(Boolean).join(":");let C=new wq(J.cacheDir,L);if(J.cache)await C.load();try{let{generateCss:Y}=await import("./chunk-2tk1zkrz.js");await Y('<div class="bg-black"></div>')}catch{}Yq();let kq=$?.routeMiddleware?.dir||"middleware";await jq(process.cwd(),kq);let p=Vq();if(p.length>0)console.log(`Loaded ${p.length} middleware: ${p.join(", ")}`);let bq=$?.routeMiddleware?.global||[];Fq($?.layoutsDir,d(process.cwd()));let i=l(".",{pagesDir:J.pagesDir});console.log(`Found ${i.length} routes`);let g=[];for(let Y of i){let N=await uq(Y);for(let H of N)g.push({route:Y,url:H.url,params:H.params,props:H.props,revalidate:H.revalidate??J.revalidate})}W.totalPages=g.length,console.log(`Generating ${W.totalPages} pages...`);let b=[],s=[];for(let Y=0;Y<g.length;Y+=J.concurrency)s.push(g.slice(Y,Y+J.concurrency));for(let Y of s)await Promise.all(Y.map(async(N)=>{let{route:H,url:V,params:S,props:Sq,revalidate:a}=N;try{await J.hooks.onPageStart?.(V);let w=await Bun.file(H.filePath).text(),R=JJ(w),vq=R?.middleware?Array.isArray(R.middleware)?R.middleware:[R.middleware]:[],t=[...bq,...vq];if(t.length>0){let D=Gq(V,S,R||{}),M=Lq(D,null,void 0,{isServer:!0}),E=await Nq(t,M);if(E.redirect){let U=typeof E.redirect==="string"?E.redirect:E.redirect.path||E.redirect,x=QJ(String(U),V),k=ZJ(V,J);await O.promises.mkdir(j.dirname(k),{recursive:!0}),await Bun.write(k,x),W.successCount++,W.pages.push({route:V,outputPath:k,size:Buffer.byteLength(x),cached:!1}),b.push({loc:V,lastmod:new Date().toISOString()}),console.log(`  \u21B3 ${V} \u2192 redirect to ${U}`);return}if(E.abort){let U=typeof E.abort==="string"?E.abort:E.abort?.error?.message||"aborted";console.warn(`  \u21B3 ${V} \u2014 middleware aborted: ${U}`);return}}let e=w.match(/definePageMeta\s*\(\s*\{[\s\S]*?validate\s*:\s*((?:\([^)]*\)|[^,}])*(?:\{[\s\S]*?\})?)/m);if(e)try{if(!await Function("route",`
+                const validate = ${e[1]};
+                return validate(route);
+              `)({params:S})){console.warn(`Validation failed for ${V}, skipping...`);return}}catch{}let I=null,qq=!1;if(J.cache){if(I=C.get(V,H.filePath),I)qq=!0,W.cachedCount++}if(!I){let D=await Mq(H,S,Sq,J,$);if(I=D.html,J.failOnIncludeError&&D.includeFailures.length>0)throw Error(`${D.includeFailures.length} include(s) failed to resolve, so this page would have shipped with an error banner where the markup should be:
+  ${D.includeFailures.join(`
+  `)}
+Set ssg.failOnIncludeError to false to build anyway.`);if(J.cache)C.set(V,H.filePath,D.dependencies,I)}let v;if(J.trailingSlash)v=j.join(J.outputDir,V,"index.html");else v=V==="/"?j.join(J.outputDir,"index.html"):j.join(J.outputDir,`${V}.html`);if(J.chunkIslands){let{html:D,chunks:M}=Qq(I,{integrity:J.integrityIslands,minify:J.minify});if(M.length>0){let E=j.join(J.outputDir,"_stx","islands");await O.promises.mkdir(E,{recursive:!0});for(let U of M){let x=j.join(E,`${U.hash}.js`);if(!await Bun.file(x).exists())await Bun.write(x,U.code);if(!z.has(U.hash)){z.add(U.hash);let k=Buffer.byteLength(U.code,"utf8");A+=k,G[U.hash]={bytes:k,file:`/_stx/islands/${U.hash}.js`}}}if(X[V]=M.map((U)=>U.hash),I=D,J.prefetchIslands)I=Zq(I)}}if(await O.promises.mkdir(j.dirname(v),{recursive:!0}),await Bun.write(v,I),!sq(V,I,R,J.sitemapExclude))b.push({loc:V,lastmod:new Date().toISOString().split("T")[0],priority:V==="/"?1:0.8});let Jq={route:V,outputPath:v,size:Buffer.byteLength(I,"utf8"),cached:qq};if(a!==!1)Jq.revalidateAt=Date.now()+a*1000;W.pages.push(Jq),W.successCount++,await J.hooks.onPageEnd?.(V,I)}catch(w){W.failedCount++,W.errors.push({route:V,error:w}),await J.hooks.onError?.(w,V),console.error(`Error generating ${V}:`,w)}}));let o=zq();if(o.length>0){let Y=o.map((N)=>`${N.filePath}: ${N.message}`).join(`
+`);throw Error(`Client script bundling failed:
+${Y}`)}if(J.cache)await C.save();if(J.generate404){let Y=j.join(J.pagesDir,"404.stx");if(await Bun.file(Y).exists()){let N=new Set,H={...$,debug:!1,cache:!1},V=await P(await Bun.file(Y).text(),{},Y,H,N);await Bun.write(j.join(J.outputDir,"404.html"),V)}else await Bun.write(j.join(J.outputDir,"404.html"),`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Page Not Found</title>
+  <style>
+    body { font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; min-height: 100vh; margin: 0; }
+    .container { text-align: center; }
+    h1 { font-size: 6rem; margin: 0; color: #333; }
+    p { color: #666; }
+    a { color: #0066cc; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>404</h1>
+    <p>Page not found</p>
+    <a href="/">Go home</a>
+  </div>
+</body>
+</html>`)}for(let Y of[500]){let N=j.join(J.pagesDir,`${Y}.stx`);if(await Bun.file(N).exists()){let H=new Set,V={...$,debug:!1,cache:!1},S=await P(await Bun.file(N).text(),{},N,V,H);await Bun.write(j.join(J.outputDir,`${Y}.html`),S)}}let u=j.join(J.pagesDir,"error.stx");if(await Bun.file(u).exists()){let Y=new Set,N={...$,debug:!1,cache:!1},H=await P(await Bun.file(u).text(),{},u,N,Y);await Bun.write(j.join(J.outputDir,"error.html"),H)}if(J.sitemap&&b.length>0){let Y=oq(b,J.domain),N=j.join(J.outputDir,"sitemap.xml");await Bun.write(N,Y),W.sitemapPath=N,console.log(`Generated sitemap.xml with ${b.length} URLs`)}if(J.robots!==!1){let Y=typeof J.robots==="object"?J.robots:{},N=[...J.sitemapExclude.filter((V)=>typeof V==="string"),...Y.disallow||[]],H=Bq({rules:[{userAgent:Y.userAgent||"*",allow:Y.allow||["/"],...N.length>0?{disallow:N}:{}}],...Y.sitemap!==!1&&W.sitemapPath?{sitemap:new URL("/sitemap.xml",J.domain).href}:{}});await Bun.write(j.join(J.outputDir,"robots.txt"),H),console.log("Generated robots.txt")}if(J.rss){let Y=typeof J.rss==="object"?J.rss:{title:"Site Feed",description:"Latest updates",link:J.domain},N=[];if(Y.getItems)N=await Y.getItems();let H=rq(Y,N),V=j.join(J.outputDir,"rss.xml");await Bun.write(V,H),W.rssPath=V,console.log(`Generated rss.xml with ${N.length} items`)}let f=Uq(J.outputDir);if(f.assets>0)console.log(`Externalized ${f.assets} asset(s) from ${f.pages} page(s) (${(f.bytesInlined/1024).toFixed(1)}KB removed from HTML)`);let m=Iq(J.outputDir);if(m.assets>0)console.log(`Externalized ${m.assets} repeated asset(s) from ${m.pages} page(s) (${(m.bytesInlined/1024).toFixed(1)}KB removed from HTML)`);if(J.publicDir&&O.existsSync(J.publicDir))await c(J.publicDir,J.outputDir),console.log(`Copied public assets from ${J.publicDir}`);let r=Dq();if(r)await c(r,j.join(J.outputDir,Tq)),console.log(`Copied assets from ${Eq}`)}catch(L){throw await J.hooks.onError?.(L),L}if(W.buildTime=Date.now()-Z,z.size>0){W.islandChunks={count:z.size,totalBytes:A};let L={generatedChunks:z.size,totalBytes:A,chunks:G,pages:X};await Bun.write(j.join(J.outputDir,"_stx","islands-manifest.json"),JSON.stringify(L,null,2))}await J.hooks.onBuildEnd?.(W);let B=W.islandChunks?`
+  Island chunks: ${W.islandChunks.count} (${(W.islandChunks.totalBytes/1024).toFixed(1)} KB lifted out of inline HTML)`:"";return console.log(`
+Build complete!
+  Total: ${W.totalPages} pages
+  Success: ${W.successCount}
+  Cached: ${W.cachedCount}
+  Failed: ${W.failedCount}
+  Time: ${W.buildTime}ms${B}
+`),W}async function c(q,Z){await O.promises.mkdir(Z,{recursive:!0});let $=await O.promises.readdir(q,{withFileTypes:!0});for(let Q of $){let K=j.join(q,Q.name),J=j.join(Z,Q.name);if(Q.isDirectory())await O.promises.mkdir(J,{recursive:!0}),await c(K,J);else await O.promises.copyFile(K,J)}}function tq(q={}){let Z=q.cacheDir||d(process.cwd(),"ssg-cache"),$=new Rq(Z),Q=q.revalidate||3600;return{async get(K){let J=await $.get(K);if(!J)return null;if(Date.now()>J.revalidateAfter)this.revalidate(K).catch(console.error);return{html:J.html,headers:{"Cache-Control":`public, max-age=${Q}, stale-while-revalidate=${Q*2}`,ETag:J.etag,"X-ISR-Generated":new Date(J.generatedAt).toISOString(),...J.headers}}},async revalidate(K){let W=l(".",{pagesDir:q.pagesDir||"pages"}).find((B)=>{return K.match(B.regex)!==null});if(!W){console.warn(`Route not found for revalidation: ${K}`);return}let z=K.match(W.regex),A={};if(z)W.params.forEach((B,L)=>{A[B]=z[L+1]});let G=await n(),{html:X}=await Mq(W,A,{},q,G);await $.set(K,{html:X,generatedAt:Date.now(),revalidateAfter:Date.now()+Q*1000,etag:iq(X)}),console.log(`Revalidated: ${K}`)},async invalidate(K){if(typeof K==="string")await $.invalidate(K);else await $.invalidatePattern(K)}}}function eq(q){return async()=>{return{paths:await q(),fallback:!1}}}function qJ(){return{name:"markdown",extensions:[".md",".mdx"],async load(q){let Z=await Bun.file(q).text(),$=Z.match(/^---\n([\s\S]*?)\n---/),Q={},K=Z;if($){let G=$[1];K=Z.slice($[0].length).trim();for(let X of G.split(`
+`)){let B=X.indexOf(":");if(B>0){let L=X.slice(0,B).trim(),_=X.slice(B+1).trim();if(_==="true")_=!0;else if(_==="false")_=!1;else if(/^\d+$/.test(_))_=parseInt(_,10);else if(/^\d+\.\d+$/.test(_))_=parseFloat(_);else if(_.startsWith("[")&&_.endsWith("]"))_=_.slice(1,-1).split(",").map((F)=>F.trim().replace(/^['"]|['"]$/g,""));Q[L]=_}}}let J=K.replace(/^### (.*$)/gim,"<h3>$1</h3>").replace(/^## (.*$)/gim,"<h2>$1</h2>").replace(/^# (.*$)/gim,"<h1>$1</h1>").replace(/\*\*(.*)\*\*/gim,"<strong>$1</strong>").replace(/\*(.*)\*/gim,"<em>$1</em>").replace(/`([^`]+)`/gim,"<code>$1</code>").replace(/\[([^\]]+)\]\(([^)]+)\)/gim,'<a href="$2">$1</a>').replace(/\n/gim,"<br>"),W=[],z=/<h([1-6])>([^<]+)<\/h[1-6]>/gi,A;while((A=z.exec(J))!==null){let G=parseInt(A[1],10),X=A[2],B=X.toLowerCase().replace(/[^a-z0-9]+/g,"-");W.push({id:B,text:X,level:G})}return{content:J,data:Q,toc:W}}}}function JJ(q){return Oq(q)}function QJ(q,Z){return`<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta http-equiv="refresh" content="0; url=${q}">
+<link rel="canonical" href="${q}">
+<title>Redirecting...</title>
+</head>
+<body>
+<p>Redirecting to <a href="${q}">${q}</a>...</p>
+<script>window.location.replace('${q}')</script>
+</body>
+</html>`}function ZJ(q,Z){if(q==="/"||q==="")return j.join(Z.outputDir,"index.html");let $=q.replace(/^\/|\/$/g,"");if(Z.trailingSlash)return j.join(Z.outputDir,$,"index.html");return j.join(Z.outputDir,`${$}.html`)}var FJ={generateStaticSite:aq,createISRHandler:tq,defineStaticPaths:eq,createMarkdownLoader:qJ};export{sq as isExcludedFromSitemap,aq as generateStaticSite,eq as defineStaticPaths,FJ as default,lq as declaresPageAction,qJ as createMarkdownLoader,tq as createISRHandler};

package/dist/ssr.d.ts

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import type { StxOptions } from './types';
+/**
+ * Render a STX template with server-side data
+ *
+ * @param template - Template path relative to viewsDir, or inline template string
+ * @param data - Data to pass to the template
+ * @param options - Render options
+ */
+export declare function render(template: string, data?: Record<string, unknown>, options?: {
+    viewsDir?: string
+    layoutsDir?: string
+    stxOptions?: StxOptions
+    ctx?: RequestContext
+  }): Promise<Response>;
+/**
+ * Create a STX server application
+ */
+export declare function createApp(config?: AppConfig): StxServerApp;
+/** Session data store */
+export declare interface SessionData {
+  [key: string]: unknown
+}
+/** Session interface */
+export declare interface Session {
+  id: string
+  data: SessionData
+  get<T = unknown>(key: string): T | undefined
+  set(key: string, value: unknown): void
+  delete(key: string): void
+  clear(): void
+  has(key: string): boolean
+  flash(key: string, value?: unknown): unknown | undefined
+  regenerate(): void
+  destroy(): void
+}
+/** Pluggable session store interface for production-ready backends (Redis, DB, etc.) */
+export declare interface SessionStore {
+  get(sessionId: string): Promise<SessionData | null>
+  set(sessionId: string, data: SessionData, ttlSeconds: number): Promise<void>
+  delete(sessionId: string): Promise<void>
+}
+/** Request context passed to route handlers */
+export declare interface RequestContext {
+  request: Request
+  url: URL
+  params: Record<string, string>
+  query: Record<string, string>
+  session: Session
+  csrfToken: string
+  formData: () => Promise<Record<string, string | File>>
+  json: <T = unknown>() => Promise<T>
+  cookies: Record<string, string>
+  setCookie: (name: string, value: string, options?: CookieOptions) => void
+  responseHeaders: Headers
+  flash: (key: string, value: unknown) => void
+  getFlash: (key: string) => unknown
+  errors: ValidationErrors
+  old: (key: string) => string
+  isAuthenticated: () => boolean
+  user: () => unknown
+}
+/** Cookie options */
+export declare interface CookieOptions {
+  maxAge?: number
+  expires?: Date
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: 'Strict' | 'Lax' | 'None'
+}
+/** Validation errors */
+export declare interface ValidationErrors {
+  [field: string]: string[]
+}
+/** App configuration */
+export declare interface AppConfig {
+  viewsDir?: string
+  layoutsDir?: string
+  defaultLayout?: string
+  sessionSecret?: string
+  sessionCookieName?: string
+  sessionTtl?: number
+  stxOptions?: StxOptions
+  csrfCookieName?: string
+  csrfEnabled?: boolean
+  sessionStore?: SessionStore
+}
+/**
+ * Handle returned by {@link createApp} — the server application surface.
+ */
+export declare interface StxServerApp {
+  fetch: (request: Request) => Promise<Response>
+  get: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  post: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  put: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  delete: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  patch: (pattern: string, handler: RouteHandler, middleware?: Middleware[]) => StxServerApp
+  use: (middleware: Middleware) => StxServerApp
+  render: (template: string, data?: Record<string, unknown>, ctx?: RequestContext) => Promise<Response>
+  redirect: (url: string, status?: 302 | 301 | 303 | 307 | 308) => Response
+  back: (ctx: RequestContext, errors?: ValidationErrors, oldInput?: Record<string, string>) => Response
+  listen: (port?: number) => ReturnType<typeof Bun.serve>
+}
+/** Route handler */
+// eslint-disable-next-line pickier/no-unused-vars
+export type RouteHandler = (ctx: RequestContext) => Response | Promise<Response>;
+/** Middleware function */
+export type Middleware = (ctx: RequestContext, next: () => Promise<Response>) => Response | Promise<Response>;
+/** Default in-memory session store. Use a custom SessionStore (Redis, DB) for production. */
+export declare class MemorySessionStore implements SessionStore {
+  get(sessionId: string): Promise<SessionData | null>;
+  set(sessionId: string, data: SessionData, ttlSeconds: number): Promise<void>;
+  delete(sessionId: string): Promise<void>;
+}