@jxsuite/compiler 1.3.0 → 1.4.0

package/dist/compiler.js

@@ -90,7 +90,7 @@ app.post('${X}/${Z}', async (c) => {
   } catch (e) {
     return c.json({ ok: false, error: e?.message ?? 'Server error' }, 500)
   }
-})`}var u8=c(()=>{e4();X0()});function sZ(Z){return Z instanceof Error?Z.message:String(Z)}function f8(Z,X,W){let G;try{G=JSON.parse(Z)}catch(Q){throw Error(`Failed to parse ${W} at ${X}: ${sZ(Q)}`,{cause:Q})}if(!F2(G))throw Error(`Invalid ${W} at ${X}: expected a JSON object`);return G}function w1(Z,X){return f8(Z,X,"Jx document")}function vX(Z,X){return f8(Z,X,"project config")}function yX(Z,X){return f8(Z,X,"class definition")}var c8=c(()=>{o2()});class O1{name;classPath;classDef;extensions;mediaType;documentKinds;exportTarget;remote;studio;project;server;connector;capabilities;#X;#Z=null;constructor(Z,X,W,G){this.name=Z,this.classPath=X,this.classDef=W,this.#X=G;let{format:Q}=W;this.extensions=(Q?.extensions??[]).map((J)=>J.toLowerCase()),this.mediaType=Q?.mediaType??null,this.documentKinds=Q?.documentKinds??[],this.exportTarget=Q?.exportTarget===!0,this.remote=Q?.remote===!0,this.studio=W.$studio??null,this.project=W.project??null,this.server=W.server??null,this.connector=W.connector??null,this.capabilities=tZ(W)}implementation(){if(!this.#Z){let Z=this.classDef.$implementation;if(!Z)return Promise.reject(Error(`Format class "${this.name}" has no $implementation to import`));this.#Z=this.#X.importModule(this.#X.resolvePath(this.classPath,Z))}return this.#Z}async call(Z,...X){let W=this.capabilities[Z];if(!W)throw Error(`Format class "${this.name}" does not declare a "${Z}" capability`);let G=await this.implementation(),Q=this.classDef.title??this.name,J=G[Q]??G.default?.[Q]??G.default,U=J?.[W.identifier];if(typeof U!=="function")throw TypeError(`Format class "${this.name}": implementation export "${Q}" has no static "${W.identifier}" method`);return await U.call(J,...X)}}class T1{#X;constructor(Z){this.#X=Z;for(let X of z6){let W=new Map;for(let G of Z){if(!G.capabilities[X])continue;for(let Q of G.extensions){let J=W.get(Q);if(J)throw Error(`Format conflict: "${J.name}" and "${G.name}" both claim "${Q}" with the "${X}" capability`);W.set(Q,G)}}}}get entries(){return this.#X}byExtension(Z,X){let W=X6(Z);return this.#X.find((G)=>G.extensions.includes(W)&&(!X||G.capabilities[X]))}byName(Z){return this.#X.find((X)=>X.name===Z)}withCapability(Z){return this.#X.filter((X)=>X.capabilities[Z])}documentExtensions(Z){let X=new Set;for(let W of this.#X){if(Z&&!W.documentKinds.includes(Z))continue;for(let G of W.extensions)X.add(G)}return X.delete(".json"),[...X]}has(Z){let X=X6(Z);return this.#X.some((W)=>W.extensions.includes(X))}}function tZ(Z){let X={},W=Z.$defs?.methods??{};for(let[G,Q]of Object.entries(W)){let J=Q.role;if(!J||!W6.includes(J))continue;let U={identifier:Q.identifier??G,timing:Q.timing??aZ};if(typeof Q.discriminator==="string")U.discriminator=Q.discriminator;X[J]=U}return X}function X6(Z){let X=Z.toLowerCase();return X.startsWith(".")?X:`.${X}`}var z6,W6,aZ;var d8=c(()=>{z6=["parse","serialize","discover","load"],W6=[...z6,"projectData","resolvePaths","lower","emit","mount","dialect","deploySchema","bindings","testConnection"],aZ=["compiler","server"]});class G6{#X;#Z;#z;constructor(Z){this.#X=Z,this.#Z=Z.flatMap((Q)=>Q.classes);let X=new Map;for(let Q of Z)for(let J of Q.classes){let U=X.get(J.name);if(U&&U!==Q.specifier)throw Error(`Extension conflict: "${U}" and "${Q.specifier}" both provide a class named "${J.name}"`);X.set(J.name,Q.specifier)}let W=new Map;for(let Q of this.#Z){if(!Q.project)continue;let J=W.get(Q.project.key);if(J)throw Error(`Extension conflict: "${J.name}" and "${Q.name}" both claim the project section "${Q.project.key}"`);W.set(Q.project.key,Q)}let G=new Map;for(let Q of this.#Z){if(!Q.server)continue;let{basePath:J}=Q.server;if(!J.startsWith("/_jx/"))throw Error(`Extension "${Q.name}": server basePath "${J}" must be under /_jx/`);let U=G.get(J);if(U)throw Error(`Extension conflict: "${U.name}" and "${Q.name}" both mount "${J}"`);G.set(J,Q)}this.#z=new T1(this.#Z.filter((Q)=>Q.extensions.length>0))}get extensions(){return this.#X}get classes(){return this.#Z}get formats(){return this.#z}byName(Z){return this.#Z.find((X)=>X.name===Z)}projectContributions(){return this.#Z.filter((Z)=>Z.project!==null)}byProjectKey(Z){return this.#Z.find((X)=>X.project?.key===Z)}byPathsDiscriminator(Z){return this.#Z.find((X)=>X.capabilities.resolvePaths?.discriminator===Z)}emitters(){return this.#Z.filter((Z)=>Z.capabilities.emit!==void 0)}serverMounts(){return this.#Z.filter((Z)=>Z.server!==null).toSorted((Z,X)=>(Z.server?.order??100)-(X.server?.order??100)||Z.name.localeCompare(X.name))}connectors(){return this.#Z.filter((Z)=>Z.connector!==null)}schemaFragments(Z){return this.#X.map((X)=>X.schemas[Z]).filter((X)=>typeof X==="string")}}async function Q6(Z,X,W){let G=[];for(let Q of Z??[])G.push(await eZ(Q,X,W));return new G6(G)}async function eZ(Z,X,W){let G;if(Z.startsWith("./")||Z.startsWith("../")){let K=X.resolvePath(W,Z);G=X.resolvePath(`${K}/package.json`,`./${_1}`)}else try{G=X.resolvePath(W,`${Z}/${_1}`)}catch(K){throw Error(`Extension "${Z}" is not resolvable: it must export ${_1} (is the package installed, and does its exports map include it?): ${p8(K)}`,{cause:K})}let Q;try{Q=await X.loadJson(G)}catch(K){throw Error(`Extension "${Z}": cannot read manifest ${G}: ${p8(K)}`,{cause:K})}if(!Q||typeof Q!=="object"||typeof Q.name!=="string")throw Error(`Extension "${Z}": ${_1} must declare a "name"`);if(!Z.startsWith(".")&&Q.name!==Z)throw Error(`Extension "${Z}": manifest name "${Q.name}" does not match the specifier`);let J=[];for(let[K,H]of Object.entries(Q.classes??{})){let Y=X.resolvePath(G,H),q;try{q=await X.loadJson(Y)}catch(B){throw Error(`Extension "${Z}": cannot read class "${K}" at ${Y}: ${p8(B)}`,{cause:B})}J.push(new O1(K,Y,q,X))}let U={};if(Q.schemas?.project)U.project=X.resolvePath(G,Q.schemas.project);if(Q.schemas?.document)U.document=X.resolvePath(G,Q.schemas.document);if(Q.schemas?.fields)U.fields=X.resolvePath(G,Q.schemas.fields);return{specifier:Z,manifestPath:G,manifest:Q,classes:J,schemas:U}}function p8(Z){return Z instanceof Error?Z.message:String(Z)}var _1="jx-extension.json";var J6=c(()=>{d8();d8()});var i8={};X9(i8,{unknownFormatError:()=>Q7,importImplementation:()=>K6,createNodeFormatIO:()=>V6,buildProjectFormatRegistry:()=>W7,buildProjectExtensionRegistry:()=>q6,buildExtensionsPayload:()=>G7});import{readFileSync as Y6}from"node:fs";import{dirname as Z7,isAbsolute as X7,resolve as l8,sep as N1}from"node:path";import{pathToFileURL as z7}from"node:url";import{createRequire as U6}from"node:module";async function K6(Z){let X=[Z],W=`${N1}src${N1}`,G=`${N1}dist${N1}`;if(Z.includes(W))X.push(Z.replace(W,G));if(Z.endsWith(".js"))X.push(`${Z.slice(0,-3)}.ts`);let Q;for(let J of X)try{return await import(z7(J).href)}catch(U){Q=U}throw Q instanceof Error?Q:Error(String(Q))}function V6(Z){return{importModule:(X)=>K6(X),loadJson:async(X)=>JSON.parse(Y6(X,"utf8")),resolvePath:(X,W)=>{if(W.startsWith("./")||W.startsWith("../"))return l8(Z7(X),W);if(X7(W))return W;let G=U6(l8(Z,"package.json"));try{return G.resolve(W)}catch{return U6(import.meta.url).resolve(W)}}}}async function q6(Z,X){return Q6(X?.extensions,V6(Z),l8(Z,"project.json"))}async function W7(Z,X){return(await q6(Z,X)).formats}function G7(Z){let X=[];for(let W of Z.extensions){let G={};if(W.schemas.project)try{G=JSON.parse(Y6(W.schemas.project,"utf8")).properties??{}}catch{G={}}let Q=[];for(let J of W.classes){if(!J.project)continue;Q.push({className:J.name,entrySchema:G[J.project.key]??null,project:J.project,studio:J.studio})}X.push({classes:W.classes.map((J)=>{let U=J.studio?.stateDefaults,K=J.project===null&&J.server===null&&J.connector===null&&J.extensions.length===0;return{name:J.name,path:J.classPath,...K?{state:!0}:{},...U&&typeof U==="object"?{stateDefaults:U}:{}}}),contributions:Q,name:W.manifest.name,specifier:W.specifier,...W.manifest.title===void 0?{}:{title:W.manifest.title},...W.manifest.description===void 0?{}:{description:W.manifest.description}})}return X}function Q7(Z,X){return Error(`No format class registered for "${X}" (${Z}). Enable an extension providing this format in project.json "extensions", e.g. "@jxsuite/parser".`)}var n8=c(()=>{J6()});async function B6(Z,X={}){let{resolveElementPath:W,$media:G,formats:Q}=X,J=[],U=new Set;async function K(H,Y){let q,B;if(typeof H==="string"){let{readFileSync:h}=await import("node:fs"),{resolve:f}=await import("node:path");if(B=Y?f(Y,H):f(H),U.has(B))return;if(U.add(B),B.endsWith(".json"))q=w1(h(B,"utf8"),B);else{let{extname:X2}=await import("node:path"),u=X2(B).toLowerCase(),b=Q?.byExtension?.(u,"parse");if(!b){let{unknownFormatError:o}=await Promise.resolve().then(() => (n8(),i8));throw o(B,u)}q=await b.call("parse",h(B,"utf8"))}}else{if(q=H,B=null,q.tagName&&U.has(q.tagName))return;if(q.tagName)U.add(q.tagName)}let{tagName:M}=q;if(!M||!M.includes("-"))throw Error(`compileElement: tagName "${M}" must contain a hyphen`);let{dirname:F}=await import("node:path"),D=B?F(B):null,w=[];if(Array.isArray(q.$elements))for(let h of q.$elements){let f=T2(h)?h.$ref:h;if(typeof f!=="string")continue;if(D)await K(f,D);let X2=W?W(f,D):f.replace(/\.json$/,".js");w.push(X2)}let A=J1(M);if(G)q.$media={...G,...q.$media};let{rewriteSrc:C}=X,E=y0(q,A,w,C?(h)=>C(h,D):void 0),y=B?B.replace(/\.json$/,".js"):`${M}.js`;J.push({content:E,path:y,tagName:M})}return await K(Z,X.basePath??null),{files:J}}async function J7(Z,X={}){let{title:W="Jx App",reactivitySrc:G="https://esm.sh/@vue/reactivity@3.5.13",litHtmlSrc:Q="https://esm.sh/lit-html@3.3.0"}=X,J=await B6(Z,X),U=J.files.at(-1);if(!U)throw Error("compileElementPage: no element modules were produced");let{basename:K}=await import("node:path"),H=K(U.path),Y=`<!DOCTYPE html>
+})`}var u8=c(()=>{e4();X0()});function sZ(Z){return Z instanceof Error?Z.message:String(Z)}function f8(Z,X,W){let G;try{G=JSON.parse(Z)}catch(Q){throw Error(`Failed to parse ${W} at ${X}: ${sZ(Q)}`,{cause:Q})}if(!F2(G))throw Error(`Invalid ${W} at ${X}: expected a JSON object`);return G}function w1(Z,X){return f8(Z,X,"Jx document")}function vX(Z,X){return f8(Z,X,"project config")}function yX(Z,X){return f8(Z,X,"class definition")}var c8=c(()=>{o2()});class O1{name;classPath;classDef;extensions;mediaType;documentKinds;exportTarget;remote;studio;project;server;connector;capabilities;#X;#Z=null;constructor(Z,X,W,G){this.name=Z,this.classPath=X,this.classDef=W,this.#X=G;let{format:Q}=W;this.extensions=(Q?.extensions??[]).map((J)=>J.toLowerCase()),this.mediaType=Q?.mediaType??null,this.documentKinds=Q?.documentKinds??[],this.exportTarget=Q?.exportTarget===!0,this.remote=Q?.remote===!0,this.studio=W.$studio??null,this.project=W.project??null,this.server=W.server??null,this.connector=W.connector??null,this.capabilities=tZ(W)}implementation(){if(!this.#Z){let Z=this.classDef.$implementation;if(!Z)return Promise.reject(Error(`Format class "${this.name}" has no $implementation to import`));this.#Z=this.#X.importModule(this.#X.resolvePath(this.classPath,Z))}return this.#Z}async call(Z,...X){let W=this.capabilities[Z];if(!W)throw Error(`Format class "${this.name}" does not declare a "${Z}" capability`);let G=await this.implementation(),Q=this.classDef.title??this.name,J=G[Q]??G.default?.[Q]??G.default,U=J?.[W.identifier];if(typeof U!=="function")throw TypeError(`Format class "${this.name}": implementation export "${Q}" has no static "${W.identifier}" method`);return await U.call(J,...X)}}class T1{#X;constructor(Z){this.#X=Z;for(let X of z6){let W=new Map;for(let G of Z){if(!G.capabilities[X])continue;for(let Q of G.extensions){let J=W.get(Q);if(J)throw Error(`Format conflict: "${J.name}" and "${G.name}" both claim "${Q}" with the "${X}" capability`);W.set(Q,G)}}}}get entries(){return this.#X}byExtension(Z,X){let W=X6(Z);return this.#X.find((G)=>G.extensions.includes(W)&&(!X||G.capabilities[X]))}byName(Z){return this.#X.find((X)=>X.name===Z)}withCapability(Z){return this.#X.filter((X)=>X.capabilities[Z])}documentExtensions(Z){let X=new Set;for(let W of this.#X){if(Z&&!W.documentKinds.includes(Z))continue;for(let G of W.extensions)X.add(G)}return X.delete(".json"),[...X]}has(Z){let X=X6(Z);return this.#X.some((W)=>W.extensions.includes(X))}}function tZ(Z){let X={},W=Z.$defs?.methods??{};for(let[G,Q]of Object.entries(W)){let J=Q.role;if(!J||!W6.includes(J))continue;let U={identifier:Q.identifier??G,timing:Q.timing??aZ};if(typeof Q.discriminator==="string")U.discriminator=Q.discriminator;X[J]=U}return X}function X6(Z){let X=Z.toLowerCase();return X.startsWith(".")?X:`.${X}`}var z6,W6,aZ;var d8=c(()=>{z6=["parse","serialize","discover","load"],W6=[...z6,"projectData","resolvePaths","lower","emit","assets","mount","dialect","deploySchema","bindings","testConnection"],aZ=["compiler","server"]});class G6{#X;#Z;#z;constructor(Z){this.#X=Z,this.#Z=Z.flatMap((Q)=>Q.classes);let X=new Map;for(let Q of Z)for(let J of Q.classes){let U=X.get(J.name);if(U&&U!==Q.specifier)throw Error(`Extension conflict: "${U}" and "${Q.specifier}" both provide a class named "${J.name}"`);X.set(J.name,Q.specifier)}let W=new Map;for(let Q of this.#Z){if(!Q.project)continue;let J=W.get(Q.project.key);if(J)throw Error(`Extension conflict: "${J.name}" and "${Q.name}" both claim the project section "${Q.project.key}"`);W.set(Q.project.key,Q)}let G=new Map;for(let Q of this.#Z){if(!Q.server)continue;let{basePath:J}=Q.server;if(!J.startsWith("/_jx/"))throw Error(`Extension "${Q.name}": server basePath "${J}" must be under /_jx/`);let U=G.get(J);if(U)throw Error(`Extension conflict: "${U.name}" and "${Q.name}" both mount "${J}"`);G.set(J,Q)}this.#z=new T1(this.#Z.filter((Q)=>Q.extensions.length>0))}get extensions(){return this.#X}get classes(){return this.#Z}get formats(){return this.#z}byName(Z){return this.#Z.find((X)=>X.name===Z)}projectContributions(){return this.#Z.filter((Z)=>Z.project!==null)}byProjectKey(Z){return this.#Z.find((X)=>X.project?.key===Z)}byPathsDiscriminator(Z){return this.#Z.find((X)=>X.capabilities.resolvePaths?.discriminator===Z)}emitters(){return this.#Z.filter((Z)=>Z.capabilities.emit!==void 0)}assetProviders(){return this.#Z.filter((Z)=>Z.capabilities.assets!==void 0)}serverMounts(){return this.#Z.filter((Z)=>Z.server!==null).toSorted((Z,X)=>(Z.server?.order??100)-(X.server?.order??100)||Z.name.localeCompare(X.name))}connectors(){return this.#Z.filter((Z)=>Z.connector!==null)}schemaFragments(Z){return this.#X.map((X)=>X.schemas[Z]).filter((X)=>typeof X==="string")}}async function Q6(Z,X,W){let G=[];for(let Q of Z??[])G.push(await eZ(Q,X,W));return new G6(G)}async function eZ(Z,X,W){let G;if(Z.startsWith("./")||Z.startsWith("../")){let K=X.resolvePath(W,Z);G=X.resolvePath(`${K}/package.json`,`./${_1}`)}else try{G=X.resolvePath(W,`${Z}/${_1}`)}catch(K){throw Error(`Extension "${Z}" is not resolvable: it must export ${_1} (is the package installed, and does its exports map include it?): ${p8(K)}`,{cause:K})}let Q;try{Q=await X.loadJson(G)}catch(K){throw Error(`Extension "${Z}": cannot read manifest ${G}: ${p8(K)}`,{cause:K})}if(!Q||typeof Q!=="object"||typeof Q.name!=="string")throw Error(`Extension "${Z}": ${_1} must declare a "name"`);if(!Z.startsWith(".")&&Q.name!==Z)throw Error(`Extension "${Z}": manifest name "${Q.name}" does not match the specifier`);let J=[];for(let[K,H]of Object.entries(Q.classes??{})){let Y=X.resolvePath(G,H),q;try{q=await X.loadJson(Y)}catch(B){throw Error(`Extension "${Z}": cannot read class "${K}" at ${Y}: ${p8(B)}`,{cause:B})}J.push(new O1(K,Y,q,X))}let U={};if(Q.schemas?.project)U.project=X.resolvePath(G,Q.schemas.project);if(Q.schemas?.document)U.document=X.resolvePath(G,Q.schemas.document);if(Q.schemas?.fields)U.fields=X.resolvePath(G,Q.schemas.fields);return{specifier:Z,manifestPath:G,manifest:Q,classes:J,schemas:U}}function p8(Z){return Z instanceof Error?Z.message:String(Z)}var _1="jx-extension.json";var J6=c(()=>{d8();d8()});var i8={};X9(i8,{unknownFormatError:()=>Q7,importImplementation:()=>K6,createNodeFormatIO:()=>V6,buildProjectFormatRegistry:()=>W7,buildProjectExtensionRegistry:()=>q6,buildExtensionsPayload:()=>G7});import{readFileSync as Y6}from"node:fs";import{dirname as Z7,isAbsolute as X7,resolve as l8,sep as N1}from"node:path";import{pathToFileURL as z7}from"node:url";import{createRequire as U6}from"node:module";async function K6(Z){let X=[Z],W=`${N1}src${N1}`,G=`${N1}dist${N1}`;if(Z.includes(W))X.push(Z.replace(W,G));if(Z.endsWith(".js"))X.push(`${Z.slice(0,-3)}.ts`);let Q;for(let J of X)try{return await import(z7(J).href)}catch(U){Q=U}throw Q instanceof Error?Q:Error(String(Q))}function V6(Z){return{importModule:(X)=>K6(X),loadJson:async(X)=>JSON.parse(Y6(X,"utf8")),resolvePath:(X,W)=>{if(W.startsWith("./")||W.startsWith("../"))return l8(Z7(X),W);if(X7(W))return W;let G=U6(l8(Z,"package.json"));try{return G.resolve(W)}catch{return U6(import.meta.url).resolve(W)}}}}async function q6(Z,X){return Q6(X?.extensions,V6(Z),l8(Z,"project.json"))}async function W7(Z,X){return(await q6(Z,X)).formats}function G7(Z){let X=[];for(let W of Z.extensions){let G={};if(W.schemas.project)try{G=JSON.parse(Y6(W.schemas.project,"utf8")).properties??{}}catch{G={}}let Q=[];for(let J of W.classes){if(!J.project)continue;Q.push({className:J.name,entrySchema:G[J.project.key]??null,project:J.project,studio:J.studio})}X.push({classes:W.classes.map((J)=>{let U=J.studio?.stateDefaults,K=J.project===null&&J.server===null&&J.connector===null&&J.extensions.length===0;return{name:J.name,path:J.classPath,...K?{state:!0}:{},...U&&typeof U==="object"?{stateDefaults:U}:{}}}),contributions:Q,name:W.manifest.name,specifier:W.specifier,...W.manifest.title===void 0?{}:{title:W.manifest.title},...W.manifest.description===void 0?{}:{description:W.manifest.description}})}return X}function Q7(Z,X){return Error(`No format class registered for "${X}" (${Z}). Enable an extension providing this format in project.json "extensions", e.g. "@jxsuite/parser".`)}var n8=c(()=>{J6()});async function B6(Z,X={}){let{resolveElementPath:W,$media:G,formats:Q}=X,J=[],U=new Set;async function K(H,Y){let q,B;if(typeof H==="string"){let{readFileSync:h}=await import("node:fs"),{resolve:f}=await import("node:path");if(B=Y?f(Y,H):f(H),U.has(B))return;if(U.add(B),B.endsWith(".json"))q=w1(h(B,"utf8"),B);else{let{extname:X2}=await import("node:path"),u=X2(B).toLowerCase(),b=Q?.byExtension?.(u,"parse");if(!b){let{unknownFormatError:o}=await Promise.resolve().then(() => (n8(),i8));throw o(B,u)}q=await b.call("parse",h(B,"utf8"))}}else{if(q=H,B=null,q.tagName&&U.has(q.tagName))return;if(q.tagName)U.add(q.tagName)}let{tagName:M}=q;if(!M||!M.includes("-"))throw Error(`compileElement: tagName "${M}" must contain a hyphen`);let{dirname:F}=await import("node:path"),D=B?F(B):null,w=[];if(Array.isArray(q.$elements))for(let h of q.$elements){let f=T2(h)?h.$ref:h;if(typeof f!=="string")continue;if(D)await K(f,D);let X2=W?W(f,D):f.replace(/\.json$/,".js");w.push(X2)}let A=J1(M);if(G)q.$media={...G,...q.$media};let{rewriteSrc:C}=X,E=y0(q,A,w,C?(h)=>C(h,D):void 0),y=B?B.replace(/\.json$/,".js"):`${M}.js`;J.push({content:E,path:y,tagName:M})}return await K(Z,X.basePath??null),{files:J}}async function J7(Z,X={}){let{title:W="Jx App",reactivitySrc:G="https://esm.sh/@vue/reactivity@3.5.13",litHtmlSrc:Q="https://esm.sh/lit-html@3.3.0"}=X,J=await B6(Z,X),U=J.files.at(-1);if(!U)throw Error("compileElementPage: no element modules were produced");let{basename:K}=await import("node:path"),H=K(U.path),Y=`<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
   "type": "module",
   "exports": {
     ".": "./src/compiler.ts",
+    "./asset-mounts": "./src/site/asset-mounts.ts",
     "./format-host": "./src/site/format-host.ts",
     "./project-sections": "./src/site/project-sections.ts",
     "./schema-command": "./src/site/schema-command.ts",
@@ -45,16 +46,16 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.5.0",
-    "@jxsuite/create": "^1.2.0",
-    "@jxsuite/runtime": "^1.3.0",
-    "@jxsuite/schema": "^1.3.0",
+    "@jxsuite/create": "^1.2.1",
+    "@jxsuite/runtime": "^1.3.1",
+    "@jxsuite/schema": "^1.4.0",
     "esbuild": "^0.28.1",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.0",
-    "@jxsuite/connector": "^0.4.0",
-    "@jxsuite/parser": "^1.3.0",
+    "@happy-dom/global-registrator": "^20.11.1",
+    "@jxsuite/connector": "^0.4.1",
+    "@jxsuite/parser": "^1.4.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/site/asset-mounts.ts

@@ -0,0 +1,140 @@
+/**
+ * Asset-mounts — host side of the extension `assets` capability (specs/extensions.md §8.5).
+ *
+ * A section-owner class publishes directories that may sit outside the project root (an external
+ * content source's co-located images) at a stable site URL. The build resolves those URLs while
+ * optimizing images, collects the ones its compiled output actually references, and copies just
+ * those files into dist — the source directory itself is never mirrored, so entry files never leak
+ * into the build output.
+ *
+ * @module asset-mounts
+ * @docs framework/site/images
+ */
+
+import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  collectAssetUrls,
+  normalizeAssetPrefix,
+  resolveAssetUrl,
+} from "@jxsuite/schema/asset-paths";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
+import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+/**
+ * Gather every asset mount contributed by the project's extensions.
+ *
+ * Gating matches `emit` (extensions.md §8.4): a class owning a project section contributes only
+ * when the project declares a non-empty value for that section. Mounts claiming the same URL prefix
+ * for different directories are a configuration error — the first wins and the clash is reported.
+ *
+ * @param {ExtensionRegistry} registry - The project's extension registry
+ * @param {ProjectConfig} projectConfig
+ * @param {string} projectRoot - Absolute project root
+ * @returns {Promise<{ mounts: AssetMount[]; errors: string[] }>}
+ */
+export async function loadAssetMounts(
+  registry: ExtensionRegistry,
+  projectConfig: ProjectConfig,
+  projectRoot: string,
+): Promise<{ mounts: AssetMount[]; errors: string[] }> {
+  const mounts: AssetMount[] = [];
+  const errors: string[] = [];
+  const byPrefix = new Map<string, AssetMount>();
+
+  for (const entry of registry.assetProviders()) {
+    const sectionKey = entry.project?.key;
+    const sectionValue = sectionKey
+      ? (projectConfig as unknown as Record<string, unknown>)[sectionKey]
+      : undefined;
+    if (
+      sectionKey &&
+      (sectionValue == null ||
+        (typeof sectionValue === "object" && Object.keys(sectionValue).length === 0))
+    ) {
+      continue;
+    }
+    try {
+      const declared = (await entry.call("assets", sectionValue ?? null, {
+        projectConfig,
+        root: projectRoot,
+      })) as AssetMount[] | null;
+      for (const mount of declared ?? []) {
+        if (!mount?.urlPrefix || !mount.dir) {
+          continue;
+        }
+        const normalized: AssetMount = {
+          dir: mount.dir,
+          urlPrefix: normalizeAssetPrefix(mount.urlPrefix),
+        };
+        const prior = byPrefix.get(normalized.urlPrefix);
+        if (prior) {
+          if (prior.dir !== normalized.dir) {
+            errors.push(
+              `Asset mount conflict: "${normalized.urlPrefix}" is claimed by both ` +
+                `"${prior.dir}" and "${normalized.dir}"`,
+            );
+          }
+          continue;
+        }
+        byPrefix.set(normalized.urlPrefix, normalized);
+        mounts.push(normalized);
+      }
+    } catch (error) {
+      errors.push(`Error in ${entry.name}.assets: ${(error as Error).message}`);
+    }
+  }
+
+  return { errors, mounts };
+}
+
+/**
+ * Add every mounted URL referenced by a compiled artifact to `into`.
+ *
+ * @param {string} text - Compiled HTML or CSS
+ * @param {readonly AssetMount[]} mounts
+ * @param {Set<string>} into - Accumulator across the whole build
+ */
+export function collectAssetRefs(text: string, mounts: readonly AssetMount[], into: Set<string>) {
+  if (mounts.length === 0 || !text) {
+    return;
+  }
+  for (const url of collectAssetUrls(text, mounts)) {
+    into.add(url);
+  }
+}
+
+/**
+ * Copy referenced mounted assets into the build output, each at its own URL path.
+ *
+ * @param {Iterable<string>} urls - Mounted URLs collected from the compiled output
+ * @param {readonly AssetMount[]} mounts
+ * @param {string} outDir - Absolute build output directory
+ * @returns {{ copied: number; missing: string[] }} Files written, and URLs that resolved to nothing
+ */
+export function copyMountedAssets(
+  urls: Iterable<string>,
+  mounts: readonly AssetMount[],
+  outDir: string,
+): { copied: number; missing: string[] } {
+  let copied = 0;
+  const missing: string[] = [];
+
+  for (const url of urls) {
+    // The single containment gate is resolveAssetUrl: it decodes once and refuses `.`/`..`,
+    // Empty segments, and undecodable input, so a surviving URL cannot escape either the mount
+    // Directory it reads from or the outDir path it writes to.
+    const source = resolveAssetUrl(mounts, url);
+    if (!source || !existsSync(source)) {
+      missing.push(url);
+      continue;
+    }
+    const target = resolve(outDir, decodeURIComponent(url).replace(/^\//, ""));
+    mkdirSync(dirname(target), { recursive: true });
+    cpSync(source, target);
+    copied += 1;
+  }
+
+  return { copied, missing };
+}

package/src/site/image-transform.ts

@@ -16,7 +16,9 @@ import {
   processImage,
 } from "./image-optimizer.ts";
 import { getCached, getImageCacheDir, setCached } from "./image-cache.ts";
+import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { ImageConfig, ImageManifest } from "./image-optimizer.ts";
 import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 import type { CacheManifest } from "./image-cache.ts";
@@ -193,13 +195,20 @@ function isAllowedRemote(src: string, config: ImageConfig) {
 /**
  * Resolve a src path to an absolute filesystem path.
  *
- * Handles paths starting with "/" (relative to public dir or project root).
+ * Extension asset mounts win first — they publish directories that may sit outside the project root
+ * (extensions.md §8.5), so a mounted src has no other resolution. Otherwise paths starting with "/"
+ * resolve into `public/`, and relative ones from the project root.
  *
  * @param {string} src
  * @param {string} projectRoot
+ * @param {readonly AssetMount[]} [mounts]
  * @returns {string}
  */
-function resolveImagePath(src: string, projectRoot: string) {
+function resolveImagePath(src: string, projectRoot: string, mounts?: readonly AssetMount[]) {
+  const mounted = mounts?.length ? resolveAssetUrl(mounts, src) : null;
+  if (mounted) {
+    return mounted;
+  }
   if (src.startsWith("/")) {
     return resolve(projectRoot, "public", src.slice(1));
   }
@@ -218,6 +227,7 @@ function resolveImagePath(src: string, projectRoot: string) {
  * @param {string} projectRoot
  * @param {CacheManifest | null} cache - Variant cache (build mode); unused in cloudflare mode
  * @param {ImageMetaCache} [metaCache] - Dimension/hash memo (cloudflare mode)
+ * @param {readonly AssetMount[]} [mounts] - Extension asset mounts (extensions.md §8.5)
  * @returns {Promise<{ imageRefs: Map<string, ImageManifest> }>}
  */
 export async function transformImageNodes(
@@ -226,6 +236,7 @@ export async function transformImageNodes(
   projectRoot: string,
   cache: CacheManifest | null,
   metaCache?: ImageMetaCache,
+  mounts: readonly AssetMount[] = [],
 ) {
   const imageRefs = new Map<string, ImageManifest>();
 
@@ -234,7 +245,7 @@ export async function transformImageNodes(
   }
 
   const meta = metaCache ?? new Map();
-  await walkAndTransform(doc, config, projectRoot, cache, meta, imageRefs);
+  await walkAndTransform(doc, config, projectRoot, cache, meta, imageRefs, mounts);
 
   return { imageRefs };
 }
@@ -246,6 +257,7 @@ export async function transformImageNodes(
  * @param {CacheManifest | null} cache
  * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
+ * @param {readonly AssetMount[]} mounts
  */
 async function walkAndTransform(
   node: JxMutableNode | JxDocument,
@@ -254,13 +266,14 @@ async function walkAndTransform(
   cache: CacheManifest | null,
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
+  mounts: readonly AssetMount[],
 ) {
   if (!node || typeof node !== "object") {
     return;
   }
 
   if (node.tagName === "img") {
-    await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs);
+    await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs, mounts);
   }
 
   if (typeof node.innerHTML === "string" && node.innerHTML.includes("<img")) {
@@ -271,6 +284,7 @@ async function walkAndTransform(
       cache,
       metaCache,
       imageRefs,
+      mounts,
     );
   }
 
@@ -279,7 +293,7 @@ async function walkAndTransform(
       if (typeof child === "string") {
         continue;
       }
-      await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs);
+      await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs, mounts);
     }
   }
 }
@@ -291,6 +305,7 @@ async function walkAndTransform(
  * @param {CacheManifest | null} cache
  * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
+ * @param {readonly AssetMount[]} mounts
  */
 async function transformImgNode(
   node: JxMutableNode | JxDocument,
@@ -299,6 +314,7 @@ async function transformImgNode(
   cache: CacheManifest | null,
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
+  mounts: readonly AssetMount[],
 ) {
   if (!node.attributes) {
     node.attributes = {};
@@ -325,7 +341,7 @@ async function transformImgNode(
     // Fit=scale-down avoid upscaling past the source size.
     srcset = buildCloudflareSrcset(src, config, Infinity, null);
   } else {
-    const absoluteSrc = resolveImagePath(src, projectRoot);
+    const absoluteSrc = resolveImagePath(src, projectRoot, mounts);
     if (!existsSync(absoluteSrc)) {
       return;
     }
@@ -382,6 +398,7 @@ const DATA_NO_OPT_RE = /\bdata-no-optimize\b/;
  * @param {CacheManifest | null} cache
  * @param {ImageMetaCache} metaCache
  * @param {Map<string, ImageManifest>} imageRefs
+ * @param {readonly AssetMount[]} mounts
  * @returns {Promise<string>}
  */
 async function transformInnerHtmlImages(
@@ -391,6 +408,7 @@ async function transformInnerHtmlImages(
   cache: CacheManifest | null,
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
+  mounts: readonly AssetMount[],
 ) {
   /** @type {{ match: string; replacement: string }[]} */
   const replacements = [];
@@ -418,7 +436,7 @@ async function transformInnerHtmlImages(
       continue;
     }
 
-    const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot);
+    const absoluteSrc = remote ? null : resolveImagePath(src, projectRoot, mounts);
     if (absoluteSrc && !existsSync(absoluteSrc)) {
       continue;
     }

package/src/site/site-build.ts

@@ -32,6 +32,8 @@ import { loadProjectConfig } from "./site-loader.ts";
 import { discoverPages, expandDynamicRoutes, readPageDocument } from "./pages-discovery.ts";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectSections } from "./project-sections.ts";
+import { collectAssetRefs, copyMountedAssets, loadAssetMounts } from "./asset-mounts.ts";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import { resolveLayout } from "./layout-resolver.ts";
@@ -208,6 +210,26 @@ export async function buildSite(
     log(`  Loaded ${sectionKeys.length} section(s): ${sectionKeys.join(", ")}`);
   }
 
+  // ── 3c. Extension asset mounts (extensions.md §8.5) ─────────────────────
+  // Directories published at a site URL — typically an external content source's co-located
+  // Images. They resolve for image optimization below, and the files pages actually reference
+  // Are copied into dist in step 7c.
+  const { errors: mountErrors, mounts: assetMounts } = await loadAssetMounts(
+    registry,
+    projectConfig,
+    projectRoot,
+  );
+  errors.push(...mountErrors);
+  for (const message of mountErrors) {
+    console.error(message);
+  }
+  if (assetMounts.length > 0) {
+    log(
+      `  Mounted ${assetMounts.length} asset dir(s): ${assetMounts.map((m) => m.urlPrefix).join(", ")}`,
+    );
+  }
+  const assetRefs = new Set<string>();
+
   // ── 4. Expand dynamic routes ────────────────────────────────────────────
   const routes = await expandDynamicRoutes(
     staticRoutes,
@@ -262,6 +284,7 @@ export async function buildSite(
           const css = buildComponentCSS(doc.tagName, doc.style, doc, projectConfig.$media ?? {});
           if (css) {
             componentCSS.set(doc.tagName, css);
+            collectAssetRefs(css, assetMounts, assetRefs);
             writeFileSync(resolve(componentOutDir, `${doc.tagName}.css`), css, "utf8");
             fileCount += 1;
           }
@@ -325,6 +348,7 @@ export async function buildSite(
         formatRegistry,
         registry,
         rewriteSidecarSrc,
+        assetMounts,
       );
 
       // Determine which component tags are fully static (for script omission)
@@ -345,6 +369,10 @@ export async function buildSite(
         );
       }
 
+      // Mounted assets this page actually references — scanned from the finished HTML so a
+      // Reference is caught wherever it came from (markdown image, hand-authored page, $head).
+      collectAssetRefs(result.html, assetMounts, assetRefs);
+
       // Determine output path
       const outPath = routeToOutputPath(route.urlPattern, outDir, trailingSlash);
       mkdirSync(dirname(outPath), { recursive: true });
@@ -568,7 +596,19 @@ export async function buildSite(
     console.warn("sitemap.xml skipped — set `url` in project.json to enable sitemap generation.");
   }
 
-  // ── 7c. Copy public/ assets ─────────────────────────────────────────────
+  // ── 7c. Copy referenced mounted assets (extensions.md §8.5) ─────────────
+  // Only files the compiled output references are copied, so a content source's entry files
+  // Never land in dist. Runs before the public/ copy, which keeps shadowing everything.
+  if (assetRefs.size > 0) {
+    const { copied, missing } = copyMountedAssets(assetRefs, assetMounts, outDir);
+    fileCount += copied;
+    log(`Copying ${copied} mounted asset(s)...`);
+    for (const url of missing) {
+      console.warn(`Referenced asset not found: ${url}`);
+    }
+  }
+
+  // ── 7c(ii). Copy public/ assets ─────────────────────────────────────────
   if (existsSync(publicDir)) {
     log("Copying public/ assets...");
     cpSync(publicDir, outDir, { recursive: true });
@@ -630,6 +670,7 @@ async function compilePage(
   formatRegistry?: FormatRegistry,
   registry?: ExtensionRegistry,
   rewriteSidecarSrc?: (specifier: string, docDir: string | null) => string,
+  assetMounts: readonly AssetMount[] = [],
 ) {
   // Load the raw page document (.json natively, other formats via the registry)
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
@@ -744,6 +785,7 @@ async function compilePage(
       projectRoot,
       imageCache,
       imageMetaCache ?? undefined,
+      assetMounts,
     );
   }