Agent guide for writing stx

A prescriptive guide for AI coding agents writing .stx files, produced by auditing a real production app (bughq, stx 0.2.113) against the framework surface it was failing to use.

The twelve chapters are posted as comments below. Each rule is written as RULE → WHY (with framework file:line) → WRONG (real code) → RIGHT → CHECK (a runnable command).

Why this exists

bughq is ~6,500 lines of stx written largely by AI agents. It works. It is also, structurally, an app that never switched the framework on:

The root cause is one line of the framework:

// process.js:311
const hasDoctype = /<!DOCTYPE\s/i.test(output), hasSections = /@section\s*\(/.test(output)
if (!hasDoctype || hasSections) {   // ← a doctype opts the page out of layouts entirely

Every page that writes its own document silently disables layout resolution, which disables runtime head config, which is why useHead/useSeoMeta cannot work on those pages, which is why the shell is duplicated 24 times, which is why the app/marketing boundary exists, which is why interceptAllLinks: true is load-bearing. One regex, the whole architecture downstream of it.

A companion RFC covering the framework-side changes is filed separately.

The rules

Rule 10 needs saying out loud

A .stx script block is compiled as TypeScript whether or not you type it — shouldTranspileTypeScript() (utils.js:28-33) returns true unless the block is tagged lang="js", and server blocks go through new Bun.Transpiler({ loader: 'ts' }) (variable-extractor.js:218).

So there is no "JavaScript phase" of an stx codebase and no migration to schedule. There is only typed TypeScript and untyped TypeScript — and untyped TypeScript is strictly worse than JavaScript, because it pays the cost of a compiler and delivers none of the guarantee. Annotate as you write, not in a later pass.

The audited app had 12 annotations across 123 functions, leaving ~58 of 70 parameters implicitly any. It was described as TypeScript throughout.

Know what annotations are worth right now: nothing verifies them. tsc --noEmit cannot see inside .stx files. Verified by putting const x: number = 'a string' in a client block — tsc silent, page renders 200, linter silent. Three gates, none caught it. That is an argument for fixing the toolchain, not for skipping types, but it does mean a wrong annotation is a real defect rather than something a compiler catches. The framework's own useLocalStorage declares : void while returning a ref (#1795) — that is what unchecked types decay into.

Two auto-import consequences that will bite:

• Only import type is ever acceptable, and only for types. Auto-imported symbols have ambient declarations in dist/stx.d.ts.
• Never write the generic form at a client call site. Detection matches \b<symbol>\s*\( (client-script.js:315), so useLocalStorage<string>(…) puts a < where the ( must be — the symbol is never detected and you get a ReferenceError. Annotate the destination instead.

Verification

Errata: several chapters say @extends/@section/@yield are used zero times. Precisely: zero times in pages. The two layout files do define slots (layouts/default.stx:39,42,44, layouts/marketing.stx:6,7,11,12,13) that nothing fills.

Chapters

1. Project topology and configuration
2. Page anatomy — never write a document
3. Layouts and the application shell
4. Head, SEO and structured data
5. Server blocks and the server-to-client bridge
6. State: signals, stores and composables
7. Templates: directives and bindings
8. No vanilla JS — the strict-mode mandate
9. Navigation and routing
10. Components
11. Styling with Crosswind, and TypeScript
12. Verification and enforcement

Correction (post-filing)

Three figures in the table above were wrong when this issue was first published, and have been fixed:

Commands the corrected numbers come from:

grep -rho '<StxLink' resources/ | wc -l                    # 29
grep -rhoE '<a [^>]*href="/' resources/ | wc -l            # 276
grep -rl '<style>' resources/views resources/partials resources/components | wc -l   # 23

The conclusions are unchanged — if anything StxLink adoption is half what was reported. The chapter comments below were independently checked: 1,843 of 1,850 file:line citations resolve and are in range (99.6%).

1. Project topology and configuration

There is no index.html in this project and there must never be one. config/ui.ts is the application root: it declares where pages, layouts, components, partials and stores live, and app.head is the only document <head> stx generates (process.js:205-233 → document-shell.js:101-105). Every rule in this chapter is about making that declaration true — because today three of the five keys config/ui.ts sets resolve to directories that do not exist, and the app only boots because two different servers pass overrides on top.

The two config loaders (read this before touching config/ui.ts)

config/ui.ts is loaded twice, by two different loaders, with different semantics. Every topology bug in bughq is a consequence of not knowing this.

A relative directory value cannot be correct in both loaders unless root is '.' or the value is absolute. Verified by running both against this repo:

config/ui.ts value: componentsDir: 'resources/components'
  Loader B (serve): "resources/components"           EXISTS
  Loader A (build): "resources/resources/components" MISSING

Directory option inventory

Every path-bearing key in StxConfig, its default, what it resolves against, and bughq's current state.

Non-configurable, hardcoded paths you cannot move: resources/assets (serve.js:9305), config/stx.ts for loadStxPartialsDir (@stacksjs/buddy/dist/production-server.js:70-75 — bughq's file is config/ui.ts, so this lookup always returns undefined), and the components directory the dev/prod servers force (@stacksjs/actions/dist/dev/views.js:71, production-server.js:121).

1.1 MUST pin root and pagesDir explicitly

RULE. config/ui.ts must declare root: '.' and pagesDir: 'resources/views'. Never let stx infer them.

WHY. resolveStxRoot (config.js:363-374) returns early only when you supply root:

// config.js:363-374
function resolveStxRoot(configRoot, configPagesDir) {
  const defaultPagesDir = configPagesDir || "pages";
  if (configRoot) return { root: configRoot, pagesDir: defaultPagesDir };
  const resourcesViews = path.join(process.cwd(), "resources", "views"),
        resourcesLayouts = path.join(process.cwd(), "resources", "layouts");
  if (fs.existsSync(resourcesViews) && fs.existsSync(resourcesLayouts))
    return { root: "resources", pagesDir: "views" };
  ...
  return { root: ".", pagesDir: defaultPagesDir };
}

Otherwise the shape of the project is decided by fs.existsSync on two directories. In bughq, resources/layouts/ is empty (0 files, created 23 Jul) and is the sole reason root resolves to 'resources' rather than '.'. root then propagates into: the three-directory prefixing at config.js:411-419, the SSG entry pages dir at build.js:10 (path.join(config.root || '.', config.pagesDir || ...)), the store directory at store-loader.js:11, and the component convention fallbacks at utils.js:334-338. Deleting one empty directory silently changes all four.

WRONG — config/ui.ts:8-16. No root, no pagesDir:

export default {
  // Components directory - for user-defined components
  componentsDir: 'resources/components',
  // Layouts directory - for layout templates
  layoutsDir: 'resources/layouts',
  // Partials directory - for partial templates
  partialsDir: 'resources/partials',

RIGHT:

export default {
  root: '.',
  pagesDir: 'resources/views',

CHECK.

grep -qE "^\s*root:\s*'\.'" config/ui.ts && grep -qE "^\s*pagesDir:" config/ui.ts \
  || echo "VIOLATION: root/pagesDir are being inferred from directory existence"

1.2 MUST write the three template directories project-root-relative under root: '.'

RULE. With root: '.', write componentsDir, layoutsDir and partialsDir as paths from the project root (resources/components, …). Do not set root: 'resources' and shorten them, and do not leave root inferred.

WHY. config.js:411-419 prefixes all three with root unless the value is absolute:

if (loaded.root && loaded.root !== ".") {
  const rootPrefix = loaded.root;
  if (loaded.partialsDir && !path.isAbsolute(loaded.partialsDir))
    loaded.partialsDir = path.join(rootPrefix, loaded.partialsDir);
  ...
}

Loader B does none of this. root: '.' makes the if false, so both loaders see identical, existing paths — the only relative arrangement that satisfies both (verified: root: 'resources' + layoutsDir: 'layouts' gives Loader A resources/layouts EXISTS and Loader B layouts MISSING).

The current values break real code paths, not hypothetical ones: includes.js:480-508 resolvePath() has no fallback, so /var/www/reviewos-reviewos/releases/69385e0/resources/components/IssueThread.stx:107:568: include error: Error loading include file SiteNav: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteNav.stx' ╭──────────────────────────────────────────────────────────────╮ │  ERROR  Include Error │ ╰──────────────────────────────────────────────────────────────╯ File: IssueThread.stx (line 107, col 568) Message: Error loading include file SiteNav: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteNav.stx' Context:  105: loaded.partialsDir = path.join(rootPrefix, loaded.partialsDir); 106: ... > 107: }

Loader B does none of this. root: '.' makes the if false, so both loaders see identical, existing paths — the only relative arrangement that satisfies both (verified: root: 'resources' + layoutsDir: 'layouts' gives Loader A resources/layouts EXISTS and Loader B layouts MISSING).

The current values break real code paths, not hypothetical ones: includes.js:480-508 resolvePath() has no fallback, so /var/www/reviewos-reviewos/releases/69385e0/resources/components/IssueThread.stx:113:632: include error: Error loading include file SiteNav: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteNav.stx' ╭──────────────────────────────────────────────────────────────╮ │  ERROR  Include Error │ ╰──────────────────────────────────────────────────────────────╯ File: IssueThread.stx (line 113, col 632) Message: Error loading include file SiteNav: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteNav.stx' Context:  111: ENOENT: no such file or directory, open '.../resources/resources/partials/SiteNav.stx'

That absolute path and the ANSI escape codes that follow it are page content in the built artifact.

WRONG — config/ui.ts:10,13,16 (values above). RIGHT:

  componentsDir: 'resources/components',
  112:   layoutsDir: 'resources/layouts',
> 113:   partialsDir: 'resources/partials',

— identical text, but now correct because root: '.' is pinned (1.1). The values are only meaningful together with root.

CHECK. Save as scripts/check-stx-topology.ts and wire it into CI:

import fs from 'node:fs'
  114: import path from 'node:path'
  115: 
 resolves against resources/resources/partials and returns an error string; process.js:328-331 looks for resources/resources/layouts/default.stx, does not find it, and applies no layout at all — no <main>, so stx-router/dist/client.js:796 (if (!getContainer()) return false) makes the SPA router inert. The evidence is on disk in dist/:
$ grep -rl 'include error' dist/ | wc -l
  108: 24
  109: $ head -c 260 dist/layouts/marketing.html | tail -c 120
 resolves against resources/resources/partials and returns an error string; process.js:328-331 looks for resources/resources/layouts/default.stx, does not find it, and applies no layout at all — no <main>, so stx-router/dist/client.js:796 (if (!getContainer()) return false) makes the SPA router inert. The evidence is on disk in dist/:
$ grep -rl 'include error' dist/ | wc -l
24
$ head -c 260 dist/layouts/marketing.html | tail -c 120
<body> .../resources/views/layouts/marketing.stx:10:5: include error: Error loading include file SiteNav:
ENOENT: no such file or directory, open '.../resources/resources/partials/SiteNav.stx'
That absolute path and the ANSI escape codes that follow it are page content in the built artifact.
WRONG — config/ui.ts:10,13,16 (values above). RIGHT:
  componentsDir: 'resources/components',
  layoutsDir: 'resources/layouts',
  partialsDir: 'resources/partials',
— identical text, but now correct because root: '.' is pinned (1.1). The values are only meaningful together with root.
CHECK. Save as scripts/check-stx-topology.ts and wire it into CI:
import fs from 'node:fs'
import path from 'node:path'

const KEYS = ['componentsDir', 'layoutsDir', 'partialsDir'] as const

const { loadConfig } = await import('bunfig')
const raw: any = await loadConfig({ name: 'stx', alias: ['ui'], cwd: process.cwd(), defaultConfig: {}, checkEnv: false, verbose: false })
const served = Object.fromEntries(KEYS.map(k => [k, raw[k]])) as Record<string, string>

const { loadStxConfig } = await import('@stacksjs/stx')
const res: any = await loadStxConfig()

let bad = 0
for (const k of KEYS) {
  if (served[k] !== res[k]) { console.error(`${k}: serve sees ${JSON.stringify(served[k])}, build sees ${JSON.stringify(res[k])}`); bad++ }
  else if (!fs.existsSync(res[k])) { console.error(`${k} -> ${res[k]} does not exist`); bad++ }
}
const pages = path.resolve(res.root === '.' ? '.' : res.root, res.pagesDir)
if (!fs.existsSync(pages)) { console.error(`pagesDir -> ${pages} does not exist`); bad++ }
for (const d of ['layouts', 'components', 'partials', 'stores'])
  if (fs.existsSync(path.join(pages, d))) { console.error(`${d}/ is inside pagesDir and therefore routable`); bad++ }
process.exit(bad ? 1 : 0)
Copying the served values before calling loadStxConfig is required — loadStxConfig mutates the object bunfig caches, so reading raw[k] afterwards silently reports the mutated value. Current output:
componentsDir: serve sees "resources/components", build sees "resources/resources/components"
layoutsDir:    serve sees "resources/layouts",    build sees "resources/resources/layouts"
partialsDir:   serve sees "resources/partials",   build sees "resources/resources/partials"
layouts/ is inside pagesDir and therefore routable
components/ is inside pagesDir and therefore routable
1.3 MUST NOT let an empty directory carry meaning
RULE. Every declared directory must contain the files it claims to contain. An empty directory in resources/ is a defect, not a placeholder.
WHY. resources/layouts/ is empty and is load-bearing in two opposite directions at once. Its existence flips resolveStxRoot to root: 'resources' (config.js:367-369), which causes 1.2's double prefix. Its emptiness is why the dev server picks the other directory: @stacksjs/actions/dist/dev/views.js:59-62 calls firstExistingPath(['resources/views/layouts', 'resources/layouts']), and views.js:115-126 prefers whichever candidate actually globs **/*.stx. Drop one .stx file into resources/layouts/ and both candidates qualify; the resolution then depends on array order. Production disagrees with dev already: @stacksjs/buddy/dist/production-server.js:114 uses existsSync('resources/views/layouts') ? 'resources/views/layouts' : 'resources/layouts' — presence, not content.
WRONG:
$ ls -la resources/layouts/
total 0
drwxr-xr-x  2 ...  64 Jul 23 20:31 .
RIGHT. Move the real layouts in and delete the old directory, so firstExistingPath, existsSync and config/ui.ts all name the same place:
git mv resources/views/layouts/default.stx   resources/layouts/default.stx
git mv resources/views/layouts/marketing.stx resources/layouts/marketing.stx
rmdir resources/views/layouts
CHECK.
find resources -type d -empty -not -path '*/node_modules/*' | grep . \
  && echo "VIOLATION: empty directory in resources/ — it is deciding config resolution"
1.4 MUST keep layouts, components, partials and stores outside pagesDir
RULE. Nothing under pagesDir may be a non-page. A file under resources/views/ is a public URL.
WHY. Route discovery is directory-driven. The exclusion of components/layouts/partials exists in three places and is missing from three others:
Path
Excludes non-page dirs?
Evidence
dev/prod serve file discovery
Yes
serve.js:9263-9273
.stx/routes.ts manifest
Yes
stx-router/dist/codegen.js:24
buildForProduction
Yes
production-builder.js:62
.stx/route-types.d.ts
No
codegen.js:3-22 — no filter
stx-router Router constructor
No
file-router.js:41-58
SSG generateStaticSite
No
ssg.d.ts:24-43 — SSGConfig has no componentsDir/layoutsDir/partialsDir key at all
Consequences already shipped into the build output and the generated types:
$ ls dist/layouts dist/components
dist/components:  FeatureCard.html
dist/layouts:     default.html  marketing.html
$ grep -o '<loc>[^<]*</loc>' dist/sitemap.xml | grep -E 'layouts|components'
<loc>http://localhost/components/FeatureCard</loc>
<loc>http://localhost/layouts/default</loc>
<loc>http://localhost/layouts/marketing</loc>
$ grep -n 'layouts\|components' .stx/route-types.d.ts
15:    '/components/FeatureCard': {  }
25:    '/layouts/default': {  }
26:    '/layouts/marketing': {  }
/layouts/marketing is the page whose <body> is the absolute-filesystem-path dump quoted in 1.2. It is sitemapped.
WRONG: resources/views/layouts/default.stx, resources/views/layouts/marketing.stx, resources/views/components/FeatureCard.stx.
RIGHT: resources/layouts/default.stx, resources/layouts/marketing.stx, resources/components/FeatureCard.stx (or delete FeatureCard.stx — it has zero references in resources/ or routes/).
Related, and worth knowing before you add a page: the dev server mounts the framework defaults as a second pages root — views.js:69 passes patterns: ['resources/views', 'storage/framework/defaults/resources/views']. Nine routes you did not write are live and in .stx/routes.ts: /cart, /coming-soon, /checkout/contact, /checkout/payment, /checkout/shipping, /dashboard/custom-page, /emails/welcome, /errors/tester, /orders/:id. Creating resources/views/cart.stx shadows the default (first pattern wins, file-router.js:45-48); creating a page that collides with one you did not intend to own is a silent behaviour change.
CHECK. Part of the 1.2 script; standalone form:
ls resources/views/layouts resources/views/components resources/views/partials resources/views/stores 2>/dev/null \
  && echo "VIOLATION: non-page directory inside pagesDir"
grep -nE "'/(layouts|components|partials)/" .stx/route-types.d.ts \
  && echo "VIOLATION: non-page templates typed as routes"
1.5 MUST only put load-bearing config in keys the serve path forwards
RULE. Before adding a key to config/ui.ts, confirm it reaches the renderer. The dev and production request paths forward a fixed allow-list and drop everything else.
WHY. serve.js:9508-9528 (and its twin at serve.js:9690-9708) rebuilds the render options from scratch:
const config5 = {
  ...defaultConfig4,                 // stx defaultConfig — config.js:16-24
  root: process19.cwd(),             // your `root` is discarded here
  ...componentsDir && { componentsDir },   // from options (views.js:71) — hardcoded
  ...layoutsDir && { layoutsDir },         // from options (views.js:72)
  ...partialsDir && { partialsDir },       // from options (views.js:73)
  autoShell: true,
  ssr: stxConfig.ssr ?? defaultStxConfig.ssr ?? true,
  app: stxConfig.app || {},
  ..."strict" in stxConfig && { strict: stxConfig.strict },
  ..."router" in stxConfig && { router: stxConfig.router },
  ..."debug" in stxConfig && { debug: stxConfig.debug },
  ..."skipDefaultSeoTags" in stxConfig && { skipDefaultSeoTags: stxConfig.skipDefaultSeoTags },
  ..."defaultTitle" / "defaultDescription" / "defaultImage" / "seo" / "analytics" ...,
  ..."_pluginComponentDirs" / "_pluginPageDirs" ...
};
Directory precedence is options.X ?? stxConfig.X ?? defaultStxConfig.X (serve.js:8935-8937) — options always win, and views.js:68-73 / production-server.js:121-123 always pass them. The three keys config/ui.ts sets today are exactly the three that are always overridden. The two that survive (router, app) are the two the file spends 60 lines documenting, which is correct; the ~30 that also survive are all unset.
Reaches the renderer
Silently dropped by the serve path
app, ssr, strict, router, debug, skipDefaultSeoTags, defaultTitle, defaultDescription, defaultImage, seo
defaultLayout, customDirectives, middleware, markdown, i18n, a11y, animation, loops, forms, csp, components, hydration, routeMiddleware, media, heatmap, pwa, story, streaming, webComponents, broadcasting, build, docs, cache, cachePath, templatesDir, skipSignalsRuntime, skipEventDirectives
analytics (also re-read via Loader A at serve.js:8929-8930)
publicDir (separate read, serve.js:8938)
plugins → _pluginComponentDirs / _pluginPageDirs (serve.js:8922-8928)
storesDir, css, root, pagesDir (via Loader A, not config5)
WRONG. Adding customDirectives or i18n to config/ui.ts and expecting it to apply in bun run dev.
RIGHT. Directive registration goes through plugins (config.js:445-460, addDirective), which is propagated.
CHECK.
grep -oE "^  [a-zA-Z_]+:" config/ui.ts | tr -d ' :' | grep -vxE \
 'root|pagesDir|componentsDir|layoutsDir|partialsDir|storesDir|publicDir|css|plugins|app|ssr|strict|router|debug|skipDefaultSeoTags|defaultTitle|defaultDescription|defaultImage|seo|analytics' \
 && echo "VIOLATION: key above is dropped by serve.js:9508-9528 — it has no runtime effect"
1.6 MUST NOT rely on defaultLayout, templatesDir, or shell
RULE. These three keys look configurable and are not. Do not set them; do not reason from them.
WHY.
defaultLayout (config-types.d.ts:276) appears nowhere in bun-plugin-stx/dist/serve.js. In the serve path it comes only from the spread of stx's defaultConfig (config.js:22 = "default"). Setting defaultLayout: 'app' in config/ui.ts changes stx build and changes nothing in dev or buddy serve. The layout file must be named default.stx.
templatesDir (:263) is read at exactly one site, docs.js:559, for doc generation. It has no rendering effect.
shell (: — StxConfig.shell?: string | false) drives detectShell (app-shell.js:17-30), which looks for app.stx in the project root. app-shell.d.ts marks it @deprecated Use layouts/default.stx instead, and neither bun-plugin-stx/dist/serve.js nor @stacksjs/actions/dist/dev/views.js calls detectShell at all. bughq has no app.stx and must not gain one.
CHECK.
grep -nE "^\s*(defaultLayout|templatesDir|shell):" config/ui.ts && echo "VIOLATION: inert key"
test -e app.stx && echo "VIOLATION: deprecated app.stx shell — use resources/layouts/default.stx"
test -e resources/layouts/default.stx || echo "VIOLATION: default layout must be named default.stx"
1.7 MUST put shared reactive state in storesDir. stx has no composablesDir
RULE. There is no composablesDir, functionsDir or composables/ convention anywhere in stx 0.2.113. Verified: grep -rn "composablesDir" node_modules/@stacksjs/ node_modules/bun-plugin-stx/ returns nothing. Composables (useDark, useCookie, useFetch, …) are auto-imported globals injected by the runtime — you never declare a directory for them and you never hand-import them (see the auto-imports chapter). Cross-page reactive state belongs in storesDir (config-types.d.ts:275), which is real and which bughq does not use.
WHY. store-loader.js:5-11 is the only resolver:
export async function getStoreScript(storesDir) {
  let resolvedDir;
  if (storesDir) resolvedDir = path.resolve(storesDir);
  else {
    const config = await loadStxConfig();
    resolvedDir = path.resolve(config.root || process.cwd(), config.storesDir || "stores");
  }
Note storesDir is resolved against root here, not prefixed at config.js:411-419 like the other three — a different mechanism for the same convention. In the serve path options.storesDir is undefined (it is not in the 1.5 allow-list), so the else branch always runs. With root: '.' and storesDir: 'resources/stores', that is <project>/resources/stores. The directory contract is strict: Bun.Glob("*.ts") — top level only, not recursive (store-loader.js:16); index.ts and types.ts are skipped (:19-20); every import line is stripped before transpile (:36), so a store must be self-contained. The result is inlined as <script data-stx-stores> by process.js:245-257.
WRONG — resources/functions/counter.ts:2 and resources/functions/dark.ts:4-5. These are stores in everything but location:
// resources/functions/counter.ts
export const count = state(0)
export function increment() { count.update((n: number) => n + 1) }
// resources/functions/dark.ts
export const isDark = useDark()
export const preferredDark = usePreferredDark()
resources/functions/ matches no stx convention, is referenced by zero .stx files (grep -rn "resources/functions" resources/ config/ → nothing), and is never loaded. Meanwhile the theme state it models is hand-reimplemented across the app.
RIGHT — move to resources/stores/ and declare it:
// resources/stores/theme.ts   (no imports — they are stripped)
export const isDark = useDark()
export const preferredDark = usePreferredDark()
export function toggleDark() { isDark.set(!isDark()) }
// config/ui.ts
  storesDir: 'resources/stores',
Verified end to end against getStoreScript(undefined) with this exact config: LOADED (105 bytes) → ;(function(){ // Store: theme … })();.
CHECK.
test -d resources/functions && echo "VIOLATION: resources/functions matches no stx convention — move to resources/stores"
grep -qE "^\s*storesDir:" config/ui.ts || echo "VIOLATION: storesDir undeclared"
find resources/stores -mindepth 2 -name '*.ts' | grep . && echo "VIOLATION: store-loader globs *.ts non-recursively"
grep -rn "^import " resources/stores/*.ts 2>/dev/null && echo "VIOLATION: imports are stripped at store-loader.js:36"
1.8 MUST make config/ui.ts typechecked
RULE. config/ui.ts ends in satisfies UiOptions (config/ui.ts:79) and that assertion is never evaluated. Fix tsconfig.json include so the config, the stores and the generated route types are covered.
WHY. stx is a TypeScript-first framework, and the config file is the one place where a typo costs you an entire subsystem. bun run typecheck (package.json → bun x tsc --noEmit) currently visits ten project files:
$ bun x tsc --listFilesOnly | grep -v node_modules
site.config.ts
types/stacks-app.d.ts
types/ts-cloud-augment.d.ts
app/Models/{AlertChannel,ErrorEvent,Issue,Project,Subscription,User}.ts
app/Support/urls.ts
tsconfig.json include is ["*.ts", "*.d.ts", "types/**/*.d.ts", "app/Models/**/*.ts", "app/Services/**/*.ts", "app/Support/**/*.ts"] — config/ and resources/ match nothing. .stx/route-types.d.ts (which declares module "stx/routes" with the full RouteMap) is likewise never loaded, so route patterns are untyped at every call site.
RIGHT — tsconfig.json:
  "include": [
    "*.ts",
    "*.d.ts",
    "types/**/*.d.ts",
    "config/**/*.ts",
    "resources/stores/**/*.ts",
    ".stx/route-types.d.ts",
    "app/Models/**/*.ts",
    "app/Services/**/*.ts",
    "app/Support/**/*.ts"
  ],
CHECK.
bun x tsc --listFilesOnly | grep -q 'config/ui.ts' || echo "VIOLATION: config/ui.ts is not typechecked"
1.9 MAY use _layout.stx co-location, but know it outranks the configured layout
RULE. A file named _layout.stx in any directory under pagesDir becomes the layout for every page at or below it. Use it for a route group; never add one casually.
WHY. process.js:313-327 walks up from the page's directory (max 20 levels) looking for _layout.stx before it ever consults layoutsDir/defaultLayout:
for (let i = 0; i < 20; i++) {
  const candidate = path.join(searchDir, "_layout.stx");
  if (await fileExists(candidate)) { autoLayoutPath = candidate; break }
  ...
}
if (autoLayoutPath) layoutPath = autoLayoutPath;
else if (opts.layoutsDir) { /* layoutsDir/${defaultLayout}.stx */ }
stx-router/dist/nested-layouts.js:3-14 builds the same chain for route metadata. Adding resources/views/compare/_layout.stx silently re-parents all eight /compare/* pages and no error is emitted.
CHECK. Manual review of every hit:
find resources/views -name '_layout.stx'
Each result must be intentional and documented in a comment at the top of the file naming the routes it captures.
1.10 The corrected config/ui.ts
Apply this verbatim after the file moves in 1.3/1.4. The existing comment blocks on router (config/ui.ts:18-40) and app.head (:45-73) are correct and must be preserved — they are elided here with /* … */ only for length; do not delete them.
import type { StxOptions as UiOptions } from '@stacksjs/stx'

/**
 * stx configuration — the root of this application. There is no index.html.
 *
 * This file is loaded TWICE, by loaders with different semantics:
 *
 *   A. @stacksjs/stx loadStxConfig()            (dist/config.js:387)
 *      → applies resolveStxRoot (config.js:363-374) and prefixes
 *        componentsDir/layoutsDir/partialsDir with `root` (config.js:411-419).
 *      → used by `stx build`, the SSG, production-builder, store-loader,
 *        and Crosswind config discovery.
 *
 *   B. bun-plugin-stx serve()                   (dist/serve.js:8912-8919)
 *      → raw bunfig load, NO root prefixing, defaults ssr:true.
 *      → used by `bun scripts/dev.ts` and `buddy serve` on every request.
 *
 * A relative directory value cannot be correct in both unless `root` is '.'.
 * That is why `root: '.'` is pinned below and every directory is written from
 * the project root. Verify with scripts/check-stx-topology.ts — it fails if the
 * two loaders disagree or any resolved path is missing.
 */
export default {
  // --- Project shape -------------------------------------------------------
  // Pinned, not inferred. Without `root`, resolveStxRoot (config.js:363-374)
  // decides the whole topology from `fs.existsSync('resources/layouts')` — an
  // empty directory would flip root to 'resources' and double-prefix the three
  // directories below into non-existent resources/resources/*.
  root: '.',

  // Every .stx under here is a public URL (stx-router file-router.js:41-58).
  // Nothing that is not a page may live in this tree: the SSG (ssg.d.ts:24-43)
  // and the route-type codegen (stx-router codegen.js:3-22) have no exclusion,
  // so a layout parked here is built to HTML and sitemapped.
  pagesDir: 'resources/views',

  // --- Template directories ------------------------------------------------
  // Root-relative because `root` is '.', which makes the config.js:411-419
  // prefix a no-op and both loaders agree.
  //
  // Caveat, verified not assumed: all three are OVERRIDDEN on the served path.
  // Dev passes them at @stacksjs/actions/dist/dev/views.js:68-73, prod at
  // @stacksjs/buddy/dist/production-server.js:116-123, and options win at
  // bun-plugin-stx/dist/serve.js:8935-8937. They are still declared here
  // because `stx build`, the SSG and production-builder read them directly.
  //
  // componentsDir in particular is force-set to the framework defaults tree by
  // views.js:71; bughq's own resources/components resolves only via the
  // convention fallback at @stacksjs/stx/dist/utils.js:334-338.
  componentsDir: 'resources/components',
  layoutsDir: 'resources/layouts',
  partialsDir: 'resources/partials',

  // Module-scope reactive state, inlined into every page as
  // <script data-stx-stores> (process.js:245-257). Resolved against `root` by
  // store-loader.js:11 — a different mechanism from the three keys above.
  // Contract: top-level *.ts only (non-recursive glob, store-loader.js:16),
  // index.ts/types.ts skipped, and all `import` lines stripped before
  // transpile (store-loader.js:36) — stores must be self-contained.
  storesDir: 'resources/stores',

  // Static root. Not passed by views.js, so this value actually reaches the
  // server (serve.js:8938). Declared so it stops being a hidden default.
  publicDir: 'public',

  // --- Rendering -----------------------------------------------------------
  // Explicit because the two loaders default it differently: stx's own
  // defaultConfig says false (config.js:18) while bun-plugin-stx says true
  // (serve.js:8833). The false side is what makes `stx build` pick SSG over SSR
  // (build.js:4-5). bughq is SSR; say so once, here.
  ssr: true,

  // Registers the ~35 shipped UI components by tag name — the ONLY code path
  // that fills _pluginComponentDirs (config.js:420-468). See the components
  // chapter. Boot log prints "[stx] Plugin loaded: @stacksjs/components".
  plugins: ['@stacksjs/components/stx-plugin'],

  // stx's built-in prohibited-DOM-API validator for client <script> blocks.
  // See the no-vanilla-JS chapter. Forwarded at serve.js:9517.
  strict: true,

  /* … existing router comment block, config/ui.ts:18-40, unchanged … */
  router: {
    container: 'main',
    interceptAllLinks: true,
  },

  /* … existing app.head comment block, config/ui.ts:45-73, unchanged … */
  app: {
    head: {
      title: 'bughq',
    },
  },
} satisfies UiOptions
satisfies UiOptions only does work once 1.8 lands. Two keys deliberately omitted here because they belong to later chapters but must eventually be set in this file: skipDefaultSeoTags (stx currently injects stx Project / A website built with stx templating engine into every page — see dist/compare/sentry.html:1) and analytics (config/analytics.ts:17-18 has a Fathom site ID that reaches nothing).
1.11 Apply order
The moves and the config edit are one atomic change; doing either half alone breaks the other.
git mv resources/views/layouts/*.stx resources/layouts/ and rmdir resources/views/layouts — satisfies 1.3 and 1.4 for layouts, and makes views.js:59-62 / production-server.js:114 agree with the config.
git mv resources/views/components/FeatureCard.stx resources/components/ (or git rm it — zero references) and rmdir resources/views/components.
Replace config/ui.ts with 1.10.
Extend tsconfig.json include per 1.8.
Add scripts/check-stx-topology.ts from 1.2 and run it — must exit 0.
rm -rf dist .stx && bun run dev, then re-run step 5 and confirm grep -rn "'/\(layouts\|components\)/" .stx/route-types.d.ts is empty and grep -rl 'include error' dist/ returns nothing.

2. Page anatomy — never write a document

A .stx file under resources/views/ is a fragment. It contributes markup to a document that stx assembles. It never is the document. Every rule in this chapter follows from one line of the framework:

// node_modules/@stacksjs/stx/dist/process.js:310-312
if (!layoutPath && !hasNoLayout && opts.defaultLayout) {
  const hasDoctype = /<!DOCTYPE\s/i.test(output), hasSections = /@section\s*\(/.test(output);
  if (!hasDoctype || hasSections) {

Writing <!DOCTYPE html> in a page turns off layout resolution for that page. Silently. No warning, no log line. bughq has 24 files that do this (grep -rl '<!DOCTYPE' resources/views → 24), and the entire marketing site's structural debt — 357 lines of duplicated shell, a dead layout, 8 data-no-router escape hatches, zero useSeoMeta calls — is downstream of that one regex.

The pipeline you are writing into

Note that priority 3 makes layouts/marketing.stx:7's <title>@yield('title')</title> redundant even on its own terms — @section('title', '…') already feeds the shell. Delete the string-slot head; do not port it.

WRONG — resources/views/compare/sentry.stx:6-7 (and 23 siblings):

    <title>bughq vs Sentry - bughq</title>
    <meta name="description" content="How bughq, an open-source error tracker you self-host on Postgres, compares to Sentry, the incumbent error platform.">

RIGHT:

<script server>
useSeoMeta({
  title: 'bughq vs Sentry - bughq',
  description: 'How bughq, an open-source error tracker you self-host on Postgres, compares to Sentry, the incumbent error platform.',
  canonical: 'https://bughq.org/compare/sentry',
})
</script>

CHECK.

grep -rn '<title>\|<meta name="description"' resources/views   # must return nothing
grep -rc 'link rel="stylesheet"' resources/views | grep -v ':0' # must return nothing

Currently 24 files declare <title>; 34 declare a stylesheet <link>.

2.7 MUST route page-local CSS through @push('styles') → @stack('styles'), never a bare <style>

WHY. There is a safety net and it puts your CSS in the wrong place. process.js:372-385 hoists orphan <script>/<style> tags into sections.content when a layout applies — i.e. into <body>, after the content, in a fragment the SPA router will swap away. @push avoids this entirely: process.js:299 harvests pushes into stacks before sections are collected (so @push may sit anywhere, including inside @section), process.js:423 merges the layout's own pushes into the same object, and process.js:444 fills @stack. Because the layout's @stack('styles') sits inside raw block (context.__stx_head_raw, head.js:199-206) → @section('title', '…') (context.__sections.title) → config app.head.title (config/ui.ts:76) → 'stx App' (document-shell.js:13)

link and meta arrays are concatenated, not replaced (process.js:216-218), and injectConfigHeadTags dedupes links by exact href= (document-shell.js:79-80) and metas by name/property/charset/http-equiv (document-shell.js:73-75). So config-level assets are safe to declare unconditionally.

Page-local <style> must go through @push/@stack (includes.js:722-732), not sit loose in the template: when a layout applies, process.js:373-384 sweeps every orphan <script>/<style> out of the page and appends it to sections.content — i.e. into the body, after the content, not the head.

WRONG — the same four <link> tags appear in 34 of 36 page files. resources/views/index.stx:37-40, compare/sentry.stx:8-11, pricing.stx:38-40, and 31 more:

    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Space+Grotesk…">
    <link rel="stylesheet" href="/marketing.css">

…while config/ui.ts:74-78 declares only { title: 'bughq' }.

RIGHT — config/ui.ts:

app: {
  head: {
    title: 'bughq',
    lang: 'en',
    link: [
      { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
      { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' },
      { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap' },
    ],
  },
},

and the page:

<script server>
useHead({ title: 'bughq vs Sentry - bughq' })
</script>
@extends('marketing')

CHECK.

grep -rn "fonts.googleapis.com\|<link rel=" resources/views --include="*.stx"   # must be empty
grep -rn "<style" resources/views --include="*.stx" | grep -v "@push"           # must be empty

Currently 92 duplicated <link> lines across 23 heads, and 20 files with a loose <style>.

3.7 MUST: one layout file per chrome group, and the filename is the routing group

WHY. deriveLayoutGroup (node_modules/stx-router/dist/layout-metadata.js:1-6) takes the path from the <!-- stx-layout: … --> marker, finds the last layouts segment, and returns the next segment with .stx stripped. client.js:230-237 reimplements the identical function browser-side. That string drives two decisions:

• checkLayoutChange (client.js:248-266): different group → return true at :255-258 → client.js:350-360 refetches the full document and client.js:596-607 swaps document.body.innerHTML, replacing nav, footer and all chrome. Different name within the same group → same full-body swap (client.js:261-263).
• client.js:568-580: the stylesheet/preconnect <link> reconciliation runs only on that full-document path, resolving hrefs against the target document's base URL (client.js:566-567).

So default.stx → group default, marketing.stx → group marketing. App→marketing and marketing→app both become correct full-body swaps. Today both surfaces report default (marketing by the serve.js:10121 fallback), so the router misclassifies the crossing as a same-layout fragment swap — and the asymmetric case is worse: marketing→app resolves curGroup via defaultLayoutGroup('') → 'app' (client.js:231) against the app page's 'default', firing a second full-page fetch on every marketing→/pricing, /login, /register click.

WRONG. Two document shells, zero layout metadata, one reported group.

RIGHT. Two sibling layouts under resources/layouts/. resources/layouts/marketing.stx, complete — note it has no DOCTYPE, no <head>, and calls @include for chrome exactly the way all 23 pages do today:

{{-- Marketing chrome. Group 'marketing': crossing to/from the app shell makes
     client.js:255 fire a full-document swap so nav and footer are replaced. --}}
@include('SiteNav')

<main>
@yield('content')
</main>

@include('SiteFooter')

@stack('scripts')

and resources/layouts/default.stx keeps its current body (resources/views/layouts/default.stx:38-44) with @yield('footer') deleted per rule 3.9.

CHECK.

# server-rendered metadata, dev server on :3100
curl -s localhost:3100/compare/sentry | grep -o 'name="stx-layout-group" content="[^"]*"'  # → marketing
curl -s localhost:3100/dashboard     | grep -o 'name="stx-layout-group" content="[^"]*"'  # → default
# fragment headers
curl -s -D- -o/dev/null -H 'X-STX-Router: true' localhost:3100/compare/sentry | grep -i x-stx-layout

3.8 MUST NOT: nest layouts (@extends inside a layout file) while relying on layout groups

WHY. This is a trap, not a style preference. process.js:405-421 detects an @extends in the layout file, merges the intermediate layout's sections, and recurses via processDirectives(nestedTemplate, …, layoutFullPath, …). That recursive call matches the base layout at process.js:305 and stamps <!-- stx-layout: base --> at process.js:447. The intermediate layout's name is discarded. So marketing.stx @extends('base') and default.stx @extends('base') both report group base — checkLayoutChange (client.js:255) sees no change, and you are back to unstyled fragment swaps with extra indirection.

Share the document through app.head (rule 3.6) and share markup through @include partials. Never through layout inheritance.

CHECK.

grep -rn "@extends(\|@layout(" resources/layouts/*.stx   # must return nothing

3.9 MUST: data-no-router survives only on links whose response is not an HTML page

WHY. client.js:793 honours data-stx-no-router and data-no-router, but only inside shouldIntercept, reachable only from the interceptAllLinks branch at client.js:809 (client.js:808 matches [data-stx-link] first and unconditionally — so data-no-router on an <StxLink> is silently ignored). There are exactly two legitimate reasons to opt out, and "my target page has a different <head>" is not one of them once rule 3.7 holds.

bughq's 12 occurrences split cleanly:

WRONG — resources/views/login.stx:113:

<a href="/" data-no-router class="wordmark text-2xl">bughq</a>

RIGHT.

<StxLink to="/" class="wordmark text-2xl">bughq</StxLink>

and, on the four that stay:

{{-- Server 302. Unconditional opt-out, not a shell artefact. --}}
<a href="/api/auth/github/redirect" data-no-router class="oauth-btn …">

Once every internal anchor is an <StxLink> (client.js:808 matches [data-stx-link] without interceptAllLinks), config/ui.ts:43 SHOULD flip to interceptAllLinks: false. Do not flip it before then: resources/partials/SiteNav.stx and SiteFooter.stx carry 64 plain anchors that depend on the flag.

CHECK.

grep -rn "data-no-router" resources/views --include="*.stx" | grep -v "/api/"   # must be empty

Currently 8 hits.

3.10 SHOULD: use _layout.stx for subtree chrome, and @nolayout for a page that genuinely owns its document

WHY. process.js:313-327 walks up to 20 parent directories from the page file looking for _layout.stx, bounded by path.dirname(opts.layoutsDir), and prefers it over the configured default layout (process.js:326-332). That is the Nuxt-style co-located shell: resources/views/issue/_layout.stx would wrap issue/[id].stx only. bughq has none. Use it when a subtree needs distinct chrome; do not use it to duplicate default.stx.

@nolayout (process.js:302-304, gated at :310) is the explicit opt-out. bughq uses it zero times; its 24 DOCTYPE pages opt out implicitly through process.js:311, which is why adding one @section( to any of them silently produces a nested document (rule 3.4).

CHECK. Manual review. A _layout.stx is correct only if it differs structurally from its nearest ancestor layout; diff them. grep -rn "@nolayout" resources should return only files that are deliberately standalone (an embed, an OG image renderer) — and per rule 3.1 such a page still must not write a DOCTYPE; it must let ensureDocumentShell build one.

3.11 MUST: every @yield and @stack in a layout is filled by at least one page

WHY. Unfilled slots fail silently. process.js:364-366 replaces an unmatched @yield with its default argument or the empty string; includes.js:727-729 renders an empty @stack as ''. No warning, no build error.

WRONG — resources/views/layouts/default.stx:42 @yield('footer') and :44 @stack('scripts'); resources/views/layouts/marketing.stx:12-13 the same pair. Not one page in bughq fills any of them — all 23 marketing pages call /var/www/reviewos-reviewos/releases/69385e0/resources/components/IssueThread.stx:670:404: include error: Error loading include file SiteFooter: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteFooter.stx' ╭──────────────────────────────────────────────────────────────╮ │  ERROR  Include Error │ ╰──────────────────────────────────────────────────────────────╯ File: IssueThread.stx (line 670, col 404) Message: Error loading include file SiteFooter: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteFooter.stx' Context:  668: projects/index.stx @extends('default') 669: projects/new.stx @extends('default') > 670: issue/[id].stx @extends('default')

Deleted: resources/views/layouts/, resources/views/components/FeatureCard.stx (zero references), and 7 of the 8 /compare/* files — they are byte-identical in tag+class skeleton and the canonical alternatives array already exists in resources/views/compare.stx:1-13, rendered with @foreach at compare.stx:52.

The matching config. All three directory keys are root-relative, because config.js:411-419 joins loaded.root onto each of partialsDir, componentsDir, layoutsDir — which is why the current absolute-looking values in config/ui.ts:10,13,16 become resources/resources/* and produce the include-error dump in dist/layouts/marketing.html:

export default {
  671:   root: 'resources',        // explicit — do not let config.js:363-374 infer it
  672:   pagesDir: 'views',
 inline instead. marketing.stx additionally offers no @stack('styles') despite 9 pages carrying a page-local <style> block.
RIGHT. Delete @yield('footer') and call 
/var/www/reviewos-reviewos/releases/69385e0/resources/components/IssueThread.stx:678:142: include error: Error loading include file SiteFooter: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteFooter.stx'

╭──────────────────────────────────────────────────────────────╮
│  ERROR  Include Error                                    │
╰──────────────────────────────────────────────────────────────╯

File: IssueThread.stx (line 678, col 142)
Message: Error loading include file SiteFooter: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteFooter.stx'

Context:
  676:   defaultLayout: 'default',
  677:   app: { head: { /* rule 3.6 */ } },
> 678:   router: { container: 'main', interceptAllLinks: false /* after rule 3.9 */ },
  679: } satisfies UiOptions

CHECK — one command that must pass before any .stx change is committed:

grep -rn "DOCTYPE\|<html[ >]" resources --include="*.stx"                       # empty
  680: find resources/views -name '*.stx' -exec grep -L "@extends(" {} +               # empty
 from the layout (rule 3.7). Add @stack('styles') to the layout only once a page uses @push('styles').
CHECK.
# every yield/stack name a layout declares must appear as a section/push in some page
comm -23 \
  <(grep -rhoE "@(yield|stack)\('([^']+)'" resources/layouts | grep -oE "'[^']+'" | tr -d "'" | sort -u) \
  <(grep -rhoE "@(section|push|prepend)\('([^']+)'" resources/views | grep -oE "'[^']+'" | tr -d "'" | sort -u)
# must print nothing
3.12 The file tree bughq must have
config/
  ui.ts                     # declares every directory below — the Nuxt-style manifest
resources/
  layouts/
    default.stx             # app + auth chrome → group 'default'
    marketing.stx           # marketing chrome  → group 'marketing'
  partials/
    SiteNav.stx             # 
/var/www/reviewos-reviewos/releases/69385e0/resources/components/IssueThread.stx:752:545: include error: Error loading include file SiteNav: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteNav.stx'

╭──────────────────────────────────────────────────────────────╮
│  ERROR  Include Error                                    │
╰──────────────────────────────────────────────────────────────╯

File: IssueThread.stx (line 752, col 545)
Message: Error loading include file SiteNav: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteNav.stx'

Context:
  750:         
  751: 
> 752:         
4. Head, SEO and structured data
Everything a page says about itself — <title>, description, canonical, og/twitter, robots, JSON-LD — is produced by exactly two mechanisms in stx 0.2.113: runtime head calls in a <script server> block, and app.head in config/ui.ts. Nothing else. bughq currently uses a third (24 hand-written <head> blocks) and a fourth (site.config.ts pages), and the result is 24 built pages that ship <title>stx Project</title>.
4.0 The title precedence chain (read this before writing any rule-breaking code)
process.js lines 205–226 are the entire mechanism. runtimeHead is context.__stx_runtime_head (what useHead/useSeoMeta write), pageHeadRaw is what  captured, sectionTitle is @section('title'), and baseHeadConfig is config/ui.ts app.head:
// node_modules/@stacksjs/stx/dist/process.js:206-215
  753: const baseHeadConfig = options.app?.head || {}, runtimeHead = (context.__stx_runtime_head || null) ?? getHeadStatic();
  754: let pageHeadRaw = (context.__stx_head_raw || "").trim(), pageHeadTitle;
   — already correct location
    SiteFooter.stx          # 
/var/www/reviewos-reviewos/releases/69385e0/resources/components/IssueThread.stx:756:197: include error: Error loading include file SiteFooter: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteFooter.stx'

╭──────────────────────────────────────────────────────────────╮
│  ERROR  Include Error                                    │
╰──────────────────────────────────────────────────────────────╯

File: IssueThread.stx (line 756, col 197)
Message: Error loading include file SiteFooter: ENOENT: no such file or directory, open '/var/www/reviewos-reviewos/releases/69385e0/resources/views/partials/SiteFooter.stx'

Context:
  754: let pageHeadRaw = (context.__stx_head_raw || "").trim(), pageHeadTitle;
  755: const rawTitleMatch = pageHeadRaw.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
> 756: if (rawTitleMatch) { pageHeadTitle = rawTitleMatch[1].trim(); pageHeadRaw = pageHeadRaw.replace(rawTitleMatch[0], "").trim(); }
  757: const sectionTitle = context.__sections?.title,
  758:       pageTitle = runtimeHead.title || pageHeadTitle || sectionTitle, headConfig = { ...baseHeadConfig, ...pageTitle && { title: pageTitle }, ... }
#
Source
Written by
Framework line
Verified render
1
context.__stx_runtime_head.title
useHead / useSeoMeta /  in a page with no server head
process.js:206, :213; bridge variable-extractor.js:312-323
FROM-USEHEAD beats @title, 
processHeadDirective, head.js:199-206 → process.js:559-564
process.js:207-212
FROM-HEAD wins only when 1 is absent
3
@section('title')
context.__sections.title
process.js:213
Section Title wins only when 1 and 2 are absent
4
config/ui.ts app.head.title
baseHeadConfig spread
process.js:206, :214
bare page renders <title>bughq</title>
5
"stx App"
generateDocumentShell default
document-shell.js:13, :21, :39
dist/dashboard.html ships <title>stx App</title>
Note the trap at tier 1:  writes only the module-global head (head.js:210 calls the static useHead), so if a <script server> already called useHead, process.js:206 reads context.__stx_runtime_head and @title is silently discarded. Two mechanisms, one winner, no warning.
4.0.1 API status table — stx 0.2.113
Half of the head API documented in head.d.ts is inert in a <script server> block. Do not use anything marked MUST NOT; it fails silently.
API
Implementation
Behaviour in <script server>
Verdict
useSeoMeta(config)
head.js:31-91
works for title, description, keywords, author, robots, all og:*, all twitter:*, all article:*
MUST — the default
useSeoMeta({ canonical })
head.js:82-84
dropped. The bridge at variable-extractor.js:326-331 copies only title and meta into context.__stx_runtime_head; link is never copied, and process.js:216 reads runtimeHead.link
MUST NOT — see 4.5
useHead(config)
head.js:15-17, bridge variable-extractor.js:312-323
works, and is the only call that carries link/script through
MUST for canonical/preload
definePageMeta(config)
head.js:92-99
no-op. The server scope binds definePageMeta = (_meta) => {} at variable-extractor.js:300
MUST NOT
usePageTitle / useTitle
head.js:100-103, head.js:222-224
not bound. Absent from the injected parameter list at variable-extractor.js:466
MUST NOT
titleTemplate
head.js:20-21, applied head.js:108-109
never applied. Neither bridge copies titleTemplate into context.__stx_runtime_head, and generateDocumentShell renders <title>${pageTitle}</title> raw (document-shell.js:39)
MUST NOT
: the expression could not be evaluated: Invalid character '\u2026' -->
seo.js:61-97, wired process.js:586
works; balanced-paren parse, auto-injects @context, emits <script type="application/ld+json">
MUST for JSON-LD
@structuredData … @endstructuredData
seo.js:321-339, needs registerSeoDirectives() (seo.js:340-345)
dead. registerSeoDirectives is exported but called nowhere in dist; the block renders as literal text into the page
MUST NOT
: the expression could not be evaluated: Invalid character '\u2026' -->
seo.js:98-242, wired process.js:587
works, but emits <title> + all meta inline at the call site, i.e. inside <body>, while the shell keeps its own wrong <title>
MUST NOT
@head, @title, @meta
head.js:199-220 → process.js:559-566; second @meta impl seo.js:3-17 → process.js:585
work, but lose to useHead and duplicate its job
MAY — layouts/partials only
app.head.meta/link/script
document-shell.js:11-51 (shell) and :67-99 (injectConfigHeadTags, deduped)
works on both page shapes
MUST for anything shared
Reproduce any row from the repo root:
bun -e '

  components/               # user components, resolvable by tag name
  views/                    # pagesDir — ONLY routable pages, nothing else
    index.stx               @extends('marketing')
    pricing.stx             @extends('marketing')
    docs.stx                @extends('marketing')
    compare.stx             @extends('marketing')
    use-cases.stx           @extends('marketing')
    compare/[slug].stx      @extends('marketing')   # replaces 8 × 153 identical files
    features/*.stx          @extends('marketing')
    use-cases/*.stx         @extends('marketing')
    login.stx               @extends('default')
    register.stx            @extends('default')
    forgot-password.stx     @extends('default')
    reset-password.stx      @extends('default')
    dashboard.stx           @extends('default')
    settings.stx            @extends('default')
    account.stx             @extends('default')
    projects/index.stx      @extends('default')
    projects/new.stx        @extends('default')
    issue/[id].stx          @extends('default')
Deleted: resources/views/layouts/, resources/views/components/FeatureCard.stx (zero references), and 7 of the 8 /compare/* files — they are byte-identical in tag+class skeleton and the canonical alternatives array already exists in resources/views/compare.stx:1-13, rendered with @foreach at compare.stx:52.
The matching config. All three directory keys are root-relative, because config.js:411-419 joins loaded.root onto each of partialsDir, componentsDir, layoutsDir — which is why the current absolute-looking values in config/ui.ts:10,13,16 become resources/resources/* and produce the include-error dump in dist/layouts/marketing.html:
export default {
  root: 'resources',        // explicit — do not let config.js:363-374 infer it
  pagesDir: 'views',
  layoutsDir: 'layouts',    // → resources/layouts
  componentsDir: 'components',
  partialsDir: 'partials',
  defaultLayout: 'default',
  app: { head: { /* rule 3.6 */ } },
  router: { container: 'main', interceptAllLinks: false /* after rule 3.9 */ },
} satisfies UiOptions
CHECK — one command that must pass before any .stx change is committed:
grep -rn "DOCTYPE\|<html[ >]" resources --include="*.stx"                       # empty
find resources/views -name '*.stx' -exec grep -L "@extends(" {} +               # empty
grep -rn "<main" resources/views --include="*.stx" | grep -v "{{--\|<!--"       # empty
grep -rn "data-no-router" resources/views --include="*.stx" | grep -v "/api/"   # empty
grep -rn "@extends(\|@layout(" resources/layouts/*.stx                          # empty
test ! -d resources/views/layouts && test ! -e app.stx