@microsoft/fast-build 0.6.0 → 0.8.0-fast-element-v3-rc-20260615

package/README.md

@@ -38,9 +38,10 @@ fast build [options]
 | `--entry="<path>"` | `index.html` | Entry HTML template to render |
 | `--state="<path>"` | `{}` when omitted | JSON file containing the template state. If omitted, no state file is loaded and rendering uses an empty state object. If `--state` is provided, the file must exist. |
 | `--output="<path>"` | `output.html` | Where to write the rendered HTML |
-| `--templates="<glob>"` | _(none)_ | Glob pattern(s) for custom element template HTML files. Separate multiple patterns with commas. A warning is printed if not provided or if no files match a pattern. |
+| `--templates="<glob>"` | _(none)_ | Glob pattern(s) for custom element template HTML files. Separate multiple patterns with commas. A warning is printed if not provided in non-streaming mode or if no files match a pattern. |
 | `--attribute-name-strategy="<strategy>"` | `camelCase` | Strategy for mapping HTML attribute names to state property names on custom elements. `"camelCase"` converts dashes to camelCase (e.g. `foo-bar` → `fooBar`). `"none"` preserves dashes (e.g. `foo-bar` → `foo-bar`). See [Attribute name strategy](#attribute-name-strategy). |
 | `--config="<path>"` | `fast-build.config.json` | Path to a JSON configuration file. If omitted, `fast-build.config.json` in the current directory is used when present. CLI arguments take precedence over config values. See [Configuration file](#configuration-file). |
+| `--stream[=true/false]` | `false` | Write rendered HTML chunks directly to stdout instead of writing `--output`. Valueless `--stream` is treated as `true`. |
 
 ### Example
 
@@ -81,6 +82,32 @@ Produces `output.html`:
 </html>
 ```
 
+### Streaming output
+
+Pass `--stream`, `--stream=true`, or `--stream=false`, or set
+`"stream": true` in `fast-build.config.json`, to control stdout streaming. When
+streaming is enabled, the CLI writes raw rendered HTML chunks to stdout, does
+not write the `--output` file, and does not print the normal `Built: ...`
+message.
+
+```shell
+fast build --entry=index.html --state=state.json --stream
+```
+
+Streaming is simulated by the WebAssembly renderer: chunks are prepared in
+memory, returned to JavaScript as a JSON array, parsed by the CLI, and then
+written to stdout. `--stream` uses the same entry renderer with its stream flag
+enabled and passes an empty templates map when no `--templates` glob is
+provided. Chunk boundaries are safe for HTML parsing:
+
+- Attribute bindings stay within complete opening tag chunks.
+- Custom element opening chunks include the complete Declarative Shadow DOM
+  template.
+- Streamed output uses the same renderer preprocessing and custom-element host
+  attribute propagation as normal output.
+- Empty chunks are omitted.
+- Concatenating all chunks matches the normal non-streamed render.
+
 ### Missing or omitted state
 
 State is optional. When `--state` is omitted and no `state` path is provided by config, `fast build` does not look for `state.json`; rendering uses an empty object (`{}`). An explicit `--state` path, or a `state` path from config, must exist or the command exits with an error.
@@ -117,7 +144,7 @@ Template files must use the following format:
 </f-template>
 ```
 
-If an `<f-template>` element has no `name` attribute, a warning is printed and it is ignored. Exact file paths (no wildcards) are also accepted as patterns, making it possible to register a single template file.
+If an `<f-template>` element has no `name` attribute, a warning is printed and it is ignored. Exact file paths (no wildcards) are also accepted as patterns, making it possible to register a single template file. The parser follows browser tag boundaries for the `<f-template>` and inner `<template>` wrappers, including ASCII whitespace before `>` in opening and closing tags.
 
 Any `shadowroot*` attributes on `<f-template>` are forwarded to the rendered Declarative Shadow DOM `<template>`. The CLI normalizes `shadowrootmode` and legacy `shadowroot` for compatibility: when neither has a non-empty value, it emits `shadowrootmode="open" shadowroot="open"`; when exactly one has a non-empty value, that value is mirrored to the other; when both have explicit non-empty values, both are preserved as authored, even if they conflict.
 
@@ -167,8 +194,10 @@ fast build --config=configs/my-build.json
 
 **Path resolution:** File paths in the config file (`entry`, `state`, `output`, `templates`) are resolved relative to the config file's directory, not the current working directory. This ensures the config works correctly regardless of where the CLI is invoked.
 
-All keys are optional. Only the following keys are allowed: `entry`, `state`, `output`, `templates`, `attribute-name-strategy`. Unknown keys or non-string values produce an error. If `state` is omitted, rendering uses `{}`; if `state` is present, the referenced file must exist.
+All keys are optional. Only the following keys are allowed: `entry`, `state`, `output`, `templates`, `attribute-name-strategy`, and `stream`. Unknown keys produce an error. Values must be strings except `stream`, which must be a JSON boolean (`true` or `false`). If `state` is omitted, rendering uses `{}`; if `state` is present, the referenced file must exist. CLI arguments always override config values, including `--stream=false` overriding `"stream": true`.
 
 ## Template syntax
 
-Template syntax follows the FAST declarative HTML format. See the [`@microsoft/fast-html` README](../fast-html/README.md) for full documentation on bindings, conditionals, repeats, and directives.
+Template syntax follows the FAST declarative HTML format. See the
+[`@microsoft/fast-element` declarative documentation](../fast-element/DECLARATIVE_HTML.md)
+for full documentation on bindings, conditionals, repeats, and directives.

package/bin/fast.js

@@ -7,16 +7,21 @@ const path = require("path");
 
 const WASM_MODULE = path.join(__dirname, "../wasm/microsoft_fast_build.js");
 const DEFAULT_CONFIG_FILENAME = "fast-build.config.json";
+const VALUELESS_CLI_FLAGS = new Set(["stream"]);
 const ALLOWED_CONFIG_KEYS = new Set([
     "entry",
     "state",
     "output",
     "templates",
     "attribute-name-strategy",
+    "stream",
 ]);
 
+/** @typedef {Record<string, string | boolean>} FastBuildConfig */
+
 /**
- * Parse CLI arguments of the form --key="value" or --key=value.
+ * Parse CLI arguments of the form --key="value", --key=value, or supported
+ * valueless flags like --stream.
  * @param {string[]} argv
  * @returns {Record<string, string>}
  */
@@ -26,11 +31,48 @@ function parseArgs(argv) {
         const match = arg.match(/^--([^=]+)=(.*)$/s);
         if (match) {
             args[match[1]] = match[2].replace(/^"|"$/g, "");
+            continue;
+        }
+
+        const flag = arg.match(/^--([^=]+)$/s);
+        if (flag && VALUELESS_CLI_FLAGS.has(flag[1])) {
+            args[flag[1]] = "true";
         }
     }
     return args;
 }
 
+/**
+ * Resolve a boolean option, preferring CLI args over config values.
+ * CLI values accept true, false, or an empty valueless flag.
+ * @param {Record<string, string>} args - Parsed CLI arguments.
+ * @param {FastBuildConfig} config - Parsed config file values.
+ * @param {string} key - The option key.
+ * @returns {boolean}
+ */
+function resolveBooleanOption(args, config, key) {
+    if (Object.prototype.hasOwnProperty.call(args, key)) {
+        const value = args[key].trim().toLowerCase();
+        if (value === "true" || value === "") {
+            return true;
+        }
+        if (value === "false") {
+            return false;
+        }
+
+        process.stderr.write(
+            `Error: Invalid --${key} value "${args[key]}". Expected "true" or "false".\n`
+        );
+        process.exit(1);
+    }
+
+    if (Object.prototype.hasOwnProperty.call(config, key)) {
+        return config[key] === true;
+    }
+
+    return false;
+}
+
 /**
  * Load and validate a fast-build config file.
  *
@@ -42,7 +84,7 @@ function parseArgs(argv) {
  * file's directory so that the caller can use them directly.
  *
  * @param {string | undefined} configPath - Explicit path from --config, if any.
- * @returns {{ config: Record<string, string>, configDir: string | null }}
+ * @returns {{ config: FastBuildConfig, configDir: string | null }}
  */
 function loadConfig(configPath) {
     /** @type {string} */
@@ -92,6 +134,16 @@ function loadConfig(configPath) {
             );
             process.exit(1);
         }
+        if (key === "stream") {
+            if (typeof raw[key] !== "boolean") {
+                process.stderr.write(
+                    `Error: Value for "${key}" in config file "${resolvedPath}" must be a boolean.\n`
+                );
+                process.exit(1);
+            }
+            continue;
+        }
+
         if (typeof raw[key] !== "string") {
             process.stderr.write(
                 `Error: Value for "${key}" in config file "${resolvedPath}" must be a string.\n`
@@ -110,7 +162,7 @@ function loadConfig(configPath) {
  * CLI-derived paths are resolved relative to CWD (the default behaviour).
  *
  * @param {Record<string, string>} args - Parsed CLI arguments.
- * @param {Record<string, string>} config - Parsed config file values.
+ * @param {FastBuildConfig} config - Parsed config file values.
  * @param {string | null} configDir - Directory of the config file, or null.
  * @param {string} key - The option key.
  * @param {string} [defaultValue] - Fallback when neither source provides a value.
@@ -122,6 +174,9 @@ function resolveOption(args, config, configDir, key, defaultValue) {
     }
     if (Object.prototype.hasOwnProperty.call(config, key)) {
         const value = config[key];
+        if (typeof value !== "string") {
+            return defaultValue;
+        }
         const isFilePath = key === "entry" || key === "state" || key === "output" || key === "templates";
         if (isFilePath && configDir !== null) {
             return path.resolve(configDir, value);
@@ -223,13 +278,13 @@ function staticPrefixDir(pattern) {
  * @param {string} html
  * @param {string} filePath - used in warning messages
  * @param {object} wasm - the loaded WASM module
- * @returns {{ name: string, content: string, shadowrootAttributes: { name: string, value: string | null }[] }[]}
+ * @returns {{ name: string, content: string, shadowrootAttributes: { name: string, value: string | null }[], hostAttributes: { name: string, value: string | null }[] }[]}
  */
 function parseFTemplates(html, filePath, wasm) {
-    /** @type {{ name: string | null, content: string, shadowrootAttributes?: { name: string, value: string | null }[] }[]} */
+    /** @type {{ name: string | null, content: string, shadowrootAttributes?: { name: string, value: string | null }[], hostAttributes?: { name: string, value: string | null }[] }[]} */
     const parsed = JSON.parse(wasm.parse_f_templates(html));
     const results = [];
-    for (const { name, content, shadowrootAttributes } of parsed) {
+    for (const { name, content, shadowrootAttributes, hostAttributes } of parsed) {
         if (name === null) {
             process.stderr.write(
                 `Warning: <f-template> without a 'name' attribute in '${filePath}': ${content.trim()}\n`
@@ -239,6 +294,7 @@ function parseFTemplates(html, filePath, wasm) {
                 name,
                 content,
                 shadowrootAttributes: shadowrootAttributes || [],
+                hostAttributes: hostAttributes || [],
             });
         }
     }
@@ -252,7 +308,7 @@ function parseFTemplates(html, filePath, wasm) {
  * Warns (but does not error) if the base directory does not exist.
  * @param {string} pattern
  * @param {object} wasm - the loaded WASM module
- * @returns {{ name: string, content: string, shadowrootAttributes: { name: string, value: string | null }[] }[]}
+ * @returns {{ name: string, content: string, shadowrootAttributes: { name: string, value: string | null }[], hostAttributes: { name: string, value: string | null }[] }[]}
  */
 function resolvePattern(pattern, wasm) {
     const baseDir = staticPrefixDir(pattern);
@@ -266,8 +322,8 @@ function resolvePattern(pattern, wasm) {
         if (globMatch(pattern, file)) {
             const html = fs.readFileSync(file, "utf8");
             const templates = parseFTemplates(html, file, wasm);
-            for (const { name, content, shadowrootAttributes } of templates) {
-                results.push({ name, content, shadowrootAttributes });
+            for (const { name, content, shadowrootAttributes, hostAttributes } of templates) {
+                results.push({ name, content, shadowrootAttributes, hostAttributes });
             }
         }
     }
@@ -287,6 +343,7 @@ async function runBuild(args) {
         Object.prototype.hasOwnProperty.call(args, "state") ||
         Object.prototype.hasOwnProperty.call(config, "state");
     const attributeNameStrategy = resolveOption(args, config, configDir, "attribute-name-strategy");
+    const stream = resolveBooleanOption(args, config, "stream");
 
     if (attributeNameStrategy && attributeNameStrategy !== "none" && attributeNameStrategy !== "camelCase") {
         process.stderr.write(
@@ -301,9 +358,11 @@ async function runBuild(args) {
     // Resolve template files
     const templatesMap = {};
     if (!templatesArg) {
-        process.stderr.write(
-            "Warning: --templates was not provided. No custom element templates will be loaded.\n"
-        );
+        if (!stream) {
+            process.stderr.write(
+                "Warning: --templates was not provided. No custom element templates will be loaded.\n"
+            );
+        }
     } else {
         const patterns = templatesArg.split(",").map((p) => p.trim());
         for (const pattern of patterns) {
@@ -313,13 +372,13 @@ async function runBuild(args) {
                     `Warning: No template files found for pattern "${pattern}".\n`
                 );
             }
-            for (const { name, content, shadowrootAttributes } of matches) {
+            for (const { name, content, shadowrootAttributes, hostAttributes } of matches) {
                 if (name in templatesMap) {
                     process.stderr.write(
                         `Warning: Duplicate template name "${name}" — later file overwrites earlier.\n`
                     );
                 }
-                templatesMap[name] = { content, shadowrootAttributes };
+                templatesMap[name] = { content, shadowrootAttributes, hostAttributes };
             }
         }
     }
@@ -346,6 +405,49 @@ async function runBuild(args) {
     }
 
     // Render
+    if (stream) {
+        if (typeof wasm.render_entry_with_templates !== "function") {
+            process.stderr.write(
+                "Error: Streaming requires render_entry_with_templates to be exported by the WASM module.\n"
+            );
+            process.exit(1);
+        }
+
+        const renderedChunks = wasm.render_entry_with_templates(
+            entryContent,
+            JSON.stringify(templatesMap),
+            stateContent,
+            attributeNameStrategy || "",
+            true,
+        );
+
+        /** @type {unknown} */
+        let chunks;
+        try {
+            chunks = JSON.parse(renderedChunks);
+        } catch (e) {
+            process.stderr.write(
+                `Error: Streaming renderer returned invalid JSON: ${e.message}\n`
+            );
+            process.exit(1);
+        }
+
+        if (
+            !Array.isArray(chunks) ||
+            chunks.some((chunk) => typeof chunk !== "string")
+        ) {
+            process.stderr.write(
+                "Error: Streaming renderer must return a JSON array of strings.\n"
+            );
+            process.exit(1);
+        }
+
+        for (const chunk of chunks) {
+            process.stdout.write(chunk);
+        }
+        return;
+    }
+
     let rendered;
     if (Object.keys(templatesMap).length > 0) {
         rendered = wasm.render_entry_with_templates(
@@ -375,6 +477,8 @@ async function main() {
             '  --entry="index.html"   Entry HTML template file (default: index.html)\n' +
             '  --state="state.json"   State JSON file. If omitted, rendering uses\n' +
             '                         an empty state object.\n' +
+            '  --stream[=true|false]  Write rendered HTML chunks to stdout instead\n' +
+            '                         of writing an output file.\n' +
             '  --attribute-name-strategy="camelCase"\n' +
             '                         Strategy for mapping attribute names to property names.\n' +
             '                         "camelCase" (default) or "none".\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/fast-build",
-  "version": "0.6.0",
+  "version": "0.8.0-fast-element-v3-rc-20260615",
   "description": "CLI and Node.js API for server-side rendering of FAST declarative HTML templates.",
   "author": {
     "name": "Microsoft",

package/wasm/microsoft_fast_build.d.ts

@@ -1,6 +1,29 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Apply the FAST code-sample escape to an HTML string.
+ *
+ * Walks the input HTML and, for every `<code>` element, escapes:
+ *
+ * * curly braces (`{` → `&#123;`, `}` → `&#125;`) in text content and
+ *   attribute values — so the FAST template parser does not interpret
+ *   `{{ ... }}` / `{ ... }` inside code samples as bindings;
+ * * angle brackets of FAST directive tags (`<f-when>`, `</f-when>`,
+ *   `<f-repeat>`, `</f-repeat>`, case-insensitive) — so those directive
+ *   tags surface as literal text instead of being activated as real
+ *   elements. Angle brackets of any other tag (`<button>`, custom
+ *   elements, …) are left untouched so they keep rendering as live DOM.
+ *
+ * Non-`<code>` regions of the input are returned verbatim. The function
+ * is idempotent — running it on an already-escaped string is a no-op.
+ *
+ * Intended for build-time tooling that needs to inject author-written
+ * HTML containing `<code>` samples into a rendered page without going
+ * through the full `render_*` pipeline.
+ */
+export function escape_code_samples(html: string): string;
+
 /**
  * Parse all `<f-template>` elements from an HTML string.
  * Returns a JSON array of template metadata objects,
@@ -28,9 +51,11 @@ export function render(entry: string, state?: string | null): string;
  * e.g. `{"my-button": "<template>...</template>"}`, or template metadata objects.
  * `attribute_name_strategy` controls attribute-to-property mapping: `"camelCase"` (default)
  * or `"none"`. Pass an empty string for the default.
- * Returns the rendered HTML or throws a JavaScript error.
+ * Pass `stream: true` to return a JSON array string of stream chunks; in
+ * stream mode, `templates_json` may be `{}`. Omitted or `false` stream
+ * preserves the rendered HTML behavior.
  */
-export function render_entry_with_templates(entry: string, templates_json: string, state?: string | null, attribute_name_strategy?: string | null): string;
+export function render_entry_with_templates(entry: string, templates_json: string, state?: string | null, attribute_name_strategy?: string | null, stream?: boolean | null): string;
 
 /**
  * Render a FAST HTML template with custom element templates and an optional JSON state string.

package/wasm/microsoft_fast_build.js

@@ -1,5 +1,44 @@
 /* @ts-self-types="./microsoft_fast_build.d.ts" */
 
+/**
+ * Apply the FAST code-sample escape to an HTML string.
+ *
+ * Walks the input HTML and, for every `<code>` element, escapes:
+ *
+ * * curly braces (`{` → `&#123;`, `}` → `&#125;`) in text content and
+ *   attribute values — so the FAST template parser does not interpret
+ *   `{{ ... }}` / `{ ... }` inside code samples as bindings;
+ * * angle brackets of FAST directive tags (`<f-when>`, `</f-when>`,
+ *   `<f-repeat>`, `</f-repeat>`, case-insensitive) — so those directive
+ *   tags surface as literal text instead of being activated as real
+ *   elements. Angle brackets of any other tag (`<button>`, custom
+ *   elements, …) are left untouched so they keep rendering as live DOM.
+ *
+ * Non-`<code>` regions of the input are returned verbatim. The function
+ * is idempotent — running it on an already-escaped string is a no-op.
+ *
+ * Intended for build-time tooling that needs to inject author-written
+ * HTML containing `<code>` samples into a rendered page without going
+ * through the full `render_*` pipeline.
+ * @param {string} html
+ * @returns {string}
+ */
+function escape_code_samples(html) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.escape_code_samples(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+exports.escape_code_samples = escape_code_samples;
+
 /**
  * Parse all `<f-template>` elements from an HTML string.
  * Returns a JSON array of template metadata objects,
@@ -68,14 +107,17 @@ exports.render = render;
  * e.g. `{"my-button": "<template>...</template>"}`, or template metadata objects.
  * `attribute_name_strategy` controls attribute-to-property mapping: `"camelCase"` (default)
  * or `"none"`. Pass an empty string for the default.
- * Returns the rendered HTML or throws a JavaScript error.
+ * Pass `stream: true` to return a JSON array string of stream chunks; in
+ * stream mode, `templates_json` may be `{}`. Omitted or `false` stream
+ * preserves the rendered HTML behavior.
  * @param {string} entry
  * @param {string} templates_json
  * @param {string | null} [state]
  * @param {string | null} [attribute_name_strategy]
+ * @param {boolean | null} [stream]
  * @returns {string}
  */
-function render_entry_with_templates(entry, templates_json, state, attribute_name_strategy) {
+function render_entry_with_templates(entry, templates_json, state, attribute_name_strategy, stream) {
     let deferred6_0;
     let deferred6_1;
     try {
@@ -87,7 +129,7 @@ function render_entry_with_templates(entry, templates_json, state, attribute_nam
         var len2 = WASM_VECTOR_LEN;
         var ptr3 = isLikeNone(attribute_name_strategy) ? 0 : passStringToWasm0(attribute_name_strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         var len3 = WASM_VECTOR_LEN;
-        const ret = wasm.render_entry_with_templates(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
+        const ret = wasm.render_entry_with_templates(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, isLikeNone(stream) ? 0xFFFFFF : stream ? 1 : 0);
         var ptr5 = ret[0];
         var len5 = ret[1];
         if (ret[3]) {

package/wasm/microsoft_fast_build_bg.wasm.d.ts

@@ -1,9 +1,10 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const escape_code_samples: (a: number, b: number) => [number, number];
 export const parse_f_templates: (a: number, b: number) => [number, number];
 export const render: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-export const render_entry_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
+export const render_entry_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number, number, number];
 export const render_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;