ngx-json-render 0.9.5 → 0.9.6

package/README.md

@@ -746,7 +746,7 @@ import { catalog } from './catalog'; // defineCatalog(schema, …) from ngx-json
 
 const server = createRenderUiServer({
   catalog,
-  html: readFileSync('dist/view.html', 'utf8'), // the view above, built into one page
+  html: readFileSync(new URL('./view.html', import.meta.url), 'utf8'), // the view above, built into one page
   name: 'my-app',
   version: '1.0.0',
 });
@@ -764,7 +764,24 @@ What it does on top of upstream's `createMcpApp` from `@json-render/mcp`, whose
 
 Options: `name`, `version`, `toolName` (default `render-ui`), `title`, `description`, `csp` (the origins the view may load from and connect to; left out, the host allows none) and `widgetDomain` (the view's origin for ChatGPT's plugin directory). If your catalog has a `sendMessage` action, the description tells the model how to use it; the view's handler for it calls `mcp.sendMessage()`.
 
-[`projects/mcp-app`](https://github.com/shteynu/ngx-json-render/tree/main/projects/mcp-app) is a complete example with the Material catalog: the view, the build that inlines it into one page, and this server, the one behind `https://ngx-json-render.vercel.app/mcp`.
+### Building it
+
+A host loads the view as one HTML document with nowhere to fetch chunks from, so the Angular build has to be folded into a single page. The `ngx-json-render:mcp-app` builder does that, and bundles the server next to it. Give the view its own application project (`ng generate application mcp-view`), then add a target to it in `angular.json`:
+
+```json
+"mcp": {
+  "builder": "ngx-json-render:mcp-app",
+  "options": {
+    "buildTarget": "mcp-view:build:production",
+    "outputPath": "dist/mcp-app",
+    "server": "projects/mcp-view/server.ts"
+  }
+}
+```
+
+`ng run mcp-view:mcp` runs the application build, then writes `dist/mcp-app/view.html` with every script and stylesheet inlined, and the fonts and images the stylesheets use as data URLs, and `dist/mcp-app/server.mjs` with its dependencies bundled in, so `node dist/mcp-app/server.mjs` runs anywhere without `node_modules`. Files the page cannot reach, such as an image referenced only from a template, are listed as a warning: point at them from a stylesheet or from an `https:` origin in `csp`. The server bundle is not type-checked; run `tsc --noEmit` on it first if you want that. Options: `server` (leave it out to build the view only), `tsConfig` for the server, and `externalPackages: true` to keep `node_modules` packages out of `server.mjs`.
+
+[`projects/mcp-app`](https://github.com/shteynu/ngx-json-render/tree/main/projects/mcp-app) is a complete example with the Material catalog: the view, built with this builder, and this server, the one behind `https://ngx-json-render.vercel.app/mcp`.
 
 ## Devtools
 
@@ -1208,6 +1225,8 @@ MCP Apps (`ngx-json-render/mcp`): `injectJsonRenderApp`, `parseSpecFromToolResul
 
 MCP App server (`ngx-json-render/mcp/server`): `createRenderUiServer`, `handleRenderUiRequest`, `renderUiDescription`, `specInputSchema`, `specOutputSchema`, `specProblems`, `DESCRIPTION_LIMIT`, and the types `RenderUiServerOptions`, `RenderUiDescriptionOptions`. No Angular; the same optional peers.
 
+MCP App builder (`ngx-json-render:mcp-app`): the view's application build as one `view.html`, and the server bundled into `server.mjs`.
+
 Router (`ngx-json-render/router`): `injectRouterNavigate`, and the type `RouterNavigateOptions`. Needs the optional peer `@angular/router`, which an Angular app on the router already has.
 
 AG-UI (`ngx-json-render/ag-ui`): `injectAgentUI`, `applyAgUiEvent`, `surfacesFromMessages`, `isJsonRenderSpec`, `JsonRenderActivity` (`<json-render-activity>`), `jsonRenderActivityRenderer`, `JSON_RENDER_ACTIVITY_TYPE`, and the types `AgUiAgent`, `AgUiEvent`, `AgUiMessage`, `AgUiSubscriber`, `AgUiSurface`, `AgentUIOptions`, `AgentUIReturn`, `JsonRenderActivityRendererConfig`, `JsonRenderActivityRendererOptions`. No peer: any agent and event of the right shape will do.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-json-render",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Generative UI for Angular: a json-render renderer that streams AI-generated JSON specs into real Angular components with signals.",
   "keywords": [
     "angular",
@@ -52,6 +52,7 @@
   },
   "sideEffects": false,
   "schematics": "./schematics/collection.json",
+  "builders": "./schematics/builders.json",
   "ng-add": {
     "save": "dependencies"
   },

package/schematics/builders.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/architect/src/builders-schema.json",
+  "builders": {
+    "mcp-app": {
+      "implementation": "./mcp-app-builder/index.cjs",
+      "schema": "./mcp-app-builder/schema.json",
+      "description": "Builds an MCP App: the view as one view.html, the server as server.mjs."
+    }
+  }
+}

package/schematics/mcp-app-builder/index.cjs

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMcpApp = buildMcpApp;
+const architect_1 = require("@angular-devkit/architect");
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const inline_cjs_1 = require("./inline.cjs");
+/**
+ * `ngx-json-render:mcp-app`: runs the view's application build, folds its
+ * browser output into one `view.html` (an MCP Apps host loads the view as a
+ * single document), and bundles the server entry, if there is one, into
+ * `server.mjs` next to it.
+ */
+async function buildMcpApp(options, context) {
+    const root = context.workspaceRoot;
+    const target = (0, architect_1.targetFromTargetString)(options.buildTarget, context.target?.project);
+    const run = await context.scheduleTarget(target);
+    const result = await run.result;
+    await run.stop();
+    if (!result.success)
+        return result;
+    const esbuild = loadEsbuild(root);
+    const browserDir = await browserOutput(context, target);
+    const view = await (0, inline_cjs_1.inlineView)(browserDir, async (entry) => {
+        const { outputFiles } = await esbuild.build({
+            entryPoints: [entry],
+            bundle: true,
+            format: 'esm',
+            minify: true,
+            write: false,
+            logLevel: 'warning',
+        });
+        return outputFiles[0].text;
+    });
+    const out = (0, node_path_1.resolve)(root, options.outputPath);
+    (0, node_fs_1.mkdirSync)(out, { recursive: true });
+    const viewPath = (0, node_path_1.join)(out, 'view.html');
+    (0, node_fs_1.writeFileSync)(viewPath, view.html);
+    context.logger.info(`Built ${(0, node_path_1.relative)(root, viewPath)} (${Math.round(view.html.length / 1024)} kB)`);
+    if (view.leftOut.length > 0) {
+        context.logger.warn(`Not in view.html, so the host cannot load them: ${view.leftOut.join(', ')}. ` +
+            'Reference assets from a stylesheet (they are inlined) or from an https: URL the view CSP allows.');
+    }
+    if (options.server) {
+        const serverPath = (0, node_path_1.join)(out, 'server.mjs');
+        await esbuild.build({
+            entryPoints: [(0, node_path_1.resolve)(root, options.server)],
+            outfile: serverPath,
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            tsconfig: options.tsConfig ? (0, node_path_1.resolve)(root, options.tsConfig) : undefined,
+            packages: options.externalPackages ? 'external' : undefined,
+            // The view as text, for a server that imports it rather than reading
+            // the file next to it.
+            loader: { '.html': 'text' },
+            // Bundled CommonJS dependencies may call require(); give the ES module
+            // one.
+            banner: options.externalPackages
+                ? undefined
+                : {
+                    js: "import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);",
+                },
+            logLevel: 'warning',
+        });
+        context.logger.info(`Built ${(0, node_path_1.relative)(root, serverPath)}`);
+    }
+    return { success: true, outputPath: out };
+}
+/** Where the application build wrote its browser files. */
+async function browserOutput(context, target) {
+    const options = await context.getTargetOptions(target);
+    const outputPath = options['outputPath'];
+    const base = typeof outputPath === 'string'
+        ? outputPath
+        : (outputPath?.base ?? (0, node_path_1.join)('dist', target.project));
+    const browser = typeof outputPath === 'object' && outputPath.browser !== undefined
+        ? outputPath.browser
+        : 'browser';
+    return (0, node_path_1.resolve)(context.workspaceRoot, base, browser);
+}
+/**
+ * esbuild, from `@angular/build` (which every application build already
+ * installs at a version it was tested with), or else from the workspace.
+ */
+function loadEsbuild(root) {
+    const workspace = (0, node_module_1.createRequire)((0, node_path_1.join)(root, 'package.json'));
+    try {
+        const build = (0, node_path_1.dirname)(workspace.resolve('@angular/build/package.json'));
+        return (0, node_module_1.createRequire)((0, node_path_1.join)(build, 'package.json'))('esbuild');
+    }
+    catch {
+        return workspace('esbuild');
+    }
+}
+exports.default = (0, architect_1.createBuilder)(buildMcpApp);

package/schematics/mcp-app-builder/inline.cjs

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inlineView = inlineView;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const MIME = {
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+};
+/**
+ * The browser output of an Angular application build as one HTML document.
+ * MCP Apps hosts load a view's `ui://` resource as a single document with no
+ * origin to fetch from, so every module script (main, polyfills, and the
+ * chunks they import) is bundled and inlined, every local stylesheet is
+ * inlined, and fonts and images the stylesheets point at become data URLs.
+ * External URLs stay as they are; the view's CSP has to allow them.
+ */
+async function inlineView(browserDir, bundle) {
+    const indexPath = (0, node_path_1.join)(browserDir, 'index.html');
+    if (!(0, node_fs_1.existsSync)(indexPath)) {
+        throw new Error(`No index.html in ${browserDir}. Is the build target an @angular/build:application build?`);
+    }
+    let html = (0, node_fs_1.readFileSync)(indexPath, 'utf8');
+    const used = new Set(['index.html']);
+    // Preloads point at chunks that are about to be inlined.
+    html = html.replace(/<link\b[^>]*\brel="modulepreload"[^>]*>/g, '');
+    // A view lives in an iframe, which shows no icon; `ng new` links one.
+    html = html.replace(/<link\b[^>]*\brel="(?:shortcut )?icon"[^>]*>\s*/g, (tag) => {
+        const href = attribute(tag, 'href');
+        const file = href && local(browserDir, href);
+        if (!file)
+            return tag;
+        used.add((0, node_path_1.relative)(browserDir, file));
+        return '';
+    });
+    for (const tag of html.match(/<script\b[^>]*\bsrc="[^"]*"[^>]*><\/script>/g) ?? []) {
+        const src = attribute(tag, 'src');
+        const file = src && local(browserDir, src);
+        if (!file)
+            continue;
+        used.add((0, node_path_1.relative)(browserDir, file));
+        const isModule = attribute(tag, 'type') === 'module';
+        const code = isModule ? await bundle(file) : (0, node_fs_1.readFileSync)(file, 'utf8');
+        html = html.replace(tag, () => `<script${isModule ? ' type="module"' : ''}>${escapeTag(code, 'script')}</script>`);
+    }
+    // Angular may load the stylesheet as `media="print" onload=…` with a
+    // <noscript> fallback, so it does not block the first paint.
+    const stylesheet = /<link\b[^>]*\brel="stylesheet"[^>]*>(\s*<noscript>[\s\S]*?<\/noscript>)?/g;
+    for (const [match] of html.matchAll(stylesheet)) {
+        const href = attribute(match, 'href');
+        const file = href && local(browserDir, href);
+        if (!file)
+            continue;
+        used.add((0, node_path_1.relative)(browserDir, file));
+        const css = inlineUrls((0, node_fs_1.readFileSync)(file, 'utf8'), file, browserDir, used);
+        html = html.replace(match, () => `<style>${escapeTag(css, 'style')}</style>`);
+    }
+    // Inline <style> blocks (critical CSS) can point at media files too.
+    html = html.replace(/(<style\b[^>]*>)([\s\S]*?)(<\/style>)/g, (_, open, css, close) => open + inlineUrls(css, indexPath, browserDir, used) + close);
+    const leftOut = files(browserDir)
+        .map((file) => (0, node_path_1.relative)(browserDir, file))
+        .filter((file) => !used.has(file) && !isBuildArtifact(file));
+    return { html, leftOut };
+}
+/** `url(...)` references to files of the build, as data URLs. */
+function inlineUrls(css, from, browserDir, used) {
+    return css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (match, quote, url) => {
+        const base = (0, node_path_1.join)(from, '..');
+        const file = local(base, url) ?? local(browserDir, url);
+        const mime = file && MIME[(0, node_path_1.extname)(file).toLowerCase()];
+        if (!file || !mime)
+            return match;
+        used.add((0, node_path_1.relative)(browserDir, file));
+        const data = (0, node_fs_1.readFileSync)(file).toString('base64');
+        return `url(${quote}data:${mime};base64,${data}${quote})`;
+    });
+}
+/** The file `url` names under `dir`, or undefined for anything external. */
+function local(dir, url) {
+    if (/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(url))
+        return undefined;
+    const path = decodeURIComponent(url.split(/[?#]/)[0]).replace(/^\/+/, '');
+    const file = (0, node_path_1.resolve)(dir, path);
+    if (file !== (0, node_path_1.resolve)(dir) && !file.startsWith((0, node_path_1.resolve)(dir) + node_path_1.sep)) {
+        return undefined;
+    }
+    return (0, node_fs_1.existsSync)(file) && (0, node_fs_1.statSync)(file).isFile() ? file : undefined;
+}
+function attribute(tag, name) {
+    return new RegExp(`\\b${name}="([^"]*)"`).exec(tag)?.[1];
+}
+/** Keeps `</script>` or `</style>` inside the code from closing the tag. */
+function escapeTag(code, tag) {
+    return code.replace(new RegExp(`</${tag}`, 'gi'), `<\\/${tag}`);
+}
+/** Chunks and maps the inlined scripts already carry, and build metadata. */
+function isBuildArtifact(file) {
+    return (/\.(?:js|mjs|map)$/.test(file) ||
+        file === '3rdpartylicenses.txt' ||
+        file === 'prerendered-routes.json');
+}
+function files(dir) {
+    return (0, node_fs_1.readdirSync)(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = (0, node_path_1.join)(dir, entry.name);
+        return entry.isDirectory() ? files(path) : [path];
+    });
+}

package/schematics/mcp-app-builder/schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "ngx-json-render MCP App builder",
+  "description": "Builds an MCP App view into one view.html and bundles its server into server.mjs.",
+  "type": "object",
+  "properties": {
+    "buildTarget": {
+      "type": "string",
+      "description": "The view's @angular/build:application target, such as \"my-app:build:production\" or \":build:production\" for this project."
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Directory for view.html and server.mjs, relative to the workspace root."
+    },
+    "server": {
+      "type": "string",
+      "description": "The server's entry file, bundled into server.mjs. Leave it out to build the view only."
+    },
+    "tsConfig": {
+      "type": "string",
+      "description": "The tsconfig esbuild reads for the server (paths, decorators). By default, the nearest one to each file."
+    },
+    "externalPackages": {
+      "type": "boolean",
+      "default": false,
+      "description": "Leave node_modules packages out of server.mjs, to be installed next to it. By default the server is one self-contained file."
+    }
+  },
+  "required": ["buildTarget", "outputPath"],
+  "additionalProperties": false
+}