/**
 * Extract real top-level `<script server>` elements without matching tag-like
 * text inside HTML comments or another script body. A regex over the whole
 * template mistakes documentation such as `// moved from <script server>` in
 * a client script for a nested server block, then removes the rest of that
 * client script through its closing tag.
 */
export declare function extractServerScriptsFromTemplate(content: string): {
  serverScripts: string[]
  templateContent: string
};
/**
 * A token to mint for this request, or null to leave it alone.
 *
 * Safe methods only, and only when the request carries none already: anything
 * else is somebody's live session, and rotating their token mid-flight would
 * reject the very form they are about to submit.
 */
export declare function csrfTokenToMint(req: Request, cookies: Record<string, string>): string | null;
/** The `Set-Cookie` value for a minted token. Readable by script, as double-submit requires. */
export declare function csrfCookieHeader(token: string, secure: boolean): string;
export declare function buildDynamicRouteRegexes(fileRouteBase: string): RegExp[];
/**
 * Rank a dynamic route file by specificity so the resolver can order candidates
 * most-specific-first and never let a catch-all (`[...x]`) or a broad `[param]`
 * shadow a more specific route (stacksjs/stx#1837).
 *
 * `discoverFiles` returns Bun glob order — where the catch-all frequently lands
 * first — and `getRoute` takes the FIRST regex match. Without ordering, `/foo/15`
 * matched `[...all].stx` (`^(.+)$`) before `foo/[id].stx`, so every dynamic
 * detail route 404'd. Higher score = more specific = tried first:
 *   - static segment       → +100   (strongly preferred)
 *   - `[param]` segment     →   +1   (weakly preferred)
 *   - `[...rest]` catch-all → -10000 (always last)
 */
export declare function routeSpecificity(fileRouteBase: string): number;
/**
 * True when a request path is for a STATIC ASSET (a non-page file extension like
 * `.jpg`/`.css`/`.js`) rather than a page. Used so a catch-all page can never
 * shadow an asset request that publicDir should serve — `getRoute` runs before
 * the publicDir handler (stacksjs/stx#1841). Page extensions (`.stx`/`.md`/
 * `.html`) return false; those are routable.
 */
export declare function isStaticAssetPath(requestPath: string): boolean;
/**
 * Does a file actually exist under `publicDir` for this request path?
 *
 * The extension test above is a guess about intent, and it is the wrong
 * question to ask before dropping a catch-all: an app whose catch-all
 * legitimately serves paths that carry extensions - a file browser, a docs
 * site addressing `guide.md`, anything rendering a repository - has every
 * such page refused, because the guess says "asset" and the only route that
 * could answer is the one being dropped.
 *
 * Asking the disk instead keeps what stacksjs/stx#1841 was protecting (a real
 * `public/images/logo.jpg` still wins over `[...all].stx`) and costs one stat
 * on a path that was going to be looked up moments later anyway.
 *
 * Traversal is normalized before the prefix check, the same way the publicDir
 * handler does it, so `..` cannot walk out of the root and report on a file
 * that is none of the caller's business.
 */
export declare function publicFileExists(requestPath: string, publicDir: string): boolean;
/**
 * Are we serving in production? In production the built-in 404 must not
 * enumerate the app's route list (information disclosure) and must not
 * inject the HMR client.
 *
 * Reuses the standard Stacks/Node signals — `NODE_ENV` / `APP_ENV`. serve.ts
 * has no pre-existing prod/dev flag threaded through its options, so these
 * env vars are the canonical signal (the same ones the wider stacks codebase
 * keys production behaviour off of).
 *
 * Safe by default: the browsable route list is a development-only affordance,
 * so we only treat a serve as development when it is EXPLICITLY marked so
 * (`development`/`dev`/`local`/`test`). A served app with no env configured —
 * the easy-to-hit misconfiguration — is therefore treated as production and
 * does NOT leak its route list. Local `buddy dev` already runs with
 * `NODE_ENV=development`, so it keeps the helpful list.
 */
export declare function isProductionServe(): boolean;
/**
 * `Cache-Control` for a file served straight out of `publicDir`.
 *
 * Development says `no-store`, so a swapped favicon or hero image appears on
 * the next reload rather than an hour later.
 *
 * Production does not: this server IS production for a server-rendered deploy,
 * with no CDN in front stamping cache headers on the way past. Sending
 * `no-store` there told every browser, proxy and link-preview crawler to
 * re-fetch every image on every request, and made messengers that cache a
 * preview by its headers throw the card away.
 *
 * An hour for ordinary assets, because they are replaced in place by a deploy
 * and a share card that changed with a copy edit should not be stale for a
 * year. A fingerprinted name (a content hash in it) can never change under a
 * given URL, so it gets the long immutable lifetime.
 */
export declare function staticCacheControl(pathname: string, production?: boolean): string;
/**
 * Render the built-in fallback 404 page.
 *
 * - In development (`isProduction: false`) it lists the discovered routes as
 *   clickable links — a genuinely useful dev affordance — and reflects the
 *   requested path (HTML-escaped).
 * - In production (`isProduction: true`) it renders a clean, neutral, self-
 *   contained page with NO route list and NO reflected path, so nothing about
 *   the app's internal structure leaks to anonymous visitors.
 *
 * The page is a complete HTML document, styled inline (system font stack,
 * centered, light + dark via `prefers-color-scheme`, no external assets).
 * The caller is responsible for HMR injection (dev only) and the 404 status.
 */
export declare function render404Page(opts: {
  path: string
  routes?: string[]
  isProduction: boolean
}): string;
/**
 * A cache that forgets its coldest entry rather than growing forever.
 *
 * A plain `Map` iterates in insertion order, so deleting and re-inserting a key
 * on every read moves it to the end - which makes the first key the least
 * recently used one, and the whole of an LRU three lines long.
 *
 * Exported because the behaviour is worth testing without standing a server
 * up, the same reason `isRenderableCacheCandidate` is.
 */
export declare function boundedCache<T>(limit: number): {
  read: (key: string) => T | undefined
  remember: (key: string, value: T) => T
  clear: () => void
  readonly size: number
};
export declare function resolveServeOpenUrl(port: number, openPath?: string): string;
/**
 * Did rendering fail?
 *
 * processDirectives swallows a template error and returns an HTML comment as
 * the entire document. That was then served with the page's own status — 200 —
 * so a broken page looked healthy to every uptime check, CDN and browser cache
 * that saw it, and the only evidence was a comment in a blank page
 * (stacksjs/stx#1854).
 *
 * Both other stx servers already get this right: production-server.ts looks up
 * a /500 route and dev-server/serve-app.ts calls renderErrorPage(500).
 */
export declare function isRenderFailure(html: string): boolean;
export declare function isRenderableCacheCandidate(html: string): boolean;
/**
 * A rendered /500 page is usable as an error body only if it exists and did not
 * ITSELF fail to render — otherwise serving it swaps one blank failure comment
 * for another. Returns the page to serve, or null to fall through to the next
 * candidate / the marker body (#1854).
 */
export declare function usableErrorPage(rendered: string | null): string | null;
export declare function bundleBrowserAsset(entrypoint: string): Promise<Response>;
/**
 * Start the STX development server
 * @param options Server options with patterns and port
 */
export declare function serve(options: ServeOptions): Promise<void>;
/**
 * The cookie name a double-submit CSRF check reads.
 *
 * Spelled here rather than imported, because stx does not depend on whatever
 * framework is doing the checking - it only has to agree on the name, and this
 * is the name every double-submit implementation in this ecosystem uses.
 */
export declare const CSRF_COOKIE: 'X-CSRF-Token';
/**
 * Build the candidate regexes for a dynamic route file (stacksjs/stx#1927).
 *
 * `fileRouteBase` is the route path with the file extension already
 * stripped (e.g. `judges/[id]/profile/index`). Returns one regex per
 * acceptable URL shape:
 *   - the literal path with `[param]` → `([^/]+)`
 *   - the same with a trailing `/index` removed, so
 *     `judges/[id]/profile/index` also matches `judges/35/profile`
 *     (without this, nested dynamic routes 404 on hard reload)
 *   - both of the above again with a leading `pages/` stripped, for
 *     projects that nest routable views under `pages/`
 */
/**
 * Snapshot of the in-flight request, threaded from the fetch handler down to
 * the `<script server>` render (stacksjs/stacks#1967).
 *
 * The module-level `activeServe*` singletons are NOT safe to read at render
 * time: a render can suspend at an `await` (onRequest hooks, DB queries in
 * server scripts) while a concurrent request — the HMR EventSource opens on
 * every page load — runs its own handler and resets the singletons in its
 * `finally`. Threading an immutable per-request snapshot removes that race;
 * the singletons remain only as a fallback for legacy call sites.
 */
export declare interface ServeRequestContext {
  url: string
  path: string
  search: string
  host: string
  cookieHeader: string
  cookies: Record<string, string>
  ip: string
  locale: string | null
  params: Record<string, string>
  method: string
  request?: Request
  responseStatus?: number
  responseHeaders?: Record<string, string>
  actionRedirect?: string
  actionCookies?: string[]
  [key: string]: unknown
}
export declare interface ServeOptions {
  patterns: string[]
  port?: number
  openPath?: string
  componentsDir?: string
  layoutsDir?: string
  fallbackLayoutsDir?: string
  fallbackComponentsDir?: string
  partialsDir?: string
  watchDirs?: string[]
  renderCache?: boolean
  renderCacheVary?: 'request' | 'source'
  crosswindCacheLimit?: number
  prewarmRenderCache?: boolean | number
  publicDir?: string
  quiet?: boolean
  autoIncrementPort?: boolean | number
  reusePort?: boolean
  stxModule?: typeof import('@stacksjs/stx') | Promise<typeof import('@stacksjs/stx')>
  i18n?: import('@stacksjs/stx').ResolvedI18n
  site?: import('@stacksjs/stx').SiteConfig
  routes?: Record<string, (req: Request) => Response | Promise<Response>>
  onRequest?: (req: Request) =>
  | Response
  | Record<string, unknown>
  | null
  | undefined
  | Promise<Response | Record<string, unknown> | null | undefined>
  onResponse?: (req: Request, response: Response) =>
  | Response
  | null
  | undefined
  | Promise<Response | null | undefined>
  middleware?: Record<string, MiddlewareHandler>
  globalMiddleware?: string[]
  middlewareGroups?: Record<string, string[]>
  auth?: false | {
    cookieName?: string
    redirectTo?: string
    home?: string
    protectedPaths?: string[]
  }
}
export declare interface MiddlewareContext {
  path: string
  url: URL
  params: Record<string, string>
  cookies: Record<string, string>
  redirect: (to: string, status?: number) => Response
}
/**
 * The slice of Crosswind this server calls, taken from the package's own types
 * rather than restated here.
 *
 * `CSSGenerator` has to be a constructor type, because it is `new`-ed below.
 * Widening it to `unknown` satisfies the no-explicit-any rule and still fails to
 * compile (`new (unknown)` is TS18046) — that is how d84349dd74 turned main red.
 * Restating the shape by hand is the other trap: a stale hand-written copy is
 * what made this hard to see in the first place (see the deleted
 * `cwcss-crosswind.d.ts`). `typeof import` cannot drift from the real engine.
 */
declare type CrosswindEngine = Pick<typeof import('@cwcss/crosswind'), 'CSSGenerator' | 'config'>;
/**
 * Middleware handler — a Laravel-style gate that either passes through
 * (returns `void`/`null`/`undefined`) or terminates the pipeline by
 * returning a `Response`.
 *
 * The third argument is the colon-separated arg list, so a page that
 * declares `middleware: ['auth:admin']` invokes the `auth` handler
 * with `args = ['admin']` — the same shape as Laravel's
 * `handle($request, $next, ...$args)`.
 */
export type MiddlewareHandler = (
  req: Request,
  ctx: MiddlewareContext,
  ...args: string[]
) => Response | null | undefined | void | Promise<Response | null | undefined | void>;