@microsoft/webui 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/** Options for building a WebUI application. */
+export interface BuildOptions {
+    /** Path to the application folder containing templates. */
+    appDir: string;
+    /** Entry HTML file name (default: "index.html"). */
+    entry?: string;
+    /** CSS delivery strategy: "link" (default) or "style". */
+    css?: "link" | "style";
+    /** Parser plugin (e.g., "fast" for FAST-HTML hydration). */
+    plugin?: string;
+    /** Additional component sources (npm packages or local paths). */
+    components?: string[];
+    /** Output directory (used by CLI fallback for build-to-disk). */
+    outDir?: string;
+}
+/** Build statistics. */
+export interface BuildStats {
+    /** Build duration in milliseconds. */
+    durationMs: number;
+    /** Total number of protocol fragments. */
+    fragmentCount: number;
+    /** Number of registered components. */
+    componentCount: number;
+    /** Number of CSS files produced. */
+    cssFileCount: number;
+    /** Size of the serialized protocol in bytes. */
+    protocolSizeBytes: number;
+    /** Number of unique CSS tokens discovered. */
+    tokenCount: number;
+}
+/** Result of a successful build operation. */
+export interface BuildResult {
+    /** Serialized protocol (protobuf binary). */
+    protocol: Buffer;
+    /** CSS files as alternating [filename, content, ...]. */
+    cssFiles: string[];
+    /** Build statistics. */
+    stats: BuildStats;
+}
+/** Complete JSON partial response from the server for client-side navigation. */
+export interface PartialResponse {
+    /** Application state for the matched route. */
+    state: Record<string, unknown>;
+    /** f-template HTML strings the client doesn't already have. */
+    templates: string[];
+    /** Updated hex bitmask of loaded component templates. */
+    inventory: string;
+    /** The request path. */
+    path: string;
+    /** Matched route chain — one entry per nesting level. */
+    chain: Array<{
+        component: string;
+        path: string;
+        params?: Record<string, string>;
+        exact?: boolean;
+    }>;
+}
+/** Build a WebUI application from an app directory. */
+export declare function build(options: BuildOptions): BuildResult;
+/**
+ * Render a pre-compiled protocol with state data.
+ * Uses native addon when available, WASM fallback otherwise.
+ */
+export declare function render(protocol: Buffer, state: object | string): string;
+/**
+ * Render a protocol with streaming output.
+ * Each HTML fragment is passed to the onChunk callback as it is produced.
+ */
+export declare function renderStream(protocol: Buffer, state: object | string, onChunk: (html: string) => void): void;
+/** Build and render in a single call. */
+export declare function buildAndRender(options: BuildOptions, state: object | string): string;
+/** Inspect protocol bytes and return JSON representation. */
+export declare function inspect(protocolData: Buffer): string;
+/**
+ * Produce a complete JSON partial response for client-side navigation.
+ *
+ * Returns a JSON string with `state`, `templates`, `inventory`, `path`, and `chain`.
+ * Pipe directly to the HTTP response — no post-processing needed.
+ *
+ * If you need to inspect the response, parse it with the exported `PartialResponse` type:
+ * ```ts
+ * const partial: PartialResponse = JSON.parse(renderPartial(...));
+ * ```
+ */
+export declare function renderPartial(protocolData: Buffer, stateJson: string, entryId: string, requestPath: string, inventoryHex: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,cAAc,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wBAAwB;IACxB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,KAAK,EAAE,KAAK,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC,CAAC;CACJ;AA2DD,uDAAuD;AACvD,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CAkCxD;AAID;;;GAGG;AACH,wBAAgB,MAAM,CACpB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,MAAM,GACrB,MAAM,CAeR;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC9B,IAAI,CAYN;AAID,yCAAyC;AACzC,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,MAAM,GAAG,MAAM,GACrB,MAAM,CAMR;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,MAAM,CAMR"}

package/dist/index.js

@@ -0,0 +1,128 @@
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import nodePath from "node:path";
+import { resolve, platformKey } from "./platform.js";
+const require2 = createRequire(import.meta.url);
+let addon = null;
+let fallbackWarned = false;
+function loadAddon() {
+  if (addon) return addon;
+  const addonPath = resolve("addon");
+  if (addonPath) {
+    try {
+      if (addonPath.endsWith(".node")) {
+        addon = require2(addonPath);
+      } else {
+        const m = { exports: {} };
+        process.dlopen(m, addonPath);
+        addon = m.exports;
+      }
+      return addon;
+    } catch {
+    }
+  }
+  return null;
+}
+function warnFallback() {
+  if (fallbackWarned) return;
+  fallbackWarned = true;
+  console.warn(
+    `[webui] Native addon not available for ${platformKey()}. Using WASM fallback \u2014 performance may be degraded.
+Install the platform-specific package for optimal performance.`
+  );
+}
+function build(options) {
+  const native = loadAddon();
+  if (native?.build) {
+    return native.build(options);
+  }
+  const binPath = resolve("bin");
+  if (!binPath) {
+    throw new Error(
+      "[webui] Cannot build: no native addon or CLI binary available."
+    );
+  }
+  const args = ["build", options.appDir ?? "."];
+  if (options.entry) args.push("--entry", options.entry);
+  if (options.css) args.push("--css", options.css);
+  if (options.plugin) args.push("--plugin", options.plugin);
+  if (options.components) {
+    for (const c of options.components) {
+      args.push("--components", c);
+    }
+  }
+  if (options.outDir) args.push("--out", options.outDir);
+  execFileSync(binPath, args, { stdio: "inherit" });
+  if (options.outDir) {
+    const protocol = fs.readFileSync(nodePath.join(options.outDir, "protocol.bin"));
+    return { protocol, cssFiles: [], stats: emptyStats() };
+  }
+  return { protocol: Buffer.alloc(0), cssFiles: [], stats: emptyStats() };
+}
+function render(protocol, state) {
+  const native = loadAddon();
+  if (native) {
+    let result = "";
+    const stateStr = typeof state === "string" ? state : JSON.stringify(state);
+    native.render(protocol, stateStr, (chunk) => {
+      result += chunk;
+    });
+    return result;
+  }
+  warnFallback();
+  throw new Error(
+    "[webui] render() requires the native addon. WASM render fallback not yet wired."
+  );
+}
+function renderStream(protocol, state, onChunk) {
+  const native = loadAddon();
+  if (native) {
+    const stateStr = typeof state === "string" ? state : JSON.stringify(state);
+    native.render(protocol, stateStr, onChunk);
+    return;
+  }
+  warnFallback();
+  throw new Error(
+    "[webui] renderStream() requires the native addon. WASM render fallback not yet wired."
+  );
+}
+function buildAndRender(options, state) {
+  const result = build(options);
+  if (!result.protocol || result.protocol.length === 0) {
+    throw new Error("[webui] Build did not return protocol data.");
+  }
+  return render(result.protocol, state);
+}
+function inspect(protocolData) {
+  const native = loadAddon();
+  if (native?.inspect) {
+    return native.inspect(protocolData);
+  }
+  throw new Error("[webui] inspect() requires the native addon.");
+}
+function renderPartial(protocolData, stateJson, entryId, requestPath, inventoryHex) {
+  const native = loadAddon();
+  if (native?.renderPartial) {
+    return native.renderPartial(protocolData, stateJson, entryId, requestPath, inventoryHex);
+  }
+  throw new Error("[webui] renderPartial() requires the native addon.");
+}
+function emptyStats() {
+  return {
+    durationMs: 0,
+    fragmentCount: 0,
+    componentCount: 0,
+    cssFileCount: 0,
+    protocolSizeBytes: 0,
+    tokenCount: 0
+  };
+}
+export {
+  build,
+  buildAndRender,
+  inspect,
+  render,
+  renderPartial,
+  renderStream
+};

package/dist/install.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":""}

package/dist/install.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import { resolve, platformKey, packageName } from "./platform.js";
+try {
+  const binPath = resolve("bin");
+  if (binPath && fs.existsSync(binPath)) {
+    process.exit(0);
+  }
+} catch {
+}
+const key = platformKey();
+let pkg;
+try {
+  pkg = packageName();
+} catch {
+  console.warn(
+    `[webui] Warning: Unsupported platform ${key}. The webui CLI will not be available. Set WEBUI_BINARY_PATH to use a custom binary.`
+  );
+  process.exit(0);
+}
+console.warn(
+  `[webui] Warning: Platform package ${pkg} was not installed. This usually means your package manager was run with --no-optional. The webui CLI and native addon will not be available.
+To fix: reinstall without --no-optional, or set WEBUI_BINARY_PATH.`
+);

package/dist/platform.d.ts

@@ -0,0 +1,11 @@
+export declare function platformKey(): string;
+export declare function packageName(): string;
+/**
+ * Resolve a file from the platform-specific package, with fallback to
+ * local cargo build output for workspace development.
+ *
+ * @param kind — "bin" for CLI binary, "addon" for .node file
+ * @returns Absolute path, or null if not found.
+ */
+export declare function resolve(kind: "bin" | "addon"): string | null;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AA2BA,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,WAAW,IAAI,MAAM,CAUpC;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CA+C5D"}

package/dist/platform.js

@@ -0,0 +1,75 @@
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const require2 = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLATFORMS = {
+  "darwin-arm64": "@microsoft/webui-darwin-arm64",
+  "darwin-x64": "@microsoft/webui-darwin-x64",
+  "linux-x64": "@microsoft/webui-linux-x64",
+  "linux-arm64": "@microsoft/webui-linux-arm64",
+  "win32-x64": "@microsoft/webui-win32-x64",
+  "win32-arm64": "@microsoft/webui-win32-arm64"
+};
+const ADDON_NAMES = {
+  darwin: "libwebui_node.dylib",
+  linux: "libwebui_node.so",
+  win32: "webui_node.dll"
+};
+function platformKey() {
+  return `${process.platform}-${os.arch()}`;
+}
+function packageName() {
+  const key = platformKey();
+  const name = PLATFORMS[key];
+  if (!name) {
+    throw new Error(
+      `[webui] Unsupported platform: ${key}. Supported: ${Object.keys(PLATFORMS).join(", ")}`
+    );
+  }
+  return name;
+}
+function resolve(kind) {
+  if (kind === "bin" && process.env["WEBUI_BINARY_PATH"]) {
+    return process.env["WEBUI_BINARY_PATH"];
+  }
+  if (kind === "addon" && process.env["WEBUI_ADDON_PATH"]) {
+    return process.env["WEBUI_ADDON_PATH"];
+  }
+  try {
+    const pkg = packageName();
+    const pkgDir = path.dirname(require2.resolve(`${pkg}/package.json`));
+    if (kind === "bin") {
+      const binName = process.platform === "win32" ? "webui.exe" : "webui";
+      const binPath = path.join(pkgDir, "bin", binName);
+      if (existsSync(binPath)) return binPath;
+    } else {
+      const addonPath = path.join(pkgDir, "webui.node");
+      if (existsSync(addonPath)) return addonPath;
+    }
+  } catch {
+  }
+  const workspaceRoot = path.resolve(__dirname, "..", "..", "..");
+  const releasePath = path.join(workspaceRoot, "target", "release");
+  if (kind === "bin") {
+    const binName = process.platform === "win32" ? "webui.exe" : "webui";
+    const binPath = path.join(releasePath, binName);
+    if (existsSync(binPath)) return binPath;
+    const debugPath = path.join(workspaceRoot, "target", "debug", binName);
+    if (existsSync(debugPath)) return debugPath;
+  } else {
+    const addonName = ADDON_NAMES[process.platform] ?? "libwebui_node.so";
+    const addonPath = path.join(releasePath, addonName);
+    if (existsSync(addonPath)) return addonPath;
+    const debugPath = path.join(workspaceRoot, "target", "debug", addonName);
+    if (existsSync(debugPath)) return debugPath;
+  }
+  return null;
+}
+export {
+  packageName,
+  platformKey,
+  resolve
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "bin": {
+    "webui": "bin/webui"
+  },
+  "description": "WebUI — high-performance server-side rendering framework. Build-time protocol compiler and streaming renderer.",
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "esbuild": "^0.27.3",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "default": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      }
+    }
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "wasm/"
+  ],
+  "license": "MIT",
+  "name": "@microsoft/webui",
+  "optionalDependencies": {
+    "@microsoft/webui-darwin-arm64": "0.0.1",
+    "@microsoft/webui-darwin-x64": "0.0.1",
+    "@microsoft/webui-linux-arm64": "0.0.1",
+    "@microsoft/webui-linux-x64": "0.0.1",
+    "@microsoft/webui-win32-arm64": "0.0.1",
+    "@microsoft/webui-win32-x64": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicolo-ribaudo/nicolo-nicolo.git"
+  },
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "build": "esbuild src/index.ts src/platform.ts src/install.ts --outdir=dist --format=esm --platform=node && tsc --emitDeclarationOnly",
+    "postinstall": "node --input-type=module -e \"try{await import('./dist/install.js')}catch{}\"",
+    "test": "esbuild test/integration.test.ts --outfile=test/integration.test.js --format=esm --platform=node && node --test test/integration.test.js"
+  }
+}