@jxsuite/compiler 5.0.0 → 5.1.1

package/dist/compiler.js

@@ -284,7 +284,7 @@ app.post('${t}/${e}', async (c) => {
   }
 })`}var UE=P(()=>{Jl();qb();_n()});function zb(e){let t=[],r=[],n=null,s=0,A=()=>r.at(-1)?.path??"",o=()=>n===null?A():gZ(A(),n),i=()=>{s+=1;let a="";while(s<e.length){let c=e[s];if(c==="\\"){let l=e[s+1]??"";if(l==="u")a+=String.fromCodePoint(Number.parseInt(e.slice(s+2,s+6),16)),s+=6;else a+=lZ[l]??l,s+=2;continue}if(c==='"')return s+=1,a;a+=c,s+=1}return a};while(s<e.length){let a=e[s];if(Kb.has(a)||a===","||a===":"){s+=1;continue}if(a==="{"||a==="["){r.push(a==="{"?{keys:new Set,kind:"object",path:o()}:{kind:"array",path:o()}),n=null,s+=1;continue}if(a==="}"||a==="]"){r.pop(),n=null,s+=1;continue}if(a==='"'){let l=i(),u=r.at(-1);if(u?.kind==="object"&&uZ(e,s)===":"){if(u.keys.has(l))t.push({detail:l,kind:"duplicate-key",path:u.path});u.keys.add(l),n=l}else n=null;continue}if(a==="-"||a>="0"&&a<="9"){let l=s;while(s<e.length&&/[\d+.eE-]/.test(e[s]))s+=1;let u=e.slice(l,s);if(!fZ(u))t.push({detail:u,kind:"unsafe-number",path:o()});n=null;continue}let c=s;while(s<e.length&&/[A-Za-z]/.test(e[s]))s+=1;if(s===c)s+=1;n=null}return t}function uZ(e,t){let r=t;while(r<e.length&&Kb.has(e[r]))r+=1;return e[r]??""}function gZ(e,t){return e===""?t:`${e}.${t}`}function fZ(e){if(/[.eE]/.test(e))return!0;let t=Number(e);if(!Number.isFinite(t))return!1;return String(t)===e.replace(/^\+/,"")}function Xb(e){let t=e.path===""?"the document root":`"${e.path}"`;return e.kind==="duplicate-key"?`duplicate key "${e.detail}" in ${t} — JSON.parse keeps the last one and `+"silently discards the first (RFC 7493 §2.3)":`number ${e.detail} in ${t} cannot be represented exactly and will change when `+"the document is written back (RFC 7493 §2.2)"}var Kb,lZ;var ex=P(()=>{Kb=new Set([" ","\t",`
 `,"\r"]);lZ={b:"\b",f:"\f",n:`
-`,r:"\r",t:"\t"}});function hZ(e){return e instanceof Error?e.message:String(e)}function LE(e){if(typeof e==="string")return tx.test(e)?e.normalize("NFC"):e;if(Array.isArray(e))return e.map((t)=>LE(t));if(Ye(e)){let t={};for(let[r,n]of Object.entries(e))t[tx.test(r)?r.normalize("NFC"):r]=LE(n);return t}return e}function OE(e,t,r){let n;try{n=JSON.parse(e)}catch(A){throw Error(`Failed to parse ${r} at ${t}: ${hZ(A)}`,{cause:A})}if(!Ye(n))throw Error(`Invalid ${r} at ${t}: expected a JSON object`);let s=zb(e);if(s.length>0){let A=s.map((o)=>Xb(o)).join("; ");throw Error(`Invalid ${r} at ${t}: ${A}`)}return LE(n)}function Ql(e,t){return OE(e,t,"Jx document")}function n3(e,t){return OE(e,t,"project config")}function s3(e,t){return OE(e,t,"class definition")}var tx;var vE=P(()=>{xr();ex();tx=/[^\p{ASCII}]/u});function Ax(e){if(typeof e!=="string")return null;let[t,...r]=e.split(";"),n=(t??"").indexOf("/");if(n===-1)return null;let s=(t??"").slice(0,n).trim().toLowerCase(),A=(t??"").slice(n+1).trim().toLowerCase();if(!rx.test(s)||!rx.test(A))return null;let o=A.lastIndexOf("+"),i=o===-1?null:A.slice(o+1),a=o===-1?A:A.slice(0,o);if(i==="")return null;let c=a.indexOf("."),l=c===-1?null:a.slice(0,c),u=l!==null&&EZ.has(l)?l:null,g=u===null?a:a.slice(u.length+1);if(g==="")return null;let h={};for(let f of r){let d=f.indexOf("=");if(d===-1)return null;let E=f.slice(0,d).trim().toLowerCase(),I=f.slice(d+1).trim();if(E==="")return null;if(I.startsWith('"')&&I.endsWith('"')&&I.length>=2)I=I.slice(1,-1);h[E]=I}return{parameters:h,subtype:g,suffix:i,tree:u,type:s}}function ox(e){if(typeof e!=="string"||e.trim()==="")return"expected a media type string";if(!e.includes("/"))return`"${e}" has no "/" — a media type is type/subtype (RFC 6838 §4.2)`;if(Ax(e)===null)return`"${e}" is not a well-formed media type (RFC 6838 §4.2)`;return null}function ix(e){let t=Ax(e);if(t===null)return null;let r=t.tree===null?"":`${t.tree}.`,n=t.suffix===null?"":`+${t.suffix}`;return`${t.type}/${r}${t.subtype}${n}`}var rx,EZ,nx="text/markdown; variant=GFM",sx="application/yaml",o3;var ax=P(()=>{rx=/^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$/,EZ=new Set(["vnd","prs","x"]);o3={".markdown":`${nx}; charset=utf-8`,".md":`${nx}; charset=utf-8`,".yaml":`${sx}; charset=utf-8`,".yml":`${sx}; charset=utf-8`}});class Bl{name;classPath;classDef;extensions;mediaType;mediaTypeEssence;documentKinds;exportTarget;remote;studio;project;server;connector;capabilities;#e;#t=null;constructor(e,t,r,n){this.name=e,this.classPath=t,this.classDef=r,this.#e=n;let{format:s}=r;this.extensions=(s?.extensions??[]).map((A)=>A.toLowerCase()),this.mediaType=s?.mediaType??null,this.mediaTypeEssence=ix(this.mediaType),this.documentKinds=s?.documentKinds??[],this.exportTarget=s?.exportTarget===!0,this.remote=s?.remote===!0,this.studio=r.$studio??null,this.project=r.project??null,this.server=r.server??null,this.connector=r.connector??null,this.capabilities=IZ(r)}implementation(){if(!this.#t){let e=this.classDef.$implementation;if(!e)return Promise.reject(Error(`Format class "${this.name}" has no $implementation to import`));this.#t=this.#e.importModule(this.#e.resolvePath(this.classPath,e))}return this.#t}async call(e,...t){let r=this.capabilities[e];if(!r)throw Error(`Format class "${this.name}" does not declare a "${e}" capability`);let n=await this.implementation(),s=this.classDef.title??this.name,A=n[s]??n.default?.[s]??n.default,o=A?.[r.identifier];if(typeof o!=="function")throw TypeError(`Format class "${this.name}": implementation export "${s}" has no static "${r.identifier}" method`);return await o.call(A,...t)}}class pl{#e;constructor(e){this.#e=e;for(let t of e){if(t.mediaType===null)continue;let r=ox(t.mediaType);if(r!==null)throw Error(`Format "${t.name}" declares an invalid mediaType: ${r}`)}for(let t of lx){let r=new Map;for(let n of e){if(!n.capabilities[t])continue;for(let s of n.extensions){let A=r.get(s);if(A)throw Error(`Format conflict: "${A.name}" and "${n.name}" both claim "${s}" with the "${t}" capability`);r.set(s,n)}}}}get entries(){return this.#e}byExtension(e,t){let r=cx(e);return this.#e.find((n)=>n.extensions.includes(r)&&(!t||n.capabilities[t]))}byName(e){return this.#e.find((t)=>t.name===e)}withCapability(e){return this.#e.filter((t)=>t.capabilities[e])}documentExtensions(e){let t=new Set;for(let r of this.#e){if(e&&!r.documentKinds.includes(e))continue;for(let n of r.extensions)t.add(n)}return t.delete(".json"),[...t]}has(e){let t=cx(e);return this.#e.some((r)=>r.extensions.includes(t))}}function IZ(e){let t={},r=e.$defs?.methods??{};for(let[n,s]of Object.entries(r)){let A=s.role;if(!A||!ux.includes(A))continue;let o={identifier:s.identifier??n,timing:s.timing??dZ};if(typeof s.discriminator==="string")o.discriminator=s.discriminator;t[A]=o}return t}function cx(e){let t=e.toLowerCase();return t.startsWith(".")?t:`.${t}`}var lx,ux,dZ;var HE=P(()=>{ax();lx=["parse","serialize","rewrite","discover","load"],ux=[...lx,"projectData","resolvePaths","lower","emit","head","assets","mount","dialect","deploySchema","bindings","testConnection"],dZ=["compiler","server"]});class gx{#e;#t;#r;constructor(e){this.#e=e,this.#t=e.flatMap((s)=>s.classes);let t=new Map;for(let s of e)for(let A of s.classes){let o=t.get(A.name);if(o&&o!==s.specifier)throw Error(`Extension conflict: "${o}" and "${s.specifier}" both provide a class named "${A.name}"`);t.set(A.name,s.specifier)}let r=new Map;for(let s of this.#t){if(!s.project)continue;let A=r.get(s.project.key);if(A)throw Error(`Extension conflict: "${A.name}" and "${s.name}" both claim the project section "${s.project.key}"`);r.set(s.project.key,s)}let n=new Map;for(let s of this.#t){if(!s.server)continue;let{basePath:A}=s.server;if(!A.startsWith("/_jx/"))throw Error(`Extension "${s.name}": server basePath "${A}" must be under /_jx/`);let o=n.get(A);if(o)throw Error(`Extension conflict: "${o.name}" and "${s.name}" both mount "${A}"`);n.set(A,s)}this.#r=new pl(this.#t.filter((s)=>s.extensions.length>0))}get extensions(){return this.#e}get classes(){return this.#t}get formats(){return this.#r}byName(e){return this.#t.find((t)=>t.name===e)}projectContributions(){return this.#t.filter((e)=>e.project!==null)}byProjectKey(e){return this.#t.find((t)=>t.project?.key===e)}byPathsDiscriminator(e){return this.#t.find((t)=>t.capabilities.resolvePaths?.discriminator===e)}emitters(){return this.#t.filter((e)=>e.capabilities.emit!==void 0)}headProviders(){return this.#t.filter((e)=>e.capabilities.head!==void 0)}assetProviders(){return this.#t.filter((e)=>e.capabilities.assets!==void 0)}serverMounts(){return this.#t.filter((e)=>e.server!==null).toSorted((e,t)=>(e.server?.order??100)-(t.server?.order??100)||e.name.localeCompare(t.name))}connectors(){return this.#t.filter((e)=>e.connector!==null)}schemaFragments(e){return this.#e.map((t)=>t.schemas[e]).filter((t)=>typeof t==="string")}}async function fx(e,t,r){let n=[];for(let s of e??[])n.push(await CZ(s,t,r));return new gx(n)}async function CZ(e,t,r){let n;if(e.startsWith("./")||e.startsWith("../")){let i=t.resolvePath(r,e);n=t.resolvePath(`${i}/package.json`,`./${Wi}`)}else try{n=t.resolvePath(r,`${e}/${Wi}`)}catch(i){throw Error(`Extension "${e}" is not resolvable: it must export ${Wi} (is the package installed, and does its exports map include it?): ${YE(i)}`,{cause:i})}let s;try{s=await t.loadJson(n)}catch(i){throw Error(`Extension "${e}": cannot read manifest ${n}: ${YE(i)}`,{cause:i})}if(!s||typeof s!=="object"||typeof s.name!=="string")throw Error(`Extension "${e}": ${Wi} must declare a "name"`);if(!e.startsWith(".")&&s.name!==e)throw Error(`Extension "${e}": manifest name "${s.name}" does not match the specifier`);let A=[];for(let[i,a]of Object.entries(s.classes??{})){let c=t.resolvePath(n,a),l;try{l=await t.loadJson(c)}catch(u){throw Error(`Extension "${e}": cannot read class "${i}" at ${c}: ${YE(u)}`,{cause:u})}A.push(new Bl(i,c,l,t))}let o={};if(s.schemas?.project)o.project=t.resolvePath(n,s.schemas.project);if(s.schemas?.document)o.document=t.resolvePath(n,s.schemas.document);if(s.schemas?.fields)o.fields=t.resolvePath(n,s.schemas.fields);return{specifier:e,manifestPath:n,manifest:s,classes:A,schemas:o}}function YE(e){return e instanceof Error?e.message:String(e)}var Wi="jx-extension.json";var hx=P(()=>{HE();HE()});import{readFileSync as QZ}from"node:fs";import{dirname as BZ,isAbsolute as pZ,resolve as JE,sep as yl}from"node:path";import{pathToFileURL as yZ}from"node:url";import{createRequire as Ex}from"node:module";async function mZ(e){let t=[e],r=`${yl}src${yl}`,n=`${yl}dist${yl}`;if(e.includes(r))t.push(e.replace(r,n));if(e.endsWith(".js"))t.push(`${e.slice(0,-3)}.ts`);let s;for(let A of t)try{return await import(yZ(A).href)}catch(o){s=o}throw s instanceof Error?s:Error(String(s))}function SZ(e){return{importModule:(t)=>mZ(t),loadJson:async(t)=>JSON.parse(QZ(t,"utf8")),resolvePath:(t,r)=>{if(r.startsWith("./")||r.startsWith("../"))return JE(BZ(t),r);if(pZ(r))return r;let n=Ex(JE(e,"package.json"));try{return n.resolve(r)}catch{return Ex(import.meta.url).resolve(r)}}}}async function C3(e,t){return fx(t?.extensions,SZ(e),JE(e,"project.json"))}function ml(e,t){return Error(`No format class registered for "${t}" (${e}). Enable an extension providing this format in project.json "extensions", e.g. "@jxsuite/parser".`)}var $E=P(()=>{hx()});async function Qx(e,t={}){let{resolveElementPath:r,$media:n,formats:s}=t,A=[],o=new Set;async function i(a,c){let l,u;if(typeof a==="string"){let{readFileSync:w}=await import("node:fs"),{resolve:B}=await import("node:path");if(u=c?B(c,a):B(a),o.has(u))return;if(o.add(u),u.endsWith(".json"))l=Ql(w(u,"utf8"),u);else{let{extname:S}=await import("node:path"),p=S(u).toLowerCase(),m=s?.byExtension?.(p,"parse");if(!m){await Promise.resolve().then(() => $E());throw ml(u,p)}l=await m.call("parse",w(u,"utf8"))}}else{if(l=a,u=null,l.tagName&&o.has(l.tagName))return;if(l.tagName)o.add(l.tagName)}let{tagName:g}=l;if(!g||!g.includes("-"))throw Error(`compileElement: tagName "${g}" must contain a hyphen`);let{dirname:h}=await import("node:path"),f=u?h(u):null,d=[];if(Array.isArray(l.$elements))for(let w of l.$elements){let B=ve(w)?w.$ref:w;if(typeof B!=="string")continue;if(f)await i(B,f);let S=r?r(B,f):B.replace(/\.json$/,".js");d.push(S)}let E=ua(g);if(n)l.$media={...n,...l.$media};let{rewriteSrc:I}=t,C=qi(l,E,d,I?(w)=>I(w,f):void 0,ea(l,t.defaults)),Q=u?u.replace(/\.json$/,".js"):`${g}.js`;A.push({content:C,path:Q,tagName:g})}return await i(e,t.basePath??null),{files:A}}async function wZ(e,t={}){let{title:r="Jx App",reactivitySrc:n="https://esm.sh/@vue/reactivity@3.5.13",litHtmlSrc:s="https://esm.sh/lit-html@3.3.0"}=t,A=await Qx(e,t),o=A.files.at(-1);if(!o)throw Error("compileElementPage: no element modules were produced");let{basename:i}=await import("node:path"),a=i(o.path),c=`<!DOCTYPE html>
+`,r:"\r",t:"\t"}});function hZ(e){return e instanceof Error?e.message:String(e)}function LE(e){if(typeof e==="string")return tx.test(e)?e.normalize("NFC"):e;if(Array.isArray(e))return e.map((t)=>LE(t));if(Ye(e)){let t={};for(let[r,n]of Object.entries(e))t[tx.test(r)?r.normalize("NFC"):r]=LE(n);return t}return e}function OE(e,t,r){let n;try{n=JSON.parse(e)}catch(A){throw Error(`Failed to parse ${r} at ${t}: ${hZ(A)}`,{cause:A})}if(!Ye(n))throw Error(`Invalid ${r} at ${t}: expected a JSON object`);let s=zb(e);if(s.length>0){let A=s.map((o)=>Xb(o)).join("; ");throw Error(`Invalid ${r} at ${t}: ${A}`)}return LE(n)}function Ql(e,t){return OE(e,t,"Jx document")}function n3(e,t){return OE(e,t,"project config")}function s3(e,t){return OE(e,t,"class definition")}var tx;var vE=P(()=>{xr();ex();tx=/[^\p{ASCII}]/u});function Ax(e){if(typeof e!=="string")return null;let[t,...r]=e.split(";"),n=(t??"").indexOf("/");if(n===-1)return null;let s=(t??"").slice(0,n).trim().toLowerCase(),A=(t??"").slice(n+1).trim().toLowerCase();if(!rx.test(s)||!rx.test(A))return null;let o=A.lastIndexOf("+"),i=o===-1?null:A.slice(o+1),a=o===-1?A:A.slice(0,o);if(i==="")return null;let c=a.indexOf("."),l=c===-1?null:a.slice(0,c),u=l!==null&&EZ.has(l)?l:null,g=u===null?a:a.slice(u.length+1);if(g==="")return null;let h={};for(let f of r){let d=f.indexOf("=");if(d===-1)return null;let E=f.slice(0,d).trim().toLowerCase(),I=f.slice(d+1).trim();if(E==="")return null;if(I.startsWith('"')&&I.endsWith('"')&&I.length>=2)I=I.slice(1,-1);h[E]=I}return{parameters:h,subtype:g,suffix:i,tree:u,type:s}}function ox(e){if(typeof e!=="string"||e.trim()==="")return"expected a media type string";if(!e.includes("/"))return`"${e}" has no "/" — a media type is type/subtype (RFC 6838 §4.2)`;if(Ax(e)===null)return`"${e}" is not a well-formed media type (RFC 6838 §4.2)`;return null}function ix(e){let t=Ax(e);if(t===null)return null;let r=t.tree===null?"":`${t.tree}.`,n=t.suffix===null?"":`+${t.suffix}`;return`${t.type}/${r}${t.subtype}${n}`}var rx,EZ,nx="text/markdown; variant=GFM",sx="application/yaml",o3;var ax=P(()=>{rx=/^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$/,EZ=new Set(["vnd","prs","x"]);o3={".markdown":`${nx}; charset=utf-8`,".md":`${nx}; charset=utf-8`,".yaml":`${sx}; charset=utf-8`,".yml":`${sx}; charset=utf-8`}});class Bl{name;classPath;classDef;extensions;mediaType;mediaTypeEssence;documentKinds;exportTarget;remote;studio;project;server;connector;capabilities;#e;#t=null;constructor(e,t,r,n){this.name=e,this.classPath=t,this.classDef=r,this.#e=n;let{format:s}=r;this.extensions=(s?.extensions??[]).map((A)=>A.toLowerCase()),this.mediaType=s?.mediaType??null,this.mediaTypeEssence=ix(this.mediaType),this.documentKinds=s?.documentKinds??[],this.exportTarget=s?.exportTarget===!0,this.remote=s?.remote===!0,this.studio=r.$studio??null,this.project=r.project??null,this.server=r.server??null,this.connector=r.connector??null,this.capabilities=IZ(r)}implementation(){if(!this.#t){let e=this.classDef.$implementation;if(!e)return Promise.reject(Error(`Format class "${this.name}" has no $implementation to import`));this.#t=this.#e.importModule(this.#e.resolvePath(this.classPath,e))}return this.#t}async call(e,...t){let r=this.capabilities[e];if(!r)throw Error(`Format class "${this.name}" does not declare a "${e}" capability`);let n=await this.implementation(),s=this.classDef.title??this.name,A=n[s]??n.default?.[s]??n.default,o=A?.[r.identifier];if(typeof o!=="function")throw TypeError(`Format class "${this.name}": implementation export "${s}" has no static "${r.identifier}" method`);return await o.call(A,...t)}}class pl{#e;constructor(e){this.#e=e;for(let t of e){if(t.mediaType===null)continue;let r=ox(t.mediaType);if(r!==null)throw Error(`Format "${t.name}" declares an invalid mediaType: ${r}`)}for(let t of lx){let r=new Map;for(let n of e){if(!n.capabilities[t])continue;for(let s of n.extensions){let A=r.get(s);if(A)throw Error(`Format conflict: "${A.name}" and "${n.name}" both claim "${s}" with the "${t}" capability`);r.set(s,n)}}}}get entries(){return this.#e}byExtension(e,t){let r=cx(e);return this.#e.find((n)=>n.extensions.includes(r)&&(!t||n.capabilities[t]))}byName(e){return this.#e.find((t)=>t.name===e)}withCapability(e){return this.#e.filter((t)=>t.capabilities[e])}documentExtensions(e){let t=new Set;for(let r of this.#e){if(e&&!r.documentKinds.includes(e))continue;for(let n of r.extensions)t.add(n)}return t.delete(".json"),[...t]}has(e){let t=cx(e);return this.#e.some((r)=>r.extensions.includes(t))}}function IZ(e){let t={},r=e.$defs?.methods??{};for(let[n,s]of Object.entries(r)){let A=s.role;if(!A||!ux.includes(A))continue;let o={identifier:s.identifier??n,timing:s.timing??dZ};if(typeof s.discriminator==="string")o.discriminator=s.discriminator;t[A]=o}return t}function cx(e){let t=e.toLowerCase();return t.startsWith(".")?t:`.${t}`}var lx,ux,dZ;var HE=P(()=>{ax();lx=["parse","serialize","rewrite","discover","load"],ux=[...lx,"projectData","resolvePaths","lower","emit","head","assets","mount","dialect","deploySchema","bindings","testConnection"],dZ=["compiler","server"]});class gx{#e;#t;#r;constructor(e){this.#e=e,this.#t=e.flatMap((s)=>s.classes);let t=new Map;for(let s of e)for(let A of s.classes){let o=t.get(A.name);if(o&&o!==s.specifier)throw Error(`Extension conflict: "${o}" and "${s.specifier}" both provide a class named "${A.name}"`);t.set(A.name,s.specifier)}let r=new Map;for(let s of this.#t){if(!s.project)continue;let A=r.get(s.project.key);if(A)throw Error(`Extension conflict: "${A.name}" and "${s.name}" both claim the project section "${s.project.key}"`);r.set(s.project.key,s)}let n=new Map;for(let s of this.#t){if(!s.server)continue;let{basePath:A}=s.server;if(!A.startsWith("/_jx/"))throw Error(`Extension "${s.name}": server basePath "${A}" must be under /_jx/`);let o=n.get(A);if(o)throw Error(`Extension conflict: "${o.name}" and "${s.name}" both mount "${A}"`);n.set(A,s)}this.#r=new pl(this.#t.filter((s)=>s.extensions.length>0))}get extensions(){return this.#e}get classes(){return this.#t}get formats(){return this.#r}byName(e){return this.#t.find((t)=>t.name===e)}projectContributions(){return this.#t.filter((e)=>e.project!==null)}byProjectKey(e){return this.#t.find((t)=>t.project?.key===e)}byPathsDiscriminator(e){return this.#t.find((t)=>t.capabilities.resolvePaths?.discriminator===e)}emitters(){return this.#t.filter((e)=>e.capabilities.emit!==void 0)}headProviders(){return this.#t.filter((e)=>e.capabilities.head!==void 0)}assetProviders(){return this.#t.filter((e)=>e.capabilities.assets!==void 0)}serverMounts(){return this.#t.filter((e)=>e.server!==null).toSorted((e,t)=>(e.server?.order??100)-(t.server?.order??100)||e.name.localeCompare(t.name))}connectors(){return this.#t.filter((e)=>e.connector!==null)}schemaFragments(e){return this.#e.map((t)=>t.schemas[e]).filter((t)=>typeof t==="string")}}async function fx(e,t,r){let n=[];for(let s of e??[])n.push(await CZ(s,t,r));return new gx(n)}async function CZ(e,t,r){let n;if(e.startsWith("./")||e.startsWith("../")){let i=t.resolvePath(r,e);n=t.resolvePath(`${i}/package.json`,`./${Wi}`)}else try{n=t.resolvePath(r,`${e}/${Wi}`)}catch(i){throw Error(`Extension "${e}" is not resolvable: it must export ${Wi} (is the package installed, and does its exports map include it?): ${YE(i)}`,{cause:i})}let s;try{s=await t.loadJson(n)}catch(i){throw Error(`Extension "${e}": cannot read manifest ${n}: ${YE(i)}`,{cause:i})}if(!s||typeof s!=="object"||typeof s.name!=="string")throw Error(`Extension "${e}": ${Wi} must declare a "name"`);if(!e.startsWith(".")&&s.name!==e)throw Error(`Extension "${e}": manifest name "${s.name}" does not match the specifier`);let A=[];for(let[i,a]of Object.entries(s.classes??{})){let c=t.resolvePath(n,a),l;try{l=await t.loadJson(c)}catch(u){throw Error(`Extension "${e}": cannot read class "${i}" at ${c}: ${YE(u)}`,{cause:u})}A.push(new Bl(i,c,l,t))}let o={};if(s.schemas?.project)o.project=t.resolvePath(n,s.schemas.project);if(s.schemas?.document)o.document=t.resolvePath(n,s.schemas.document);if(s.schemas?.fields)o.fields=t.resolvePath(n,s.schemas.fields);return{specifier:e,manifestPath:n,manifest:s,classes:A,schemas:o}}function YE(e){return e instanceof Error?e.message:String(e)}var Wi="jx-extension.json";var hx=P(()=>{HE();HE()});import{readFileSync as QZ}from"node:fs";import{dirname as BZ,isAbsolute as pZ,resolve as JE,sep as yl}from"node:path";import{pathToFileURL as yZ}from"node:url";import{createRequire as Ex}from"node:module";async function mZ(e){let t=[e],r=`${yl}src${yl}`,n=`${yl}dist${yl}`;if(e.includes(r)){let A=e.replace(r,n);if(t.push(A),A.endsWith(".ts"))t.push(`${A.slice(0,-3)}.js`)}if(e.endsWith(".js"))t.push(`${e.slice(0,-3)}.ts`);let s;for(let A of t)try{return await import(yZ(A).href)}catch(o){s=o}throw s instanceof Error?s:Error(String(s))}function SZ(e){return{importModule:(t)=>mZ(t),loadJson:async(t)=>JSON.parse(QZ(t,"utf8")),resolvePath:(t,r)=>{if(r.startsWith("./")||r.startsWith("../"))return JE(BZ(t),r);if(pZ(r))return r;let n=Ex(JE(e,"package.json"));try{return n.resolve(r)}catch{return Ex(import.meta.url).resolve(r)}}}}async function C3(e,t){return fx(t?.extensions,SZ(e),JE(e,"project.json"))}function ml(e,t){return Error(`No format class registered for "${t}" (${e}). Enable an extension providing this format in project.json "extensions", e.g. "@jxsuite/parser".`)}var $E=P(()=>{hx()});async function Qx(e,t={}){let{resolveElementPath:r,$media:n,formats:s}=t,A=[],o=new Set;async function i(a,c){let l,u;if(typeof a==="string"){let{readFileSync:w}=await import("node:fs"),{resolve:B}=await import("node:path");if(u=c?B(c,a):B(a),o.has(u))return;if(o.add(u),u.endsWith(".json"))l=Ql(w(u,"utf8"),u);else{let{extname:S}=await import("node:path"),p=S(u).toLowerCase(),m=s?.byExtension?.(p,"parse");if(!m){await Promise.resolve().then(() => $E());throw ml(u,p)}l=await m.call("parse",w(u,"utf8"))}}else{if(l=a,u=null,l.tagName&&o.has(l.tagName))return;if(l.tagName)o.add(l.tagName)}let{tagName:g}=l;if(!g||!g.includes("-"))throw Error(`compileElement: tagName "${g}" must contain a hyphen`);let{dirname:h}=await import("node:path"),f=u?h(u):null,d=[];if(Array.isArray(l.$elements))for(let w of l.$elements){let B=ve(w)?w.$ref:w;if(typeof B!=="string")continue;if(f)await i(B,f);let S=r?r(B,f):B.replace(/\.json$/,".js");d.push(S)}let E=ua(g);if(n)l.$media={...n,...l.$media};let{rewriteSrc:I}=t,C=qi(l,E,d,I?(w)=>I(w,f):void 0,ea(l,t.defaults)),Q=u?u.replace(/\.json$/,".js"):`${g}.js`;A.push({content:C,path:Q,tagName:g})}return await i(e,t.basePath??null),{files:A}}async function wZ(e,t={}){let{title:r="Jx App",reactivitySrc:n="https://esm.sh/@vue/reactivity@3.5.13",litHtmlSrc:s="https://esm.sh/lit-html@3.3.0"}=t,A=await Qx(e,t),o=A.files.at(-1);if(!o)throw Error("compileElementPage: no element modules were produced");let{basename:i}=await import("node:path"),a=i(o.path),c=`<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "5.0.0",
+  "version": "5.1.1",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {

package/src/site/format-host.ts

@@ -22,7 +22,9 @@ export type { FormatRegistry, FormatEntry } from "@jxsuite/schema/format-registr
  * Import a class $implementation module by absolute path, tolerating source-vs-built layouts. A
  * `.class.json` typically declares `"$implementation": "./markdown.js"` next to its TypeScript
  * source: under Bun the sibling `.ts` resolves directly, while under node the built module lives in
- * the package's `dist/` directory. Tries, in order: the literal path, src/ → dist/, .js → .ts.
+ * the package's `dist/` directory. Tries, in order: the literal path, src/ → dist/, that same file
+ * with its `.ts` extension read as `.js` (a descriptor that names its TypeScript source, whose
+ * built module is JavaScript), and .js → .ts.
  *
  * @param {string} path - Absolute path to the implementation module
  * @returns {Promise<Record<string, unknown>>}
@@ -32,7 +34,11 @@ export async function importImplementation(path: string): Promise<Record<string,
   const srcSeg = `${sep}src${sep}`;
   const distSeg = `${sep}dist${sep}`;
   if (path.includes(srcSeg)) {
-    candidates.push(path.replace(srcSeg, distSeg));
+    const built = path.replace(srcSeg, distSeg);
+    candidates.push(built);
+    if (built.endsWith(".ts")) {
+      candidates.push(`${built.slice(0, -3)}.js`);
+    }
   }
   if (path.endsWith(".js")) {
     candidates.push(`${path.slice(0, -3)}.ts`);

package/src/site/i18n.ts

@@ -20,6 +20,8 @@ import {
 } from "@jxsuite/schema/locale";
 import type { ResolvedI18n, TextDirection } from "@jxsuite/schema/locale";
 
+import { servedRoute } from "./static-host.ts";
+
 /*
  * `resolveI18n` and the two types beside it live in `@jxsuite/schema/locale` rather than here.
  * Studio needs the same answer and cannot import this package — there is no `./site/i18n` export,
@@ -278,12 +280,15 @@ export function translationSets(
  * @param {readonly TranslationRoute[]} routes - Concrete routes only
  * @param {ResolvedI18n | null} i18n
  * @param {string} siteUrl - Absolute site URL; alternates must be absolute
+ * @param {string} [trailingSlash] - `build.trailingSlash`: the alternates name the URL the host
+ *   serves, so they agree with the canonical link and the sitemap
  * @returns {Map<string, LocaleAlternate[]>} Keyed by `urlPattern`
  */
 export function localeAlternates(
   routes: readonly TranslationRoute[],
   i18n: ResolvedI18n | null,
   siteUrl: string,
+  trailingSlash?: string,
 ): Map<string, LocaleAlternate[]> {
   const out = new Map<string, LocaleAlternate[]>();
   if (i18n === null || siteUrl === "") {
@@ -299,13 +304,13 @@ export function localeAlternates(
     let alternates = built.get(members);
     if (alternates === undefined) {
       alternates = members.map((m) => ({
-        href: siteAbsoluteUrl(m.urlPattern, siteUrl),
+        href: siteAbsoluteUrl(servedRoute(m.urlPattern, trailingSlash), siteUrl),
         hreflang: m.locale,
       }));
       const fallback = members.find((m) => m.locale === i18n.defaultLocale);
       if (fallback !== undefined) {
         alternates.push({
-          href: siteAbsoluteUrl(fallback.urlPattern, siteUrl),
+          href: siteAbsoluteUrl(servedRoute(fallback.urlPattern, trailingSlash), siteUrl),
           hreflang: "x-default",
         });
       }

package/src/site/site-build.ts

@@ -39,6 +39,7 @@ import {
   resolveSidecarEntry,
 } from "./bundler.ts";
 import { loadProjectConfig } from "./site-loader.ts";
+import type { ResolvedProjectConfig } from "./site-loader.ts";
 import {
   discoverPages,
   expandDynamicRoutes,
@@ -95,6 +96,13 @@ import {
   registrationScript,
   tombstoneServiceWorker,
 } from "./service-worker.ts";
+import {
+  htmlDeclaresNoindex,
+  isNotFoundRoute,
+  outputUrlPath,
+  servedRoute,
+  withAlternateLink,
+} from "./static-host.ts";
 import {
   buildManifest,
   buildSecurityTxt,
@@ -579,7 +587,7 @@ export async function buildSite(
     translationKey: declaredKeys.get(r.urlPattern),
     urlPattern: r.urlPattern,
   }));
-  const alternateMap = localeAlternates(keyedRoutes, i18n, siteUrl ?? "");
+  const alternateMap = localeAlternates(keyedRoutes, i18n, siteUrl ?? "", trailingSlash);
   /*
    * The same sets, site-absolute, for `$page.alternates`. Computed from the whole table for the
    * same reason the alternates are — and separately from them because a switcher must work in a
@@ -745,16 +753,16 @@ export async function buildSite(
       // Determine output path
       const outPath = routeToOutputPath(route.urlPattern, outDir, trailingSlash);
       mkdirSync(dirname(outPath), { recursive: true });
-      /* Last, after the scans above: they ask what this page REFERENCES, and the answer is a
-         build-output path, not a deployed URL. Re-rooting first would make every one of them miss. */
-      writeFileSync(outPath, rewriteHtmlBase(result.html, basePath), "utf8");
-      fileCount += 1;
-
       // Record a sitemap entry for this concrete page (skip unexpanded dynamic routes and
       // Pages that opted out via $sitemap: false). <loc> is built like the canonical URL so
       // The two always agree.
       const isConcrete = !route.urlPattern.includes(":") && !route.urlPattern.includes("*");
-      if (sitemapEnabled && !result.excludeFromSitemap && isConcrete) {
+      /*
+       * A page the sitemap would list and the page itself disowns sends two answers to one question,
+       * so a page that asks crawlers for `noindex` is left out, and so is the not-found page.
+       */
+      const indexable = !isNotFoundRoute(route.urlPattern) && !htmlDeclaresNoindex(result.html);
+      if (sitemapEnabled && !result.excludeFromSitemap && indexable && isConcrete) {
         const routeAlternates = alternateMap.get(route.urlPattern) ?? [];
         sitemapEntries.push({
           /*
@@ -768,14 +776,20 @@ export async function buildSite(
             typeof route.sourceMtime === "string" && route.sourceMtime !== ""
               ? route.sourceMtime
               : toRfc3339(statSync(route.sourcePath).mtime),
-          loc: siteAbsoluteUrl(route.urlPattern, siteUrl),
+          loc: siteAbsoluteUrl(servedRoute(route.urlPattern, trailingSlash), siteUrl),
           ...(routeAlternates.length > 0 && { alternates: routeAlternates }),
         });
       }
 
-      // Write serialized export sidecars alongside HTML (formats with exportTarget: true)
+      /*
+       * Serialize the export sidecars (formats with exportTarget: true, e.g. Markdown) BEFORE the page
+       * is written, so its `<head>` advertises exactly the twins that exist: a link to a file the
+       * build did not write is worse than no link. The not-found page has none: it is served for
+       * whatever URL was mistyped, so there is nothing for a twin to be a twin of.
+       */
+      const sidecars: { content: string; path: string; type: string | null }[] = [];
       for (const fmt of formatRegistry.withCapability("serialize")) {
-        if (!fmt.exportTarget) {
+        if (!fmt.exportTarget || isNotFoundRoute(route.urlPattern)) {
           continue;
         }
         try {
@@ -793,14 +807,30 @@ export async function buildSite(
           })) as string;
           if (content) {
             const sidecarPath = outPath.replace(/\.html$/, fmt.extensions[0]!);
-            writeFileSync(sidecarPath, content, "utf8");
-            fileCount += 1;
+            sidecars.push({ content, path: sidecarPath, type: fmt.mediaTypeEssence });
           }
         } catch (error) {
           const err = error as Error;
           errors.push(`Error exporting ${fmt.name} for ${route.urlPattern}: ${err.message}`);
         }
       }
+      for (const sidecar of sidecars) {
+        if (sidecar.type !== null) {
+          result.html = withAlternateLink(result.html, {
+            href: outputUrlPath(outDir, sidecar.path),
+            type: sidecar.type,
+          });
+        }
+      }
+
+      /* Last, after the scans above: they ask what this page REFERENCES, and the answer is a
+         build-output path, not a deployed URL. Re-rooting first would make every one of them miss. */
+      writeFileSync(outPath, rewriteHtmlBase(result.html, basePath), "utf8");
+      fileCount += 1;
+      for (const sidecar of sidecars) {
+        writeFileSync(sidecar.path, sidecar.content, "utf8");
+        fileCount += 1;
+      }
 
       // Write any additional files (island modules, etc.)
       for (const file of result.files) {
@@ -1239,7 +1269,7 @@ export async function buildSite(
  */
 async function compilePage(
   route: SiteRoute,
-  projectConfig: ProjectConfig,
+  projectConfig: ResolvedProjectConfig,
   projectRoot: string,
   sections: Record<string, unknown>,
   imageCache: CacheManifest | null,
@@ -1427,7 +1457,14 @@ async function compilePage(
     ...(projectConfig.name != null && { siteName: projectConfig.name }),
     ...(projectConfig.url != null && { siteUrl: projectConfig.url }),
     ...(locale.alternates.length > 0 && { alternates: locale.alternates }),
-    pageUrl: route.urlPattern,
+    /*
+     * The canonical link and og:url name the URL the host answers with the page: the route as
+     * `build.trailingSlash` serves it. The not-found page gets neither, since the URL it answers at
+     * is whatever the visitor mistyped.
+     */
+    ...(!isNotFoundRoute(route.urlPattern) && {
+      pageUrl: servedRoute(route.urlPattern, projectConfig.build.trailingSlash),
+    }),
   });
 
   // Merge project-level $media into the layout document so responsive queries are available
@@ -2400,7 +2437,7 @@ function injectHead(
  * Convert a URL pattern to an output file path.
  *
  * "/" → dist/index.html "/about" → dist/about/index.html (with trailingSlash: "always")
- * "/blog/hello" → dist/blog/hello/index.html
+ * "/blog/hello" → dist/blog/hello/index.html "/404" → dist/404.html
  *
  * @param {string} urlPattern
  * @param {string} outDir
@@ -2412,6 +2449,12 @@ function routeToOutputPath(urlPattern: string, outDir: string, trailingSlash: st
     return join(outDir, "index.html");
   }
 
+  // The not-found page is the one file a static host looks for by name (specs/site-architecture.md
+  // §8.4.2), whatever the trailingSlash setting.
+  if (isNotFoundRoute(urlPattern)) {
+    return join(outDir, "404.html");
+  }
+
   // Remove leading slash
   const segments = urlPattern.replace(/^\//, "");
 

package/src/site/static-host.ts

@@ -0,0 +1,153 @@
+/**
+ * What a static host and a crawler are told about each page, decided in one place.
+ *
+ * Four facts, each of which the build used to leave to the author or get wrong:
+ *
+ * - The path a host serves a route at, which `build.trailingSlash` decides, so the canonical link,
+ *   `og:url`, the sitemap `<loc>` and the `hreflang` alternates name the URL that answers with the
+ *   page and not one that redirects to it ({@link servedRoute});
+ * - Which route is the site's not-found page ({@link isNotFoundRoute}), which hosts expect at
+ *   `/404.html` and which is never a page to index;
+ * - Whether a built page asks crawlers not to index it ({@link htmlDeclaresNoindex}), because a
+ *   sitemap that lists a page the page itself disowns sends two answers to the same question;
+ * - Where a page's machine-readable twin lives, and the `<link rel="alternate">` that tells a reader
+ *   of the HTML about it ({@link withAlternateLink}), because a file nothing points to is a file
+ *   nobody finds.
+ *
+ * @docs framework/site/deployment
+ * @docs framework/agents/machine-readable
+ */
+
+import { relative, sep } from "node:path";
+import { escapeHtml } from "../shared.ts";
+
+/**
+ * The route of the site's not-found page, written to `404.html` (specs/site-architecture.md
+ * §8.4.2).
+ */
+export const NOT_FOUND_ROUTE = "/404";
+
+/** Whether `urlPattern` is the site's not-found page. */
+export function isNotFoundRoute(urlPattern: string): boolean {
+  return urlPattern === NOT_FOUND_ROUTE;
+}
+
+/**
+ * The path a host serves `urlPattern` at, given `build.trailingSlash`.
+ *
+ * `"always"` writes `/about` as `about/index.html`, which hosts serve at `/about/` and answer
+ * `/about` with a redirect to it; `"never"` writes `about.html`, served at `/about`. The root is
+ * `/` either way, and any other setting leaves the route as written.
+ *
+ * @param {string} urlPattern - A concrete route (`/about`, `/kb/a/b`)
+ * @param {string} [trailingSlash] - `build.trailingSlash`
+ * @returns {string} The route as the host serves it
+ */
+export function servedRoute(urlPattern: string, trailingSlash?: string): string {
+  if (urlPattern === "/") {
+    return "/";
+  }
+  if (trailingSlash === "always") {
+    return urlPattern.endsWith("/") ? urlPattern : `${urlPattern}/`;
+  }
+  if (trailingSlash === "never") {
+    return urlPattern.replace(/\/+$/, "") || "/";
+  }
+  return urlPattern;
+}
+
+/** The value of one attribute in a start tag, quoted either way or bare; `null` when absent. */
+function attributeOf(tag: string, name: string): string | null {
+  const match = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`, "i").exec(
+    tag,
+  );
+  return match === null ? null : (match[1] ?? match[2] ?? match[3] ?? "");
+}
+
+/**
+ * Whether the `<head>` of a built page carries `<meta name="robots">` with `noindex` (or `none`,
+ * which means `noindex, nofollow`). Reads the finished HTML, like the CSP scan: a page can set the
+ * tag from a layout, a state entry or `$head`, and only the output says what it ended up with.
+ *
+ * @param {string} html - A built page
+ * @returns {boolean} True when crawlers are asked to leave the page out of their index
+ */
+export function htmlDeclaresNoindex(html: string): boolean {
+  const end = html.search(/<\/head\s*>/i);
+  const head = end === -1 ? html : html.slice(0, end);
+  for (const [tag] of head.matchAll(/<meta\b[^>]*>/gi)) {
+    if (attributeOf(tag, "name")?.trim().toLowerCase() !== "robots") {
+      continue;
+    }
+    const directives = new Set(
+      (attributeOf(tag, "content") ?? "")
+        .toLowerCase()
+        .split(",")
+        .map((part) => part.trim()),
+    );
+    if (directives.has("noindex") || directives.has("none")) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** The `<head>` of a built page, or the whole string when it has no closing tag. */
+function headOf(html: string): { head: string; end: number } {
+  const end = html.search(/<\/head\s*>/i);
+  return { end, head: end === -1 ? html : html.slice(0, end) };
+}
+
+/**
+ * Whether a page's `<head>` already has a `<link rel="alternate">` of this media type, one the
+ * author wrote or an earlier step added. `type` is compared by essence and without regard to case.
+ *
+ * @param {string} html - A built page
+ * @param {string} type - A media type essence, `text/markdown`
+ * @returns {boolean} True when the page already advertises an alternate of that type
+ */
+export function hasAlternateLink(html: string, type: string): boolean {
+  const wanted = type.trim().toLowerCase();
+  for (const [tag] of headOf(html).head.matchAll(/<link\b[^>]*>/gi)) {
+    const rel = (attributeOf(tag, "rel") ?? "").toLowerCase().split(/\s+/);
+    const linked = (attributeOf(tag, "type") ?? "").split(";")[0]?.trim().toLowerCase();
+    if (rel.includes("alternate") && linked === wanted) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Adds `<link rel="alternate" type="…" href="…">` to the end of a built page's `<head>`, unless the
+ * page already has an alternate of that type (an author's own wins, like every auto-injected entry,
+ * specs/site-architecture.md §8.4) or has no `<head>` to put it in.
+ *
+ * This is the discovery mechanism the llms.txt proposal recommends for a Markdown twin
+ * (`rel="alternate" type="text/markdown"`): the twin's URL is not one a reader can guess, and
+ * `/templates/` is not `/templates/index.md` to anyone who has not been told.
+ *
+ * @param {string} html - A built page
+ * @param {{ href: string; type: string }} link - Site-absolute `href`, and the media type essence
+ * @returns {string} The page, with the link when it was needed
+ */
+export function withAlternateLink(html: string, link: { href: string; type: string }): string {
+  const { end } = headOf(html);
+  if (end === -1 || hasAlternateLink(html, link.type)) {
+    return html;
+  }
+  const tag = `<link href="${escapeHtml(link.href)}" rel="alternate" type="${escapeHtml(link.type)}">`;
+  return `${html.slice(0, end)}${tag}\n${html.slice(end)}`;
+}
+
+/**
+ * The site-absolute URL path a file in the build output is served at, percent-encoded the way a
+ * `<link href>` and a canonical URL are (`/kb/a b/index.md` is `/kb/a%20b/index.md`).
+ *
+ * @param {string} outDir - The build output directory
+ * @param {string} file - A file inside it
+ * @returns {string} `/templates/index.md`
+ */
+export function outputUrlPath(outDir: string, file: string): string {
+  return new URL(`/${relative(outDir, file).split(sep).join("/")}`, "http://localhost").pathname;
+}