@stacksjs/stx 0.2.355 → 0.2.357

package/dist/ssg.js

@@ -1,5 +1,5 @@
 // @bun
-import{Bk as Fq,wk as Uq,xk as Iq}from"./chunk-p3p4d6g1.js";import{Ck as Eq,Dk as Tq,Ek as Dq}from"./chunk-c0n802j1.js";import{Zk as _q,al as zq,bl as Aq}from"./chunk-epqd3eah.js";import"./chunk-ngjkzaj7.js";import"./chunk-fvsefztj.js";import{Jp as P,Sm as Oq,io as l,lo as Hq,sr as n}from"./chunk-msq8xvhp.js";import"./chunk-8y1ve8tc.js";import"./chunk-njx93b4z.js";import"./chunk-2wb3pgp4.js";import"./chunk-89mqnh67.js";import"./chunk-xvh1k1a4.js";import{it as Xq}from"./chunk-9e20mgwc.js";import{nt as d}from"./chunk-y2f41kaq.js";import"./chunk-xj6bcwqa.js";import"./chunk-gtqbvt3a.js";import"./chunk-vhta1be7.js";import{Ut as Bq}from"./chunk-tc4pj651.js";import"./chunk-san1eq0r.js";import"./chunk-avwywzsj.js";import"./chunk-wj21f1e0.js";import"./chunk-d86q27j8.js";import"./chunk-72x62kch.js";import{rw as Yq,sw as Vq,tw as jq,uw as Gq,vw as Lq,ww as Nq}from"./chunk-swvm1wgn.js";import"./chunk-9nrgjtah.js";import{Nw as y}from"./chunk-ejqpq0wc.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(`
+import{Ck as Fq,xk as Uq,yk as Iq}from"./chunk-wz4fnsat.js";import{Dk as Eq,Ek as Tq,Fk as Dq}from"./chunk-frp9fc7j.js";import{_k as _q,bl as zq,cl as Aq}from"./chunk-degz74nv.js";import"./chunk-t23kccpz.js";import"./chunk-qjvny3wf.js";import{Kp as P,Tm as Oq,jo as l,mo as Hq,wr as n}from"./chunk-3ssjb8cx.js";import"./chunk-ykevda74.js";import"./chunk-ez003q74.js";import"./chunk-kyyt9xhs.js";import"./chunk-tf16jtj4.js";import"./chunk-19m7hed6.js";import{mt as Xq}from"./chunk-kjd9hbg4.js";import{rt as d}from"./chunk-ejwfnttb.js";import"./chunk-5270fyk7.js";import"./chunk-q4kgqqed.js";import"./chunk-1nnza3m6.js";import{Yt as Bq}from"./chunk-hkrzv980.js";import"./chunk-qbz6yn8c.js";import"./chunk-czj6nq0b.js";import"./chunk-zxfejz72.js";import"./chunk-mere396d.js";import"./chunk-aa8015mk.js";import{Aw as Nq,vw as Yq,ww as Vq,xw as jq,yw as Gq,zw as Lq}from"./chunk-trva71am.js";import"./chunk-rtfwn4cm.js";import{Rw as y}from"./chunk-emjmshj8.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]}
@@ -41,7 +41,7 @@ ${q.map((Q)=>{let K=new URL(Q.loc,Z).href,J=`  <url>
 ${$.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-avye7h5s.js");try{L=N(await Y(process.cwd()))}catch{}}let{prepareImageDelivery:_}=await import("./chunk-e631svvs.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-avye7h5s.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,pagesDirs:$?._layerPageDirs});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",`
+</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-3kyydhzt.js");try{L=N(await Y(process.cwd()))}catch{}}let{prepareImageDelivery:_}=await import("./chunk-j8wycqve.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-3kyydhzt.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,pagesDirs:$?._layerPageDirs});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:

package/dist/stx-module-imports.d.ts

@@ -0,0 +1,24 @@
+import type { ScriptBlock, ScriptKind } from './stx-virtual-ts';
+/**
+ * Names imported from `stx` into a block kind that does not receive them.
+ *
+ * A name the module does not export at all is left alone: TypeScript already
+ * reports it (TS2305), and saying it twice helps nobody.
+ */
+export declare function stxImportDiagnostics(source: string, blocks: readonly ScriptBlock[]): StxImportDiagnostic[];
+/** Names `import { … } from 'stx'` binds in a `<script server>` block. */
+export declare const STX_SERVER_MODULE_EXPORTS: readonly string[];
+/** Names `import { … } from 'stx'` binds in a client block. */
+export declare const STX_CLIENT_MODULE_EXPORTS: readonly string[];
+/** Every value `stx-module.d.ts` exports: what at least one block kind gets. */
+export declare const STX_MODULE_EXPORTS: readonly string[];
+/** A name imported from `stx` into a block that does not receive it. */
+export declare interface StxImportDiagnostic {
+  line: number
+  column: number
+  offset: number
+  length: number
+  name: string
+  kind: ScriptKind
+  message: string
+}

package/dist/stx-module-imports.js

@@ -0,0 +1,57 @@
+import { STX_ENGINE_BINDING_NAMES } from "./engine-bindings.js";
+import { STX_RUNTIME_GLOBALS } from "./runtime-globals.js";
+const ENVIRONMENT_BINDINGS = new Set([
+  "module",
+  "exports",
+  "require",
+  "$bool",
+  "window",
+  "document",
+  "console",
+  "confirm",
+  "alert",
+  "fetch"
+]);
+export const STX_SERVER_MODULE_EXPORTS = STX_ENGINE_BINDING_NAMES.filter((name) => !ENVIRONMENT_BINDINGS.has(name)).sort(), STX_CLIENT_MODULE_EXPORTS = [...STX_RUNTIME_GLOBALS].sort(), STX_MODULE_EXPORTS = [...new Set([...STX_SERVER_MODULE_EXPORTS, ...STX_CLIENT_MODULE_EXPORTS])].sort();
+const SERVER = new Set(STX_SERVER_MODULE_EXPORTS), CLIENT = new Set(STX_CLIENT_MODULE_EXPORTS), EXPORTED = new Set(STX_MODULE_EXPORTS), STX_IMPORT_RE = /\bimport\s+(?!type[\s{])\{([^}]*)\}\s*from\s*(['"])stx\2/g;
+function messageFor(name, kind) {
+  if (kind === "server")
+    return `'${name}' is not provided by 'stx' in a <script server> block. The engine binds only its own names there (defineProps, state, useHead, ...); any other name becomes \`await import('stx')\`, which does not resolve, so the whole script fails when the page renders. Import it from '@stacksjs/stx' instead.`;
+  return `'${name}' is not provided by 'stx' in a client <script> block. The import is replaced by the window.stx runtime, which has no '${name}', so it is undefined in the browser.`;
+}
+export function stxImportDiagnostics(source, blocks) {
+  const diagnostics = [];
+  for (const block of blocks) {
+    if (block.offset === void 0)
+      continue;
+    const provided = block.kind === "server" ? SERVER : CLIENT;
+    STX_IMPORT_RE.lastIndex = 0;
+    for (const match of block.code.matchAll(STX_IMPORT_RE)) {
+      const listStart = match.index + match[0].indexOf("{") + 1;
+      for (const specifier of match[1].matchAll(/[^,]+/g)) {
+        const text = specifier[0];
+        if (/^\s*type\s/.test(text))
+          continue;
+        const imported = /^\s*([A-Za-z_$][\w$]*)/.exec(text);
+        if (!imported)
+          continue;
+        const name = imported[1];
+        if (!EXPORTED.has(name) || provided.has(name))
+          continue;
+        const offset = block.offset + listStart + specifier.index + imported[0].length - name.length, before = source.slice(0, offset), line = before.split(`
+`).length;
+        diagnostics.push({
+          line,
+          column: offset - (before.lastIndexOf(`
+`) + 1) + 1,
+          offset,
+          length: name.length,
+          name,
+          kind: block.kind,
+          message: messageFor(name, block.kind)
+        });
+      }
+    }
+  }
+  return diagnostics;
+}

package/dist/stx-module.d.ts

@@ -0,0 +1,154 @@
+/// <reference path="./stx.d.ts" />
+
+/**
+ * The `stx` module, as a `.stx` script block sees it.
+ *
+ * `stx` is a VIRTUAL specifier. No package by that name is installed in an app,
+ * and `import { … } from 'stx'` works only because both script paths intercept
+ * it: a client block's import is stripped and its names destructured off
+ * `window.stx`, and a server block's names are handed in by the engine as
+ * parameters. So what this module exports is exactly what those two paths bind,
+ * and nothing else from `@stacksjs/stx` (see src/stx-module-imports.ts):
+ *
+ *  - every name destructured off `window.stx` (STX_RUNTIME_GLOBALS), which a
+ *    server block also receives where the engine binds it, and
+ *  - the stx API names only the server engine binds, marked below.
+ *
+ * Each value is typed by the ambient global of the same name in `stx.d.ts`, so
+ * an imported `state` is exactly the auto-imported one; the module adds no
+ * second copy of any signature to drift.
+ *
+ * This file is NOT referenced from the package's types entry, on purpose. The
+ * specifier is virtual only inside a `.stx` block; a `.ts` file importing from
+ * `stx` has a real import that does not resolve. `stx typecheck` and the editor
+ * plugin add it to the programs they build for `.stx` files.
+ *
+ * Which block kind gets which name is checked separately, because one
+ * declaration cannot say it: `stxImportDiagnostics` reports a server-only name
+ * imported into a client block and the reverse.
+ *
+ * test/stx-module-declaration.test.ts keeps this list equal to the runtime's.
+ */
+declare module 'stx' {
+  export const $props: Record<string, any> // <script server> only
+  export const batch: typeof globalThis.batch
+  export const clearServerData: typeof globalThis.clearServerData
+  export const computed: typeof globalThis.computed
+  export const configureFetch: typeof globalThis.configureFetch
+  export const defineClientPayload: (payload: Record<string, unknown>) => void // <script server> only
+  export const defineEmits: typeof globalThis.defineEmits
+  export const defineExpose: typeof globalThis.defineExpose
+  export const definePageMeta: typeof globalThis.definePageMeta
+  export const defineProps: typeof globalThis.defineProps
+  export const defineSlots: typeof globalThis.defineSlots
+  export const defineStore: typeof globalThis.defineStore
+  export const derived: typeof globalThis.derived
+  export const effect: typeof globalThis.effect
+  export const goBack: typeof globalThis.goBack
+  export const goForward: typeof globalThis.goForward
+  export const inject: typeof globalThis.inject
+  export const invalidateRoute: typeof globalThis.invalidateRoute
+  export const isDerived: typeof globalThis.isDerived
+  export const isSignal: typeof globalThis.isSignal
+  export const navigate: typeof globalThis.navigate
+  export const nextTick: typeof globalThis.nextTick
+  export const notFound: (status?: number) => void // <script server> only
+  export const onBeforeMount: typeof globalThis.onBeforeMount
+  export const onBeforeUnmount: typeof globalThis.onBeforeUnmount
+  export const onDestroy: typeof globalThis.onDestroy
+  export const onMount: typeof globalThis.onMount
+  export const onMounted: typeof globalThis.onMounted
+  export const onUnmounted: typeof globalThis.onUnmounted
+  export const params: Record<string, string> // <script server> only
+  export const peek: typeof globalThis.peek
+  export const props: Record<string, any> // <script server> only
+  export const provide: typeof globalThis.provide
+  export const reactive: typeof globalThis.reactive
+  export const ref: typeof globalThis.ref
+  export const refresh: typeof globalThis.refresh
+  export const registerStoresClient: typeof globalThis.registerStoresClient
+  export const setResponseHeader: (name: string, value: string) => void // <script server> only
+  export const setResponseStatus: (status: number) => void // <script server> only
+  export const setRouteParams: typeof globalThis.setRouteParams
+  export const state: typeof globalThis.state
+  export const untrack: typeof globalThis.untrack
+  export const useAsync: typeof globalThis.useAsync
+  export const useClickOutside: typeof globalThis.useClickOutside
+  export const useColorMode: typeof globalThis.useColorMode
+  export const useCookie: typeof globalThis.useCookie
+  export const useCounter: typeof globalThis.useCounter
+  export const useDark: typeof globalThis.useDark
+  export const useDebounce: typeof globalThis.useDebounce
+  export const useDebouncedValue: typeof globalThis.useDebouncedValue
+  export const useDocumentVisibility: typeof globalThis.useDocumentVisibility
+  export const useEventListener: typeof globalThis.useEventListener
+  export const useFetch: typeof globalThis.useFetch
+  export const useFocus: typeof globalThis.useFocus
+  export const useHead: typeof globalThis.useHead
+  export const useId: typeof globalThis.useId
+  export const useInterval: typeof globalThis.useInterval
+  export const useLocalStorage: typeof globalThis.useLocalStorage
+  export const useMediaQuery: typeof globalThis.useMediaQuery
+  export const useModel: typeof globalThis.useModel
+  export const useMutation: typeof globalThis.useMutation
+  export const useOptimistic: typeof globalThis.useOptimistic
+  export const usePreferredContrast: typeof globalThis.usePreferredContrast
+  export const usePreferredDark: typeof globalThis.usePreferredDark
+  export const usePreferredLight: typeof globalThis.usePreferredLight
+  export const usePreferredReducedMotion: typeof globalThis.usePreferredReducedMotion
+  export const useQuery: typeof globalThis.useQuery
+  export const useReactiveProp: typeof globalThis.useReactiveProp
+  export const useRef: typeof globalThis.useRef
+  export const useRoute: typeof globalThis.useRoute
+  export const useRouteParam: typeof globalThis.useRouteParam
+  export const useRouteParams: typeof globalThis.useRouteParams
+  export const useRouter: () => { push: (to: unknown) => void, replace: (to: unknown) => void, back: () => void, forward: () => void, go: (n: number) => void } // <script server> only
+  export const useRuntimeConfig: () => Readonly<Record<string, any>> // <script server> only
+  export const useScrollLock: typeof globalThis.useScrollLock
+  export const useSearchParams: typeof globalThis.useSearchParams
+  export const useSeoMeta: typeof globalThis.useSeoMeta
+  export const useServerData: typeof globalThis.useServerData // <script server> only
+  export const useServerRuntimeConfig: () => Readonly<{ public: Record<string, any>, private: Record<string, any> }> // <script server> only
+  export const useSessionStorage: typeof globalThis.useSessionStorage
+  export const useSlots: typeof globalThis.useSlots
+  export const useStore: typeof globalThis.useStore
+  export const useThrottle: typeof globalThis.useThrottle
+  export const useTimeout: typeof globalThis.useTimeout
+  export const useToggle: typeof globalThis.useToggle
+  export const useWebSocket: typeof globalThis.useWebSocket
+  export const watch: typeof globalThis.watch
+  export const watchEffect: typeof globalThis.watchEffect
+  export const watchMultiple: typeof globalThis.watchMultiple
+  export const withDefaults: typeof globalThis.withDefaults
+
+  export type StxSignal<T> = globalThis.StxSignal<T>
+  export type StxDerivedSignal<T> = globalThis.StxDerivedSignal<T>
+  export type StxRef<T> = globalThis.StxRef<T>
+  export type StxCleanup = globalThis.StxCleanup
+  export type StxModelOptions<T> = globalThis.StxModelOptions<T>
+  export type StxModelSignal<T> = globalThis.StxModelSignal<T>
+  export type StxTemplateRef<T> = globalThis.StxTemplateRef<T>
+  export type StxNavigateOptions = globalThis.StxNavigateOptions
+  export type StxSearchParamsCommitOptions = globalThis.StxSearchParamsCommitOptions
+  export type StxRefetchOptions = globalThis.StxRefetchOptions
+  export type StxFetchResult<T> = globalThis.StxFetchResult<T>
+  export type StxQueryResult<T> = globalThis.StxQueryResult<T>
+  export type StxMutationResult<T> = globalThis.StxMutationResult<T>
+  export type StxFetchRequestContext = globalThis.StxFetchRequestContext
+  export type StxFetchResponseContext = globalThis.StxFetchResponseContext
+  export type StxFetchErrorContext = globalThis.StxFetchErrorContext
+  export type StxEventListenerOptions = globalThis.StxEventListenerOptions
+  export type StxIntervalOptions = globalThis.StxIntervalOptions
+  export type StxIntervalControls = globalThis.StxIntervalControls
+  export type StxCookieOptions = globalThis.StxCookieOptions
+  export type StxColorModeOptions = globalThis.StxColorModeOptions
+  export type StxHeadConfig = globalThis.StxHeadConfig
+  export type StxSeoMetaConfig = globalThis.StxSeoMetaConfig
+  export type StxToastOptions = globalThis.StxToastOptions
+  export type StxToast = globalThis.StxToast
+  export type StxModal = globalThis.StxModal
+  export type StxDrawer = globalThis.StxDrawer
+  export type StxDialogOptions = globalThis.StxDialogOptions
+  export type StxStorePersistOptions = globalThis.StxStorePersistOptions
+  export type StxStoreOptions = globalThis.StxStoreOptions
+}

package/dist/stx-plugin-config.d.ts

@@ -0,0 +1,17 @@
+/** The nearest `tsconfig.json` at or above `startDir`. */
+export declare function findNearestTsconfig(startDir: string, exists: (file: string) => boolean): string | undefined;
+/**
+ * The stx plugin entry governing files under `startDir`, following `extends`.
+ *
+ * Only relative `extends` are followed; a package base (`@tsconfig/…`) does not
+ * carry an app's stx configuration.
+ */
+export declare function findStxPluginEntry(startDir: string, read: ReadConfig, exists: (file: string) => boolean): StxPluginEntry | undefined;
+/** The name the stx TypeScript plugin is contributed and configured under. */
+export declare const STX_TS_PLUGIN_NAME: '@stacksjs/stx-typescript-plugin';
+export declare interface StxPluginEntry {
+  configPath: string
+  libs: string[]
+}
+/** Read a tsconfig file as an object, or undefined when it cannot be read. */
+export type ReadConfig = (file: string) => Record<string, any> | undefined;

package/dist/stx-plugin-config.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+export const STX_TS_PLUGIN_NAME = "@stacksjs/stx-typescript-plugin";
+export function findNearestTsconfig(startDir, exists) {
+  let dir = path.resolve(startDir);
+  for (;; ) {
+    const candidate = path.join(dir, "tsconfig.json");
+    if (exists(candidate))
+      return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      return;
+    dir = parent;
+  }
+}
+export function findStxPluginEntry(startDir, read, exists) {
+  const leaf = findNearestTsconfig(startDir, exists);
+  if (!leaf)
+    return;
+  const seen = new Set, visit = (configPath) => {
+    if (seen.has(configPath))
+      return;
+    seen.add(configPath);
+    const config = read(configPath);
+    if (!config)
+      return;
+    const plugins = config.compilerOptions?.plugins;
+    if (Array.isArray(plugins)) {
+      const entry = plugins.find((plugin) => plugin?.name === STX_TS_PLUGIN_NAME), libs = Array.isArray(entry?.libs) ? entry.libs.filter((lib) => typeof lib === "string") : [];
+      return entry ? { configPath, libs: libs.map((lib) => path.resolve(path.dirname(configPath), lib)) } : null;
+    }
+    const bases = typeof config.extends === "string" ? [config.extends] : Array.isArray(config.extends) ? config.extends : [];
+    for (const base of [...bases].reverse()) {
+      if (typeof base !== "string" || !base.startsWith("."))
+        continue;
+      const resolved = path.resolve(path.dirname(configPath), base.endsWith(".json") ? base : `${base}.json`), found = visit(resolved);
+      if (found !== void 0)
+        return found;
+    }
+    return;
+  };
+  return visit(leaf) ?? void 0;
+}

package/dist/stx-virtual-ts.d.ts

@@ -49,6 +49,15 @@ export interface ScriptBlock {
     code: string;
     /** 1-based line in the source file where the body's first character sits. */
     startLine: number;
+    /**
+     * 1-based column of the body's first character. Greater than 1 when the
+     * code starts on the line the opening tag is on (`<script client>const a`),
+     * which a buffer has to pad for or every diagnostic on that line lands
+     * left of the code it is about.
+     */
+    startColumn?: number;
+    /** Offset of the body's first character in the source. */
+    offset?: number;
     /** The opening tag's attributes, trimmed. */
     attrs: string;
 }
@@ -99,6 +108,8 @@ export interface MappedLine {
 export interface VirtualFile {
     text: string;
     componentDependencies?: Map<string, string>;
+    /** Whether the `reference` option's directive was written (line 1 was free). */
+    referenced?: boolean;
     /**
      * Virtual 1-based line → where it came from.
      *
@@ -239,7 +250,17 @@ export declare function runtimeGlobalDeclarations(): string;
  * checker report a genuine typo instead of suppressing every unresolved name.
  */
 export declare const STX_SERVER_CONTEXT: readonly ['params', 'query', 'cookies', 'host', 'ip', 'setResponseStatus', 'setResponseHeader', 'notFound', 'request', 'url', 'definePageMeta', 'defineClientPayload', 'defineStore', 'props', '$props'];
-export declare function serverContextDeclarations(): string;
+export declare function serverContextDeclarations(typed?: ReadonlySet<string>): string;
+/**
+ * Names a global declaration file declares as values: `declare function`,
+ * `declare const` / `let` / `var`, at the start of a line.
+ *
+ * Used to keep the `any` fallbacks below from colliding with a TYPED global of
+ * the same name in `stx.d.ts` — `definePageMeta` and `defineStore` are both
+ * server context and typed runtime globals, and `declare var x: any` beside
+ * `declare function x()` is a conflict that leaves the name typed by neither.
+ */
+export declare function declaredGlobalNames(declarations: string): Set<string>;
 /**
  * The names a `defineClientPayload({ … })` call publishes, or `null` when the
  * page does not declare one.
@@ -421,6 +442,19 @@ export declare function expressionStatement(expression: TemplateExpression): {
  * change a line count, so every diagnostic still lands on the author's line.
  */
 export declare function absolutizeRelativeSpecifiers(code: string, originDir: string): string;
+/**
+ * Spaces that put a block's first line at the column it occupies in the file.
+ *
+ * A body that starts on the opening tag's line (`<script client>const a = 1`)
+ * was written from column 1, so every diagnostic on that line pointed left of
+ * the code it was about by the width of the tag.
+ */
+export declare function firstLinePadding(block: ScriptBlock): string;
+/**
+ * Local names a block's `import` declarations bind, type-only ones included:
+ * `import a, { b as c, type D } from 'x'` and `import * as ns from 'x'`.
+ */
+export declare function collectImportedNames(code: string): string[];
 export interface BuildVirtualOptions {
     /** Enables component call-site checks using the renderer's file lookup. */
     filePath?: string;
@@ -438,6 +472,28 @@ export interface BuildVirtualOptions {
     originDir?: string;
     /** Append ambient declarations at all. Default true. */
     globals?: boolean;
+    /**
+     * Where the server context, the `@stacksjs/browser` auto-imports and the
+     * template globals are declared. Default `'module'`.
+     *
+     * `'global'` wraps them in `declare global { … }`. Declared in the module
+     * they share a scope with the author's own bindings, so a block's
+     * `const { query } = defineProps()` is a redeclaration of the context's
+     * `query`; declared globally, the block's binding shadows it instead, as it
+     * does in `stx typecheck`, whose context is a global file. The editor, which
+     * has one buffer per file, needs the global form.
+     */
+    contextScope?: 'module' | 'global';
+    /**
+     * A declaration file to pull into the program with a triple-slash
+     * reference, written on the buffer's first line.
+     *
+     * That line is always blank when the file opens with markup or with a
+     * `<script>` tag on a line of its own, which is how every real file starts,
+     * so nothing moves. When code sits on line 1 the reference is left out and
+     * {@link VirtualFile.referenced} says so, so the caller can fall back.
+     */
+    reference?: string;
     /**
      * Declare the stx runtime globals as `any`. Default true.
      *
@@ -479,6 +535,23 @@ export interface ResolvedPosition {
      */
     inGuard?: boolean;
 }
+/**
+ * Whether a diagnostic on a template-expression line is an artefact of how the
+ * expression was wrapped rather than a fault in it. Both checkers drop these,
+ * so the editor and `stx typecheck` agree:
+ *
+ *  - A hit inside the `if (…) {` wrapper that markup guards put around an
+ *    expression is about the enclosing CONDITION, which is checked on a line
+ *    of its own. This copy would report the same fault again against innocent
+ *    markup (stacksjs/stx#2013).
+ *  - TS2774 ("this condition will always return true since this function is
+ *    always defined") is wrong about a template, and only about a template.
+ *    {@link UNWRAP_HELPER} types a signal as the intersection of the signal and
+ *    its value, which stays callable, and the runtime unwraps a name the
+ *    expression only reads — so `x-class="ready ? '' : 'hidden'"` does not
+ *    always return true. In a script block it is a true positive and is kept.
+ */
+export declare function isTemplateArtefact(position: ResolvedPosition, code: number): boolean;
 /**
  * Translate a position in a virtual buffer back to the `.stx` file.
  *

package/dist/stx-virtual-ts.js

@@ -20,7 +20,7 @@ export function extractScriptBlocks(source) {
     if (typeMatch && !/^(?:module|text\/(?:javascript|typescript))$/i.test(typeMatch[1]))
       continue;
     const kind = /\bserver\b/.test(attrs) ? "server" : /\bclient\b/.test(attrs) ? "client" : "plain", startLine = lineAt(source, bodyStart);
-    blocks.push({ kind, code: body, startLine, attrs });
+    blocks.push({ kind, code: body, startLine, startColumn: columnAt(source, bodyStart), offset: bodyStart, attrs });
   }
   return blocks;
 }
@@ -340,10 +340,13 @@ export const STX_SERVER_CONTEXT = [
   "props",
   "$props"
 ];
-export function serverContextDeclarations() {
-  return STX_SERVER_CONTEXT.map((name) => `declare var ${name}: any`).join(`
+export function serverContextDeclarations(typed = new Set) {
+  return STX_SERVER_CONTEXT.filter((name) => !typed.has(name)).map((name) => `declare var ${name}: any`).join(`
 `);
 }
+export function declaredGlobalNames(declarations) {
+  return new Set([...declarations.matchAll(/^declare (?:function|const|let|var)\s+([A-Za-z_$][\w$]*)/gm)].map((match) => match[1]));
+}
 export function extractClientPayloadNames(serverCode) {
   const call = /\bdefineClientPayload\s*\(\s*\{([\s\S]*?)\}\s*\)/g;
   let match, found = !1;
@@ -608,6 +611,27 @@ export function absolutizeRelativeSpecifiers(code, originDir) {
     return `${prefix}${quote}${absolute}${quote}`;
   });
 }
+export function firstLinePadding(block) {
+  return " ".repeat(Math.max(0, (block.startColumn ?? 1) - 1));
+}
+export function collectImportedNames(code) {
+  const names = new Set, stripped = stripCommentsAndLiterals(code);
+  for (const match of stripped.matchAll(/\bimport\s+(?:type\s+)?([\w$*{}\s,]+?)\s+from\b/g)) {
+    const clause = match[1], named = /\{([^}]*)\}/.exec(clause);
+    for (const part of named?.[1].split(",") ?? []) {
+      const local = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/).pop()?.trim();
+      if (local && /^[A-Z_$][\w$]*$/i.test(local))
+        names.add(local);
+    }
+    const outside = clause.replace(/\{[^}]*\}/, ""), namespace = /\*\s*as\s+([A-Z_$][\w$]*)/i.exec(outside);
+    if (namespace)
+      names.add(namespace[1]);
+    const defaultName = /^\s*([A-Z_$][\w$]*)/i.exec(outside);
+    if (defaultName && defaultName[1] !== "type")
+      names.add(defaultName[1]);
+  }
+  return [...names].sort();
+}
 export function buildVirtualTypeScript(source, options = {}) {
   const blocks = extractScriptBlocks(source), sourceLines = source.split(`
 `), lines = Array.from({ length: sourceLines.length }, () => ""), lineMap = new Map, components = options.filePath && options.templateExpressions !== !1 ? componentContractChecks(source, maskNonTemplateRegions(source), {
@@ -617,14 +641,24 @@ export function buildVirtualTypeScript(source, options = {}) {
     readComponent: options.readComponent,
     scriptCode: (text, file) => extractScriptBlocks(text).map((block) => absolutizeRelativeSpecifiers(block.code, path.dirname(file))).join(`
 `)
-  }) : void 0;
-  for (const block of blocks)
-    absolutizeRelativeSpecifiers(block.code, options.originDir ?? "").split(`
-`).forEach((text, i) => {
+  }) : void 0, occupied = new Set, blockEnds = [];
+  for (const block of blocks) {
+    const code = blankScriptDirectives(substituteInterpolationsInPlace(block.code)), bodyLines = absolutizeRelativeSpecifiers(code, options.originDir ?? "").split(`
+`);
+    bodyLines.forEach((text, i) => {
       const index = block.startLine - 1 + i;
-      if (index < lines.length)
-        lines[index] = text;
+      if (index < lines.length) {
+        lines[index] = i === 0 ? firstLinePadding(block) + text : text;
+        occupied.add(index);
+      }
     });
+    blockEnds.push(block.startLine - 1 + bodyLines.length - 1);
+  }
+  for (const end of blockEnds) {
+    const at = lines[end]?.trim() === "" ? end : end + 1;
+    if (at < lines.length && lines[at].trim() === "" && (at === end || !occupied.has(at)))
+      lines[at] = ";";
+  }
   const append = (text, origin) => {
     for (const [index, line] of text.split(`
 `).entries()) {
@@ -635,17 +669,33 @@ export function buildVirtualTypeScript(source, options = {}) {
   };
   if (options.globals !== !1) {
     append("");
-    if (options.runtimeGlobals !== !1)
-      for (const decl of runtimeGlobalDeclarations().split(`
-`))
-        append(decl);
-    for (const decl of serverContextDeclarations().split(`
-`))
-      append(decl);
-    for (const name of BROWSER_CORE_IMPORTS)
-      append(`declare var ${name}: any`);
-    for (const name of STX_TEMPLATE_GLOBALS)
-      append(`declare var ${name}: any`);
+    const bound = new Set([
+      ...blocks.flatMap((block) => collectBlockDeclarations(block.code)),
+      ...blocks.flatMap((block) => collectImportedNames(block.code))
+    ]), declareAny = (name) => {
+      if (!bound.has(name))
+        append(`declare var ${name}: any`);
+    };
+    if (options.runtimeGlobals !== !1) {
+      if (!bound.has("window"))
+        append("declare var window: any");
+      for (const name of STX_RUNTIME_GLOBALS)
+        declareAny(name);
+    }
+    const contextNames = [...new Set([...STX_SERVER_CONTEXT, ...BROWSER_CORE_IMPORTS, ...STX_TEMPLATE_GLOBALS])].filter((name) => options.runtimeGlobals !== !1 || !STX_RUNTIME_GLOBALS.includes(name));
+    if (options.contextScope === "global") {
+      append("declare global {");
+      for (const name of contextNames)
+        append(`  var ${name}: any`);
+      append("}");
+    } else {
+      for (const name of STX_SERVER_CONTEXT)
+        declareAny(name);
+      for (const name of BROWSER_CORE_IMPORTS)
+        declareAny(name);
+      for (const name of STX_TEMPLATE_GLOBALS)
+        declareAny(name);
+    }
     append(`declare var ${INTERPOLATION_PLACEHOLDER}: any`);
     const declared = new Set(blocks.flatMap((block) => collectBlockDeclarations(block.code)));
     append(`type ${ELEMENT_HELPER}<T> = T extends readonly (infer E)[] ? E : T extends Iterable<infer E2> ? E2 : any`);
@@ -695,9 +745,14 @@ export function buildVirtualTypeScript(source, options = {}) {
         append("});");
     }
   }
+  let referenced = !1;
+  if (options.reference && lines[0] !== void 0 && lines[0].trim() === "") {
+    lines[0] = `/// <reference path=${JSON.stringify(options.reference.replace(/\\/g, "/"))} />`;
+    referenced = !0;
+  }
   append("export {}");
   return { text: lines.join(`
-`), lineMap, sourceLineCount: sourceLines.length, componentDependencies: components?.dependencies };
+`), lineMap, sourceLineCount: sourceLines.length, componentDependencies: components?.dependencies, referenced };
 }
 export function lineStarts(text) {
   const starts = [0];
@@ -721,6 +776,11 @@ export function positionToOffset(starts, line, column) {
   const index = Math.min(Math.max(line, 1), starts.length) - 1, next = index + 1 < starts.length ? starts[index + 1] - 1 : Number.MAX_SAFE_INTEGER;
   return Math.min(starts[index] + Math.max(column, 1) - 1, next);
 }
+export function isTemplateArtefact(position, code) {
+  if (!position.expression)
+    return !1;
+  return position.inGuard === !0 || code === 2774;
+}
 export function resolvePosition(virtual, line, column) {
   const mapped = virtual.lineMap.get(line);
   if (!mapped)

package/dist/typecheck.d.ts

@@ -34,6 +34,19 @@ export declare function sourcePathFor(virtualPath: string): string;
  * than hand tsc a path to nothing.
  */
 export declare function findRuntimeTypeDeclarations(): string | null;
+/**
+ * Locate the package's own `stx-module.d.ts`, which declares the virtual `stx`
+ * module a `.stx` block imports from.
+ *
+ * It used to be generated here as `declare module 'stx' { export * from
+ * '@stacksjs/stx' }`, which typed `from 'stx'` as the whole package. That is
+ * not what the specifier binds: a client block gets only what is destructured
+ * off `window.stx`, a server block only what the engine passes in, and every
+ * other name fails at runtime (stacksjs/stx#2028). The declaration file says
+ * exactly that, and the editor plugin loads the same one, so the two checkers
+ * cannot disagree about it.
+ */
+export declare function findStxModuleDeclarations(): string | null;
 export declare function typecheckStxFiles(files: string[], options?: TypecheckOptions): Promise<TypecheckResult>;
 /** Render diagnostics the way a CLI should: file:line:col, then the message. */
 export declare function formatTypecheckDiagnostics(diagnostics: TypecheckDiagnostic[]): string;