@microsoft/webui 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,116 @@
+# @microsoft/webui
+
+High-performance server-side rendering framework. Compiles HTML templates into a binary protocol at build time and renders them with native speed at runtime — no JavaScript runtime overhead.
+
+## Installation
+
+```bash
+npm install @microsoft/webui
+```
+
+The package automatically installs the correct platform-specific native binary for your OS and architecture (Windows, macOS, Linux — x64 and arm64).
+
+## Quick start
+
+```js
+import { build, render } from "@microsoft/webui";
+
+// Build templates into a protocol
+const result = build({ appDir: "./src" });
+
+// Render with state data
+const html = render(result.protocol, { name: "World", items: ["a", "b"] });
+console.log(html);
+```
+
+## API
+
+### `build(options: BuildOptions): BuildResult`
+
+Compiles an application directory of HTML templates into a binary protocol.
+
+```js
+const result = build({
+  appDir: "./src",        // Path to the template directory
+  entry: "index.html",   // Entry file (default: "index.html")
+  css: "link",           // CSS strategy: "link" or "style"
+  plugin: "fast",        // Parser plugin (e.g., "fast" for FAST-HTML)
+  components: [],        // Additional component sources
+  outDir: "./dist",      // Output directory for CLI fallback
+});
+
+// result.protocol  — Buffer containing the compiled protocol
+// result.cssFiles  — Array of [filename, content, ...] pairs
+// result.stats     — { durationMs, fragmentCount, componentCount, cssFileCount, protocolSizeBytes, tokenCount }
+```
+
+### `render(protocol: Buffer, state: object | string): string`
+
+Renders a compiled protocol with state data and returns the full HTML string.
+
+```js
+const html = render(protocol, { title: "Hello", show: true });
+```
+
+### `renderStream(protocol: Buffer, state: object | string, onChunk: (html: string) => void): void`
+
+Renders with streaming output — each HTML fragment is passed to the callback as it is produced.
+
+```js
+renderStream(protocol, state, (chunk) => {
+  response.write(chunk);
+});
+```
+
+### `buildAndRender(options: BuildOptions, state: object | string): string`
+
+Convenience function that builds and renders in a single call.
+
+```js
+const html = buildAndRender({ appDir: "./src" }, { name: "WebUI" });
+```
+
+### `inspect(protocol: Buffer): string`
+
+Returns a JSON representation of the protocol for debugging.
+
+```js
+const json = inspect(protocol);
+console.log(JSON.parse(json));
+```
+
+### `renderPartial(protocol: Buffer, stateJson: string, entryId: string, requestPath: string, inventoryHex: string): string`
+
+Produces a JSON partial response for client-side navigation, including state, templates, and route chain.
+
+## CLI
+
+The package also includes the `webui` CLI binary:
+
+```bash
+# Build templates to disk
+npx webui build ./src --out ./dist
+
+# Start a dev server
+npx webui serve ./src --state ./data/state.json --port 3000
+
+# Inspect a compiled protocol
+npx webui inspect ./dist/protocol.bin
+```
+
+## Platform support
+
+| OS | Architecture | Package |
+|---|---|---|
+| Windows | x64 | `@microsoft/webui-win32-x64` |
+| Windows | arm64 | `@microsoft/webui-win32-arm64` |
+| macOS | arm64 | `@microsoft/webui-darwin-arm64` |
+| macOS | x64 | `@microsoft/webui-darwin-x64` |
+| Linux | x64 | `@microsoft/webui-linux-x64` |
+| Linux | arm64 | `@microsoft/webui-linux-arm64` |
+
+Platform-specific packages are installed automatically as optional dependencies.
+
+## License
+
+[MIT](https://github.com/microsoft/webui/blob/main/LICENSE)

package/dist/index.d.ts

@@ -37,6 +37,15 @@ export interface BuildResult {
     /** Build statistics. */
     stats: BuildStats;
 }
+/** Options for rendering a protocol. */
+export interface RenderOptions {
+    /** Fragment ID to start rendering from (default: "index.html"). */
+    entry?: string;
+    /** URL path to match routes against (default: "/"). */
+    requestPath?: string;
+    /** Parser plugin name (e.g., "fast" for FAST-HTML hydration). */
+    plugin?: string;
+}
 /** Complete JSON partial response from the server for client-side navigation. */
 export interface PartialResponse {
     /** Application state for the matched route. */
@@ -61,14 +70,14 @@ 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;
+export declare function render(protocol: Buffer, state: object | string, options?: RenderOptions): 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;
+export declare function renderStream(protocol: Buffer, state: object | string, onChunk: (html: string) => void, options?: RenderOptions): void;
 /** Build and render in a single call. */
-export declare function buildAndRender(options: BuildOptions, state: object | string): string;
+export declare function buildAndRender(options: BuildOptions, state: object | string, renderOpts?: RenderOptions): string;
 /** Inspect protocol bytes and return JSON representation. */
 export declare function inspect(protocolData: Buffer): string;
 /**

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -60,14 +60,16 @@ function build(options) {
   }
   return { protocol: Buffer.alloc(0), cssFiles: [], stats: emptyStats() };
 }
-function render(protocol, state) {
+function render(protocol, state, options) {
   const native = loadAddon();
   if (native) {
     let result = "";
     const stateStr = typeof state === "string" ? state : JSON.stringify(state);
-    native.render(protocol, stateStr, (chunk) => {
+    const entry = options?.entry ?? "index.html";
+    const requestPath = options?.requestPath ?? "/";
+    native.render(protocol, stateStr, entry, requestPath, (chunk) => {
       result += chunk;
-    });
+    }, options?.plugin);
     return result;
   }
   warnFallback();
@@ -75,11 +77,13 @@ function render(protocol, state) {
     "[webui] render() requires the native addon. WASM render fallback not yet wired."
   );
 }
-function renderStream(protocol, state, onChunk) {
+function renderStream(protocol, state, onChunk, options) {
   const native = loadAddon();
   if (native) {
     const stateStr = typeof state === "string" ? state : JSON.stringify(state);
-    native.render(protocol, stateStr, onChunk);
+    const entry = options?.entry ?? "index.html";
+    const requestPath = options?.requestPath ?? "/";
+    native.render(protocol, stateStr, entry, requestPath, onChunk, options?.plugin);
     return;
   }
   warnFallback();
@@ -87,12 +91,12 @@ function renderStream(protocol, state, onChunk) {
     "[webui] renderStream() requires the native addon. WASM render fallback not yet wired."
   );
 }
-function buildAndRender(options, state) {
+function buildAndRender(options, state, renderOpts) {
   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);
+  return render(result.protocol, state, renderOpts);
 }
 function inspect(protocolData) {
   const native = loadAddon();

package/package.json

@@ -27,19 +27,19 @@
   "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"
+    "@microsoft/webui-darwin-arm64": "0.0.2",
+    "@microsoft/webui-linux-arm64": "0.0.2",
+    "@microsoft/webui-darwin-x64": "0.0.2",
+    "@microsoft/webui-linux-x64": "0.0.2",
+    "@microsoft/webui-win32-arm64": "0.0.2",
+    "@microsoft/webui-win32-x64": "0.0.2"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/nicolo-ribaudo/nicolo-nicolo.git"
+    "url": "https://github.com/microsoft/webui.git"
   },
   "type": "module",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "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{}\"",