fast Documentation

Technical Documentation: microsoft/fast

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

FAST

:star: We appreciate your star, it helps!

Introduction Copy Chapter

FAST is dedicated to providing support for native Web Components and modern Web Standards, and it's designed to help you efficiently tackle some of the most common challenges in website and application design and development.

TL;DR

• Create reusable UI components with @microsoft/fast-element, all based on W3C Web Component standards.
• Integrate FAST Web Components with any library, framework, or build system. You can adopt incrementally without re-writing your existing systems.

For an in-depth explanation of FAST see our docs introduction.

Packages Copy Chapter

`@microsoft/fast-element` Copy Section

The @microsoft/fast-element library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with @microsoft/fast-element see the Getting Started guide.

`@fluentui/web-components` Copy Section

@fluentui/web-components is a library of Web Components based on the Fluent design language, built with @microsoft/fast-element.

The source for @fluentui/web-components is hosted in the Fluent UI monorepo.

Getting Started Copy Chapter

We hope you're excited by the possibilities that FAST presents. But, you may be wondering where to start. Here are a few statements that describe various members of our community. We recommend that you pick the statement you most identify with and follow the links where they lead. You can always come back and explore another topic at any time.

• "I just want ready-made components!"
  • Check out the FluentUI Web Components.
• "I want to build my own components."
  • Jump to the fast-element docs.
• "I need to integrate FAST with another framework or build system."
  • Jump to the integration docs.
• "I want to look at a quick reference."
  • Jump to the Cheat Sheet (only available in 1.x)

Roadmap Copy Chapter

Major features for the FAST project can be found in the roadmap.

Joining the Community Copy Chapter

Looking to get answers to questions or engage with us in realtime? Our community is most active on Discord. Submit requests and issues on GitHub, or join us by contributing on some good first issues via GitHub.

Get started here with the Contributor Guide.

We look forward to building an amazing open source community with you!

Contact Copy Chapter

• Join the community and chat with us in real-time on Discord.
• Submit requests and issues on GitHub.
• Contribute by helping out on some of our recommended first issues on GitHub.

Overview (`examples/README.md`) Copy Section

FAST example apps

The examples/ workspace hosts small, focused applications that show how to
build real UI with FAST using production-shaped tooling, app structure, and
styling. It is aimed at contributors, library consumers, and anyone evaluating
FAST patterns in a complete app context.

Apps Copy Chapter

Example apps are grouped by rendering strategy. Client-side-rendered (CSR)
apps live under examples/csr/ and server-side-rendered (SSR) apps
live under examples/ssr/.

Shared design system Copy Chapter

Every example app must consume @microsoft/fast-examples-design-system. The
package is CSS-only — it ships a single stylesheet (tokens.css) and no
JavaScript or TypeScript. Apps wire theme switching themselves using the
data-theme attribute on <html>.

The package exposes a single import:

Style components with semantic tokens such as
--fast-background-layer-primary-solid,
--fast-foreground-ctrl-neutral-primary-rest,
--fast-background-ctrl-brand-rest, --fast-text-global-body3-font-size,
--fast-padding-content-medium, and --fast-corner-large. Never hard-code
colors, font sizes, padding, gaps, corners, stroke widths, shadows,
durations, or curves.

See:

• examples/design-system/README.md — quickstart,
  available imports, token catalog.
• examples/design-system/DESIGN.md — naming
  grammar, role catalog, theme model, and rules for adding tokens (the
  canonical authoring guide for both humans and coding agents).
• examples/DESIGN.md — workspace-level guidance for building
  new example apps on top of the design system.

Creating a new example app Copy Chapter

1. Scaffold a new folder under the appropriate rendering-strategy subfolder
   (CSR apps go under examples/csr/<your-app>/; SSR apps go under
   examples/ssr/<your-app>/).
2. Use examples/csr/todo-app/ as a reference for CSR
   apps, or examples/ssr/chat-app/ /
   examples/ssr/webui-todo-app/ as a reference
   for SSR apps (package.json, tsconfig.json, build config, entry HTML).
3. Add "@microsoft/fast-examples-design-system": "^1.0.0" to the new
   app's dependencies and run npm install from the repo root.
4. Import @microsoft/fast-examples-design-system/tokens.css exactly once at
   the app entry point (typically src/main.ts or src/index.ts). For an
   intentionally single-theme app, hard-code <html data-theme="light"> (or
   "dark") in the entry HTML and never touch it from JavaScript.
5. Reference tokens via var(--fast-...) in component css template
   literals or .css files — do not hard-code design values.
6. If the app needs a theme toggle, set or remove the data-theme attribute
   on <html> from your app code:
   ts Copy

   document.documentElement.setAttribute("data-theme", "dark");
   document.documentElement.removeAttribute("data-theme"); // restore system

   Do not import any JavaScript from the design-system package — it
   intentionally exposes none.
7. Add the new app to the table at the top of this file.

Running an example Copy Chapter

From the repository root:

npm install
npm start -w @microsoft/fast-<your-app>-example

For the existing example apps:

npm start -w @microsoft/fast-todo-app-example
npm start -w @microsoft/fast-todo-mobx-app-example
npm start -w @microsoft/fast-chat-app-example
npm start -w @microsoft/fast-webui-todo-app-example

Useful links Copy Chapter

• Examples design guide
• Examples design-system package
• FAST repository README
• FAST documentation

Overview (`packages/README.md`) Copy Section

FAST Packages

Our web component packages.

`@microsoft/fast-element` Copy Chapter

The @microsoft/fast-element library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with @microsoft/fast-element see the Getting Started guide.

`@microsoft/fast-router` Copy Chapter

The @microsoft/fast-router package contains a history-based navigation and routing solution designed around Web Components. By using fast-router, you can create multi-page and full application experiences. The router works with any Web Components, but has special support for Web Components built on FAST.

Overview (`.github/workflows/README.md`) Copy Section

Testing

To test workflows, use the GitHub CLI and trigger the workflow from a branch.

For more information see the GitHub CLI documentation.

Draft Pull Requests Copy Chapter

All CI workflows that run against pull requests are configured to skip draft PRs:

• GitHub Actions (ci-validate-pr.yml, ci-validate-platforms.yml, ci-validate-rust.yml): The pull_request trigger includes ready_for_review in its event types, and each job has a condition that skips execution when the PR is a draft. When a draft PR is marked as ready for review, the workflows will automatically trigger.
• Azure Pipelines (azure-pipelines-bench.yml, azure-pipelines-ci.yml): The pr trigger uses drafts: false to prevent pipeline runs on draft PRs.

Continuous Deployment Copy Chapter

Nightly publishing is coordinated across GitHub Actions and Azure Pipelines so that npm credentials never leave the Azure environment. GitHub Releases are the source of truth, and deployed/<tag> git marker tags track which releases have already been published.

• cd-github-releases.yml (GitHub Actions) runs nightly via cron (0 8 * * * UTC, ~12am PST) and on workflow_dispatch. It does not bump versions or push source changes to main — version bumps land on main through ordinary human-authored pull requests (for example, by running npm run bump locally and opening a PR). The cron is scheduled ~1 hour before the Azure CD pipeline (09:00 UTC) so any GitHub releases this job creates are picked up by that same night's publish run. The workflow has two jobs:
  1. detect — checks out main with fetch-depth: 0 and runs build/scripts/create-github-releases.mjs --check-only. The script walks the workspaces tree (no npm ci required), computes ${name}_v${version} for every non-private workspace, and emits hasMissingReleases=true if any of those git tags do not yet exist.
  2. release runs only when missing releases exist. Installs Node, the Rust toolchain (for cargo package), and the npm workspace dependencies, builds the repo, then runs the script in default mode. For every missing release the script: packs the npm tarball into publish_artifacts_npm/, packs any paired Rust crates into publish_artifacts_crates/, and creates the GitHub release with all assets attached via gh release create --target <sha>. @microsoft/fast-build is a bundled release: it uses one npm package, one tag, and one GitHub release containing both microsoft-fast-build and microsoft-fast-convert crate assets. The gh CLI creates the git tag atomically with the release, so "tag exists" and "release exists" are always the same fact — a failed release is safely retried on the next workflow run, with no orphan tag stranded behind. The script errors if a paired crate's version does not match the npm package's version — but this is purely a safety net: the postbump hook in beachball.config.js rewrites each crate's Cargo.toml (and the matching entry in Cargo.lock) automatically whenever npm run bump bumps the paired npm package, so they stay in sync from the same commit.
• azure-pipelines-cd.yml (Azure Pipelines) runs every night at 1am PST (0 9 * * * UTC) with always: true so it still runs on no-op nights (it is checking external GitHub state, not repo commits). It is split into two stages so the heavy publish work is skipped on no-op nights:
  1. Check — runs build/scripts/download-github-releases.mjs --check-only. The script walks the current publishable workspaces, keeps only workspaces whose current ${name}_v${version} release tag exists, filters out tags that already have a deployed/<tag> counterpart, and emits Azure Pipelines output variables for the overall deployment decision, npm dist-tag, and each package-specific release tag. No network calls to GitHub, npm, or crates.io are needed.
  2. Package — depends on Check and runs only when needsDeployment == 'true'. Its PrepareReleaseInputs job downloads undeployed release assets through the fast GitHub service connection, sorts them into publish_artifacts_npm/ (.tgz) and publish_artifacts_crates/ (.crate), configures the detected npm dist-tag, and publishes those files as a governed pipeline artifact. The checkout-free Deploy release job consumes that artifact through templateContext.inputs, then FAST.Release.PipelineTemplate.yml@fastPipelines performs the actual npm publish / cargo publish. After publishing succeeds, the ordinary MarkDeployed job checks out the repository and pushes a deployed/<tag> marker for each release. The next nightly run sees those markers and skips the corresponding releases.

Both scripts are thin Node.js wrappers around existing CLI tools and repository metadata — no extra npm dependencies and no custom GitHub API client. Idempotency is enforced entirely through git tags (${name}_v${version} on the GitHub side, deployed/${name}_v${version} on the Azure side), so neither side needs to talk to npm.org or crates.io to decide whether work is required.

Adding a publishable package Copy Section

cd-github-releases.yml discovers publishable workspaces automatically from the root package.json workspaces list, but azure-pipelines-cd.yml must be updated because Azure Pipelines cannot create DownloadGitHubRelease@0 tasks dynamically from the runtime detection output.

The npm run checkchange command runs build/scripts/check-publish-pipeline.mjs to verify that every non-private workspace has matching Azure CD variables and a conditional DownloadGitHubRelease@0 task. This guardrail runs in PR validation and fails when a new publishable package is added without updating the publish pipeline.

When adding a new non-private workspace that should publish through CD:

1. Ensure the workspace is included in the root package.json workspaces list and has a name and version.
2. If the package has paired crate assets, place each crate at crates/<crate-name>/Cargo.toml. By default, <crate-name> is the npm package name with the leading @ removed and / replaced by -. @microsoft/fast-build is the special bundled release and pairs with both crates/microsoft-fast-build/Cargo.toml and crates/microsoft-fast-convert/Cargo.toml.
3. Add package-specific output variables to the Package stage in azure-pipelines-cd.yml. The output prefix is generated from the npm package name by converting @microsoft/<name> to camel case. For example, @microsoft/fast-foo emits fastFooNeedsDeployment and fastFooReleaseTag.
4. Add a conditional DownloadGitHubRelease@0 task to PrepareReleaseInputs using the fast GitHub service connection, defaultVersionType: 'specificTag', and the package's $(ReleaseTag) variable. Release jobs cannot check out source or directly acquire undeclared dependencies, so all downloaded assets must remain part of the governed fast-release-inputs pipeline artifact.
5. Confirm the artifact sorting step still covers the package assets. Packages should attach .tgz assets, and paired crates should also attach .crate assets.

Example Azure additions for @microsoft/fast-foo:

variables:
  fastFooNeedsDeployment: $[ stageDependencies.Check.CheckVersion.outputs['deploymentCheck.fastFooNeedsDeployment'] ]
  fastFooReleaseTag: $[ stageDependencies.Check.CheckVersion.outputs['deploymentCheck.fastFooReleaseTag'] ]

steps:
- task: DownloadGitHubRelease@0
  displayName: "Download @microsoft/fast-foo release assets"
  condition: and(succeeded(), eq(variables['fastFooNeedsDeployment'], 'true'))
  inputs:
    connection: fast
    userRepository: microsoft/fast
    defaultVersionType: 'specificTag'
    version: '$(fastFooReleaseTag)'
    downloadPath: '$(System.ArtifactsDirectory)'

Overview (`crates/microsoft-fast-build/README.md`) Copy Section

microsoft-fast-build

A server-side renderer for FAST declarative HTML templates, written in pure Rust with no native runtime dependencies.

It takes FAST declarative HTML template syntax and a JSON state object, resolves bindings, evaluates conditionals, iterates repeats, and renders custom elements — producing static HTML ready to be served.

Installation Copy Chapter

Add the crate to your Cargo.toml:

[dependencies]
microsoft-fast-build = "0.1"

Or use cargo add:

cargo add microsoft-fast-build

Usage Copy Chapter

Render with a JSON string Copy Section

use microsoft_fast_build::render_template;

let html = render_template(
    "<h1>{{title}}</h1>",
    r#"{"title": "Hello, World!"}"#,
)?;
// html == "<h1>Hello, World!</h1>"

Render with a parsed `JsonValue` Copy Section

use microsoft_fast_build::{render, JsonValue};
use std::collections::HashMap;

let mut map = HashMap::new();
map.insert("name".to_string(), JsonValue::String("Alice".to_string()));
let state = JsonValue::Object(map);

let html = render("<p>{{name}}</p>", &state)?;
// html == "<p>Alice</p>"

Both functions return Result<String, RenderError>. See Error Handling.

Render simulated stream chunks Copy Section

Streaming APIs return precomputed HTML chunks in memory. Joining the chunks
matches the equivalent non-streamed render, while chunk boundaries are chosen
around content bindings and custom elements. Stream rendering uses the same
top-level preprocessing as normal rendering, including automatic escaping of
FAST-like syntax inside <code> elements.

use microsoft_fast_build::{render_template, render_template_stream};

let chunks = render_template_stream(
    "<p>{{message}}</p>",
    r#"{"message": "Hello"}"#,
    None,
)?;

let html = render_template(
    "<p>{{message}}</p>",
    r#"{"message": "Hello"}"#,
    None,
)?;

assert_eq!(chunks, vec!["<p>", "Hello", "</p>"]);
assert_eq!(chunks.join(""), html);

Custom element streaming uses the *_stream_with_locator and
render_entry_*_stream_with_locator APIs. For entry HTML, a custom element's
opening tag chunk includes the complete Declarative Shadow DOM template; light
DOM content follows in later chunks. Template host attributes declared on the
inner <template> element are merged onto the streamed host opening tag with
the same author-wins and client-only-attribute filtering rules as normal
rendering.

Plugin integration APIs Copy Chapter

render_shadow_root_with_locator(element_name, state, locator, config) renders
only the complete Declarative Shadow DOM <template> fragment. Its JSON-state
counterpart is render_shadow_root_template_with_locator(element_name, state: Option<&str>, locator, config). Pass resolved component state;
these APIs do not synthesize a host, overlay host attributes, emit template-host
attributes, or render caller-owned light DOM. Nested components, code-sample
escaping, and fresh v3/v2 hydration scopes use the whole-host rendering path.
Unknown template names and invalid JSON state return explicit errors.

use microsoft_fast_build::{
    parse_f_templates, render_shadow_root_template_with_locator, Locator,
};

let definitions = parse_f_templates(
    r#"<f-template name="my-card"><template>{{title}}</template></f-template>"#,
);
let locator = Locator::from_metadata(definitions)?;
let fragment = render_shadow_root_template_with_locator(
    "my-card", Some(r#"{"title":"Hello"}"#), &locator, None,
)?;

parse_f_templates is also a public native API. It returns Vec<FTemplate>
with format_version, bindings, name/content, and host/shadow-root attributes.
BindingMetadata records direct names, expressions, syntax kinds, lexical
paths, and nested BindingScope { variable, iterable } frames. Application
types and required/optional declarations remain unknown (None); repeat
collections alone have a known array requirement. Metadata describes syntax,
not a state schema or a full validation certificate. Code samples are excluded.
Locator::from_metadata validates names, duplicates, and the format version.
Legacy content/tuple constructors remain supported.

Each BindingMetadata also has a span: SourceSpan containing start and end
SourcePosition records. Positions refer to the complete original input to
parse_f_templates, including document prefixes and whitespace removed from the
returned content. offset is zero-based UTF-16, not a Rust byte index; line
and column are one-based, with columns measured in UTF-16 code units. Tabs count
as one column and non-BMP characters as two. CRLF is one line break and two offset
units; lone CR and LF each start a new line.

Spans are half-open and cover trimmed expressions without braces. Repeat spans
cover the iterable, matching the existing expression metadata; lexical scopes are
unchanged. Attribute entities retain their authored spelling. Code-sample
preprocessing does not shift later spans. Bindings and FAST directive markup
inside HTML comments remain unsupported.

The WASM exports are parse_f_templates(html) (JSON metadata array) and
render_shadow_root(elementName, templatesJson, state?, attributeNameStrategy?, markers_v2?). Generated declarations include FTemplateMetadata,
TemplateBinding, TemplateBindingScope, TemplateSourceSpan, and
TemplateSourcePosition. Each generated record has
formatVersion: 1; render exports reject unsupported or malformed explicit
versions, while still accepting unversioned maps and string-valued definitions.

Nullable and boolean attributes Copy Section

Missing or explicit null bindings omit the entire attribute, including when
embedded in a literal value such as href="/prefix/{{value}}". An explicit
empty string remains href="". Boolean JSON values bound to known HTML boolean
attributes use presence/absence; ordinary attributes such as aria-hidden
still serialize booleans as "true"/"false". ?name="{{expr}}" remains the
recommended truthy/falsy form for matching browser-side FAST behavior.
Omitted bindings still reserve hydration slots. An author binding that resolves
to absence overrides template-host defaults rather than reintroducing them.
See the migration guide
for intentional changes from earlier output.

Template Syntax Copy Chapter

Bindings and FAST directive markup inside HTML comments are unsupported.
Commenting out bound markup does not reliably disable its bindings and can cause
rendering errors or client hydration mismatches. Remove unused bound markup
instead, and keep explanatory comments free of binding syntax and FAST directive
tags.

Content Bindings Copy Section

<h1>{{title}}</h1>
<div>{{{richContent}}}</div>

Single-Brace Passthrough Copy Section

Single-brace expressions ({expr}) are FAST client-side-only bindings (event handlers, attribute directives). They are never interpreted by the server renderer.

In non-hydration rendering they pass through verbatim. When rendering Declarative Shadow DOM (inside a custom element's shadow template), client-side attribute directives — f-ref, f-slotted, f-children — are stripped from the HTML output, just like @event and :property bindings. The data-fe binding count still includes them so the FAST runtime can allocate the correct number of binding slots.

<slot f-slotted="{slottedNodes}"></slot>
<video f-ref="{video}"></video>
<ul f-children="{listItems}"></ul>


<slot data-fe="1"></slot>
<video data-fe="1"></video>
<ul data-fe="1"></ul>

Boolean Attribute Bindings — `?attr` Copy Section

The ?attr="{{expr}}" syntax is a FAST convention for conditionally rendering a boolean HTML attribute. The renderer evaluates expr against the element's state:

• truthy → the bare attribute name is emitted (e.g. disabled)
• falsy → the attribute is omitted entirely

<input type="checkbox" ?disabled="{{!isEnabled}}">
<input ?disabled="{{activeGroup == currentGroup}}" type="button">


<input type="checkbox" disabled data-fe="1">


<input type="button" data-fe="1">

The data-fe marker is still emitted so the FAST client runtime knows to reconnect the binding during hydration.

Dataset Attribute Bindings — `dataset.propertyName` Copy Section

FAST elements follow the MDN HTMLElement.dataset convention: camelCase property names (e.g. dateOfBirth) correspond to kebab-case data-* HTML attributes (e.g. data-date-of-birth).

Passing `data-*` attributes to custom elements

When a custom element receives data-* attributes, the renderer groups them under a nested "dataset" key in the child state so that {{dataset.X}} bindings in the shadow template resolve naturally:

<test-el data-date-of-birth="{{dob}}"></test-el>


<div data-date-of-birth="{{dataset.dateOfBirth}}"></div>

With parent state {"dob": "1990-01-01"}, the shadow template receives child state {"dataset": {"dateOfBirth": "1990-01-01"}} and renders:

<div data-date-of-birth="1990-01-01" data-fe="1"></div>

The data-* → dataset.* mapping uses the same camelCase conversion as the browser: data-date-of-birth → dataset.dateOfBirth.

Using `{{dataset.X}}` bindings

{{dataset.X}} is ordinary dot-notation: it reads state["dataset"]["X"]. The dataset key must be present in state, either from a data-* attribute on the enclosing custom element or from a state object you supply directly:

<span>{{dataset.name}}</span>


<f-when value="{{dataset.active}}">Active</f-when>

ARIA Attribute Bindings — `ariaPropertyName` Copy Section

ARIA attributes follow the Element ARIA reflection convention: camelCase property names (e.g. ariaDisabled) correspond to aria-* HTML attributes (e.g. aria-disabled).

Passing `aria-*` attributes to custom elements

When a custom element receives aria-* attributes, the renderer converts them to their camelCase property name and stores them as top-level state keys using a static lookup table:

<test-el aria-label="Close dialog" aria-disabled="true"></test-el>


<button aria-label="{{ariaLabel}}" aria-disabled="{{ariaDisabled}}">×</button>

The shadow template receives child state {"ariaLabel": "Close dialog", "ariaDisabled": "true"}.

A lookup table is used instead of algorithmic conversion because ARIA attribute names do not place dashes at word boundaries — for example, aria-valuenow (not aria-value-now) maps to ariaValueNow.

HTML Attribute-to-Property Mappings Copy Section

Some HTML attributes have DOM property names that differ from their attribute names (e.g. tabindex → tabIndex, readonly → readOnly). When a custom element receives these attributes, the renderer converts them to their camelCase property name:

<test-el tabindex="0" readonly="true"></test-el>


<input tabindex="{{tabIndex}}" readonly="{{readOnly}}">

The shadow template receives child state {"tabIndex": "0", "readOnly": "true"}.

Only attributes where the property name differs are in the lookup table. Attributes like disabled, title, and hidden whose attribute and property names are identical pass through as-is.

Conditional Rendering — `` Copy Section

<f-when value="{{isAdmin}}">Admin panel</f-when>
<f-when value="{{!isGuest}}">Member content</f-when>
<f-when value="{{status == 'active'}}">Active</f-when>
<f-when value="{{count > 0}}">Has items</f-when>
<f-when value="{{a || b}}">Either</f-when>
<f-when value="{{a && b}}">Both</f-when>

Supported operators: ==, !=, >=, >, <=, <, ||, &&, !

Operators can be chained — && binds tighter than ||, matching standard precedence:

<f-when value="{{isAdmin && !isGuest && status == 'active'}}">Admin</f-when>
<f-when value="{{a || b || c}}">Any of the above</f-when>
<f-when value="{{isPublished || isAdmin && canPreview}}">Visible</f-when>

Right-hand operands can be string literals ('foo'), boolean literals (true/false), number literals (42), or other state references.

When value is a bare reference (e.g. {{items}}), the value is coerced to a boolean using JavaScript semantics. Because the input state is JSON, users cannot provide undefined directly; however, missing state properties or unresolved paths behave like JavaScript undefined and are treated as falsy.

Array Iteration — `` Copy Section

<ul>
  <f-repeat value="{{item in items}}">
    <li>{{item.name}} — {{title}}</li>
  </f-repeat>
</ul>

Inside <f-repeat>, {{item}} resolves to the current loop variable and {{$index}} resolves to the 0-based iteration index. Other bindings fall back to the root state (e.g. {{title}} above).
If the list binding or dot path is missing, <f-repeat> treats it as an empty array and renders zero iterations. Present non-array values still return RenderError::NotAnArray.

<f-repeat value="{{row in rows}}">
  <tr data-index="{{$index}}">
    <td>{{row.name}}</td>
  </tr>
</f-repeat>

Nesting Copy Section

<f-when> and <f-repeat> can be nested arbitrarily:

<f-when value="{{show}}">
  <f-repeat value="{{row in rows}}">
    <f-repeat value="{{cell in row.cells}}">
      <span>{{cell}}</span>
    </f-repeat>
  </f-repeat>
</f-when>

Property Access, Array Indexing, and `.length` Copy Section

Dot-notation, numeric indices, and the special .length property on arrays are all supported:

{{user.address.city}}
{{list.0.name}}
{{items.length}}

{{items.length}} resolves to the number of elements in the array. It can be used in both content bindings and <f-when> expressions:

<f-when value="{{items.length > 0}}">
  <p>{{items.length}} items found</p>
</f-when>

Custom Elements Copy Chapter

When given a Locator, the renderer detects custom elements (any tag whose name contains a hyphen, excluding f-when/f-repeat) and renders their corresponding HTML template files.

Setting up a Locator Copy Section

use microsoft_fast_build::Locator;

// From glob patterns — scans the filesystem
let locator = Locator::from_patterns(&[
    "./components/**/*.html",
    "./templates/*.html",
])?;

// Or build manually (useful in tests)
let mut locator = Locator::from_templates(std::collections::HashMap::new());
locator.add_template("my-button", "<button>{{label}}</button>");

Glob patterns support * (any characters within one path segment), ** (any number of segments), and ? (any single character).

Note: Locator::from_patterns walks the filesystem recursively up to 50 directory levels deep and skips symlinks. Symlinked directories are never followed, guarding against cycles in the directory tree.

HTML File Format Copy Section

Template HTML files must wrap their content in an <f-template> element with a name attribute identifying the custom element, and an inner <template> element containing the template markup:

<f-template name="my-button">
    <template>
        <button>{{label}}</button>
    </template>
</f-template>

A single file may contain multiple templates:

<f-template name="my-header">
    <template>
        <header><h1>{{title}}</h1></header>
    </template>
</f-template>
<f-template name="my-footer">
    <template>
        <footer>{{copyright}}</footer>
    </template>
</f-template>

If an <f-template> element is missing a name attribute, a warning is emitted to stderr and the template is ignored. 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 copied to the rendered Declarative Shadow DOM <template>. The renderer 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.

Composing CSS into an `` — `compose_f_template_styles` Copy Section

compose_f_template_styles inserts a <style> element as the first child of an <f-template> definition's inner <template>, entirely in memory:

use microsoft_fast_build::compose_f_template_styles;

let template_html = r#"
    <f-template name="my-button">
        <template>
            <button>{{label}}</button>
        </template>
    </f-template>
"#;

let composed = compose_f_template_styles(
    template_html,
    ":host { display: inline-block; }",
)?;
// composed now has <style>:host { display: inline-block; }</style> as the
// first child of the inner <template>, with every other byte preserved.

This has no filesystem requirement — template_html and css can come from any source (a build pipeline, a bundler plugin, generated CSS). The result is ordinary <f-template> source: write it to a file for Locator::from_patterns to discover, or pass it to locator::parse_f_templates directly.

Validation:

• template_html must contain exactly one <f-template> element, and that element must contain exactly one inner <template> element, or the call returns an error (MissingFTemplate, MultipleFTemplates, MissingInnerTemplate, MultipleInnerTemplates).
• css must not contain a case-insensitive </style raw-text terminator sequence (e.g. </style>, </STYLE >, </style/) — this would prematurely close the inserted <style> element. Content like content: "</stylesheet>" is not affected, since style must be followed by whitespace, /, >, or end of string to count as a terminator.

The WASM build exposes the same function as compose_f_template_styles(templateHtml, css), throwing a JS error on any validation failure.

Rendering with a Locator Copy Section

use microsoft_fast_build::{render_with_locator, render_template_with_locator, Locator};

let locator = Locator::from_patterns(&["./components/**/*.html"])?;

let html = render_template_with_locator(
    r#"<my-button label="Submit"></my-button>"#,
    r#"{"disabled": false}"#,
    &locator,
)?;

Rendering entry HTML (root custom elements) Copy Section

When rendering the top-level entry HTML of a page, use render_entry_with_locator or render_entry_template_with_locator. Custom elements found at this level are treated as root elements — their opening-tag {{binding}} attributes are resolved (primitives kept, non-primitives stripped) rather than forwarded verbatim.

All custom elements (root and nested) receive the full root state merged with their HTML attribute-derived state. Attribute-derived values take precedence over root state for overlapping keys. This gives every element access to the complete state tree without requiring explicit attribute bindings.

use microsoft_fast_build::{render_entry_with_locator, render_entry_template_with_locator, Locator};

let locator = Locator::from_patterns(&["./components/**/*.html"])?;

// Root custom elements (my-header, my-app) receive the full root state merged with
// any per-element attributes. Their templates can reference any key in the state JSON directly.
let html = render_entry_template_with_locator(
    r#"{{heading}}<my-header></my-header><my-app planet="earth"></my-app>"#,
    r#"{"heading": "Hello", "user": "Alice", "items": [{"name": "Item 1"}]}"#,
    &locator,
)?;
// my-header's template can use {{user}}, {{heading}}, etc. directly.
// my-app's template can use {{items}}, {{planet}}, etc. directly.

State Propagation Copy Section

All custom elements — whether at the entry level or deeply nested — receive the current root state as a base for their child state. Per-element HTML attributes are overlaid on top, with attribute-derived values taking precedence over any matching root state keys.

This means unbound state keys automatically propagate through the entire element tree. A child element can reference any state key from its ancestors without requiring explicit attribute bindings on every intermediate element:

<f-template name="my-el">
    <template>
        {{text}}
        <my-child-el></my-child-el>
    </template>
</f-template>


<f-template name="my-child-el">
    <template>
        {{text}}
    </template>
</f-template>

Both my-el and my-child-el render "Hello world" — the state propagates through the element tree without any explicit bindings.

Attribute handling on root elements

Root custom elements (rendered via render_entry_*) have their opening-tag {{binding}} attributes resolved in the rendered HTML output:

• Primitive bindings (string, number, boolean) — resolved and rendered with the resolved value. e.g. text="{{message}}" → text="Hello world".
• Non-primitive bindings (array, object, null) — stripped from the HTML output (the state is still available in the element's template via state propagation).
• Static attributes (no binding syntax) — passed through unchanged.

<my-parent label="{{title}}" list="{{items}}" planet="earth"></my-parent>


<my-child label="{{heading}}" :items="{{items}}"></my-child>

Attribute → State Mapping Copy Section

Attributes on a custom element become the state passed to its template:

HTML attribute keys are lowercased — HTML attribute names are case-insensitive and browsers always store them lowercase. isEnabled becomes isenabled; hyphens are preserved so selected-user-id stays selected-user-id. Templates must reference the lowercase form. When the attribute-name-strategy configuration is set to "camelCase", dashed attribute names that are not handled by specialized lookup tables (data-*, aria-*, HTML global attributes) are converted to camelCase instead: selected-user-id becomes selectedUserId, matching {{selectedUserId}} in the template. See the Configuration section for details.

Attribute value coercion — attribute values are resolved in this order:

• No value (boolean attribute) → true
• "{{binding}}" → resolved from parent state (any type: string, number, boolean, array, or object)
• Value starting with [ or { → parsed as a JSON array or object literal (e.g. items='["a","b","c"]')
• Anything else → String (e.g. count="42" yields {"count": "42"}; use count="{{count}}" to get a number)

Use :prop="{{binding}}" to pass arrays and objects from state without polluting HTML attributes — the : prefix causes the attribute to be stripped from the rendered HTML while still forwarding the resolved value (which can be an array or object) into the child element's rendering state. Alternatively, JSON array or object literals can be inlined directly as attribute values (e.g. items='["a","b","c"]'), which is useful when the data is static and does not come from parent state.

data-* attributes are always grouped under a nested "dataset" key. data_attr_to_dataset_key returns the full dot-notation path (e.g. "dataset.dateOfBirth"), which is split on . when building the nested state, making {{dataset.X}} bindings work naturally in shadow templates.

aria-* attributes are converted to their camelCase ARIA property name (e.g. aria-disabled → ariaDisabled, aria-valuenow → ariaValueNow) using a static lookup table, following the Element ARIA reflection convention. Unrecognised aria-* attributes fall through to the default lowercased-key path.

HTML attributes with mismatched property names (e.g. tabindex → tabIndex, readonly → readOnly, contenteditable → contentEditable) are converted to their camelCase DOM property name using a static lookup table. Only attributes where the property name differs are included — attributes like disabled, title, and hidden pass through as-is.

@event bindings and f-ref/f-slotted/f-children directives are skipped entirely — not added to child state and removed from rendered HTML. They are resolved purely by the FAST client runtime. The data-fe binding count still includes them so the FAST runtime allocates the correct number of binding slots.

Output Format Copy Section

The renderer wraps the rendered template in Declarative Shadow DOM and adds the hydration attributes required by the FAST client runtime:

<my-button label="Submit">light DOM</my-button>


<my-button label="Submit">
  <template shadowrootmode="open" shadowroot="open">
    <button>Submit</button>
  </template>
  light DOM
</my-button>

• shadowrootmode="open" — the standard declarative shadow DOM mode emitted by default.
• shadowroot="open" — legacy declarative shadow DOM attribute for broader browser compatibility.
• shadowroot* attributes declared on the source <f-template> are forwarded to the output <template>; shadowrootmode and shadowroot default to open when neither has a non-empty value, mirror when exactly one has a non-empty value, and are preserved as authored when both have explicit non-empty values.

Custom elements that have no matching template in the locator are passed through verbatim.

Configuration Copy Chapter

The RenderConfig struct provides configuration options that control rendering behaviour. Pass Some(&config) to any render function, or None for defaults.

`attribute-name-strategy` Copy Section

Controls how HTML attribute names are mapped to state property names when building child state for custom elements.

The camelCase strategy only applies to "plain" attributes. It does not affect:

• data-* attributes (always use dataset.* grouping)
• aria-* attributes (always use ARIA reflection lookup)
• HTML global attributes with known property names (e.g. tabindex → tabIndex)
• :prop property bindings (always lowercased)

Rust API

use microsoft_fast_build::{RenderConfig, AttributeNameStrategy, render_template_with_locator};

let config = RenderConfig::new()
    .with_attribute_name_strategy(AttributeNameStrategy::CamelCase)
    .with_markers_v2(true);

let result = render_template_with_locator(
    r#"<my-el foo-bar="hello"></my-el>"#,
    r#"{}"#,
    &locator,
    Some(&config),
)?;
// In my-el's template, use {{fooBar}} instead of {{foo-bar}}

WASM / JavaScript API

const html = render_entry_with_templates(
    entry,
    templatesJson,
    stateJson,
    "camelCase", // or "none"
    false,       // optional stream flag
    true         // optional markers_v2 flag
);

const chunksJson = render_entry_with_templates(
    entry,
    templatesJson,
    stateJson,
    "camelCase",
    true,
    true
);

Use render_with_templates for the original non-entry template-rendering semantics; use render_entry_with_templates for top-level entry HTML rendering. Passing true as the optional fifth argument switches render_entry_with_templates to stream mode and returns a JSON array string of HTML chunks; omitted or false returns normal HTML. Passing true as the optional sixth markers_v2 argument emits FAST Element 2.x indexed hydration markers.

Passing "none" or "" as the strategy uses the default behaviour.

Hydration Markers Copy Chapter

When a custom element's shadow template is rendered, the renderer emits hydration markers so the FAST client runtime can efficiently locate and patch DOM nodes without a full diff.

FAST Element 3.x data-free markers are emitted by default. Set
RenderConfig::with_markers_v2(true) in Rust, or pass the markers_v2 WASM/CLI
option, to emit FAST Element 2.x indexed markers for a client configured with
enableHydration({ markers: markers_v2 }).

Content binding markers Copy Section

Each {{expr}} or {{{expr}}} text binding is wrapped in data-free HTML comment markers:

Hello world

Markers carry no binding index or expression name. They are matched by string equality and paired using balanced depth counting.

Attribute binding markers Copy Section

Elements with {{expr}} attribute values, ?attr="{{expr}}" boolean bindings, or {expr} single-brace event/directive bindings receive a data-fe="N" marker attribute where N is the binding count. Client-only attributes (@event, :property, f-ref, f-slotted, f-children) are stripped from the HTML output but still counted in the marker:

<input type="checkbox" disabled data-fe="1">


<input disabled data-fe="1">


<input data-fe="1">


<button data-fe="1">Label</button>


<slot data-fe="1"></slot>


<video class="my-video" data-fe="2">

data-fe="N" — N is the total number of attribute bindings on the element.

Scope boundaries Copy Section

Each custom element shadow, <f-when> body, and <f-repeat> item template gets its own scope with the binding index reset to 0. Scopes don't carry numeric IDs — markers are data-free and paired by balanced depth counting.

Directive markers Copy Section

[inner content, or empty if condition is false]





  [item 0 — binding index reset to 0 per item]


  [item 1 — binding index reset to 0 per item]

Error Handling Copy Chapter

Render functions return Result<_, RenderError> (HTML or stream chunks).
RenderError exposes code(), location() -> Option<ErrorLocation>, and
template_name(). ErrorLocation has one-based line and UTF-16 column, plus
a UTF-16 length. Match error.kind() to inspect variants through source-location
wrappers. WASM failures are JavaScript Error instances with these details as
properties, not plain strings. See the source-coordinate contract and migration
notes.

Located preserves its underlying variant's code/message. WASM template-map JSON
and attribute-record validation also use invalid-template-metadata; an invalid
WASM attribute-name strategy uses invalid-attribute-name-strategy. These failures
do not acquire HTML coordinates.

Messages retain the existing explanation and include a snippet when available:

type error: '{{items}}' must resolve to a JSON array for use in <f-repeat> — template: "…<f-repeat value=\"{{item in items}}\">…"
unclosed binding '{{name': no closing '}}' found to end the expression — template: "Hello {{name"
duplicate template: element '<my-button>' is defined in multiple files: ./a/my-button.html, ./b/my-button.html

Numeric Precision Copy Chapter

The hand-rolled JSON parser stores all numbers as f64. This means integers larger than 2^53 (9,007,199,254,740,992) lose precision, as is the case with standard JavaScript number values. For typical use cases (IDs, counts, display values) this is not a concern. If your state contains very large integers, represent them as strings and bind with {{expr}} accordingly.

Renderer performance Copy Chapter

Tag and binding discovery uses a forward event scan rather than repeated
remaining-suffix searches for each directive kind. Adjacent custom elements
and plain tags no longer incur those quadratic searches. Rendered HTML,
attribute handling, default markers, and markers_v2 remain compatible.
Templates still render recursively; this is not a compiled-template or lazy
streaming API. Stream functions continue to return fully materialized chunks.

From a FAST repository checkout, run the native benchmarks and parity tests:

cargo bench --manifest-path crates/microsoft-fast-build/Cargo.toml --bench render
cargo test --manifest-path crates/microsoft-fast-build/Cargo.toml

Criterion separates parsed-state rendering, state parsing plus rendering, and
locator construction. Shared fixtures cover 1k/5k/20k instances and
50/200/1,000 definitions with payload sizes 1/20 in both marker modes.
See performance baselines for the packaged
WASM runner, golden hashes, scaling checks, RSS measurement, and limitations.

The guide also records post-scanner repeat/state-overlay and many-definition
profiles, with bounded workload commands and symbolized native CPU sampling
through Criterion's --profile-time mode. Those measurements identify child-state
copying as the next repeat/overlay target; they do not claim that memory or
allocation targets have been met.

For native allocation baselines, use the opt-in development example or the
fresh-process matrix runner from the repository root:

node crates/microsoft-fast-build/benches/profile-allocations.mjs --output=/tmp/fast-allocations.json
cargo run --manifest-path crates/microsoft-fast-build/Cargo.toml --release --features allocation-profiling --example profile-allocations -- --case=repeat_custom_elements --count=250 --mode=v3 --phase=render

The feature does not instrument the library or shipped WASM. Reports count
only allocations on the measuring thread within the selected phase, excluding
prepared inputs and report generation. See the baseline guide for controls,
output retention, reallocation semantics, and test commands.

Overview (`crates/microsoft-fast-convert/README.md`) Copy Section

microsoft-fast-convert

microsoft-fast-convert converts one FAST declarative HTML template string into another supported syntax. It is written in Rust and exposes both a Rust API and a wasm-bindgen API for Node tooling.

Supported targets Copy Chapter

• webui-prerelease — unwraps the outer <f-template> and emits HTML for WebUI's FAST parser plugin, converting only <f-repeat> to <for> and <f-when> to ``. Other supported FAST attributes (@click, :prop, ?bool, f-ref, f-children, f-slotted) pass through unchanged.
• webui-framework-prerelease — converts FAST's declarative syntax into the Microsoft WebUI Framework's own declarative runtime syntax (transferring Shadow/Light DOM policy from the outer <f-template> onto the inner <template>). It converts <f-repeat> to <for>, <f-when> to ``, f-ref to a braced w-ref, and FAST's $e event argument to bare e. f-slotted/f-children are stripped from the output with a warning, since WebUI Framework has no equivalent; every other unsupported construct (unknown f-*, $c event context, non-braced f-ref, conflicting shadow-root modes) remains a hard error. The target's name reflects the WebUI Framework project's own current prerelease status, not the stability of this target's implementation.
• fast-v3-ts — emits TypeScript source that imports FAST helpers and exports template as an html tagged template.

Rust usage Copy Chapter

use microsoft_fast_convert::{convert_template, convert_stylesheet};

let source = r#"<f-template name="my-element"><template>{{title}}</template></f-template>"#;
let result = convert_template(source, "fast-v3-ts")?;
let ts = result.output;

let css = ":host { display: block; }";
let styles = convert_stylesheet(css, "fast-v3-ts", "styles")?;

convert_template/convert_template_with_options return
Result<ConvertOutput, ConvertError>, where ConvertOutput { output: String, warnings: Vec<ConvertWarning> }. warnings reports non-fatal issues — such as a
stripped f-slotted/f-children directive, produced only by
webui-framework-prerelease — that didn't stop conversion;
webui-prerelease and fast-v3-ts output always have an empty warnings
vector, since neither strips anything. convert_stylesheet is unaffected and
still returns Result<String, ConvertError>.

convert_stylesheet(stylesheet, syntax, export_name) converts a CSS source string
into a TypeScript module that imports css from @microsoft/fast-element and
exports export_name as a css tagged template. It has no filesystem
requirement and, like convert_template, is only supported for the
fast-v3-ts syntax. export_name must be a valid TypeScript/JavaScript
identifier (no dotted paths).

fast-v3-ts output can optionally include an explicit TSource generic parameter
(html<TypeSource> instead of bare html) via convert_template_with_options and
ConvertOptions:

use microsoft_fast_convert::{convert_template_with_options, ConvertOptions};

let options = ConvertOptions {
    type_source: Some("MyElement".to_string()),
    type_source_import: Some("./my-element.js".to_string()),
    ..ConvertOptions::default()
};
let ts = convert_template_with_options(source, "fast-v3-ts", &options)?.output;

type_source must be a dotted TypeScript identifier (e.g. MyElement or
Namespace.MyElement); type_source_import, when provided, also emits a matching
import type { <root_identifier> } from "<type_source_import>"; statement. type_source
is only supported for fast-v3-ts; type_source_import requires type_source.

Syntax metadata is available through syntax_metadata(). The metadata includes each
supported syntax name, required output extension, and default output suffix so package
tooling can avoid duplicating target definitions.

Explicit public export types Copy Section

Set ConvertOptions { typed: true, ..ConvertOptions::default() } for
fast-v3-ts template conversion. It emits an ElementViewTemplate<TSource>
annotation (or ElementViewTemplate when no source type is supplied) and a
type-only FAST import. The default remains byte-compatible unannotated output.
Other syntax targets reject typed: true.

convert_stylesheet_with_options(css, syntax, export_name, &options) similarly
emits export const styles: ElementStyles = css... with a type-only import.
Stylesheet options reject type_source/type_source_import. Existing
convert_stylesheet calls keep their original output. Type imports use the
root of dotted source names; FAST type names are aliased when necessary to
avoid collisions with supplied names.

Typed exports support isolatedDeclarations; the converter does not infer a
state interface. Supply a concrete source type for strict property validation.
Native struct literals should use ..ConvertOptions::default() for unset options.

WASM usage Copy Chapter

When built with wasm-pack --target nodejs, the crate exports:

interface ConvertResult {
    readonly output: string;
    readonly warnings: string[];
}

convert_template(template: string, syntax: string): ConvertResult
convert_template_with_options(
    template: string,
    syntax: string,
    typeSource?: string,
    typeSourceImport?: string,
    typed?: boolean,
): ConvertResult
convert_stylesheet(stylesheet: string, syntax: string, export_name: string, typed?: boolean): string
convert_syntax_metadata(): string

convert_syntax_metadata() returns JSON metadata for supported syntax targets.
Errors are JavaScript Error instances, retaining the ConvertError message and
adding code plus optional line, column, length, and templateName.
Generated declarations export the FastBuildError extends Error interface.
Coordinates refer to the complete original input, not the extracted inner
template or rewritten output. They use one-based UTF-16 columns/lines and a UTF-16
error-token highlight length; CRLF is one break and lone CR/LF also break lines.
Options/syntax failures have no HTML coordinates.

Native ConvertError provides code(), location() -> Option<ErrorLocation>,
template_name(), and kind(); use kind() when matching source-wrapped
validation errors. Context fields are now boxed ErrorContext values. See the
migration guide.

Error codes Copy Chapter

Validation Copy Chapter

The converter validates that the input contains exactly one <f-template name="…"> with a non-empty name and exactly one inner <template>. It validates supported syntax values, <f-repeat> and <f-when> value="{{…}}" expressions, supported f-* attributes, and the limited expression grammar used for fast-v3-ts output. It also validates that type_source is a dotted identifier, that type_source is only supplied for fast-v3-ts, and that type_source_import is only supplied alongside type_source.

The webui-framework-prerelease target additionally validates that outer <f-template> attributes (other than name) are shadowroot-prefixed (ConvertError::UnsupportedPublisherAttribute otherwise), that a shadowroot-prefixed outer attribute doesn't conflict with a differently-valued attribute already on the inner <template> (ConvertError::ConflictingShadowRootMode), that f-ref values are single-braced (ConvertError::InvalidAttributeValue), and that event arguments don't use FAST's repeat-context tokens such as $c (ConvertError::UnsupportedEventContext). f-slotted and f-children are the one exception to this target's otherwise strict validation: rather than erroring, they are stripped from the output and reported via ConvertOutput::warnings as a ConvertWarning::StrippedUnsupportedDirective.

convert_stylesheet validates that syntax is fast-v3-ts (CSS conversion is not supported for webui-prerelease/webui-framework-prerelease) and that export_name is a valid TypeScript/JavaScript identifier. Stylesheet content is escaped for safe embedding in a TypeScript template literal: backslashes, backticks, literal ${ sequences, and carriage returns are all escaped.

Overview (`examples/design-system/README.md`) Copy Section

@microsoft/fast-examples-design-system

A CSS-only design system for FAST example apps. The package ships three
hand-authored stylesheets that define a shared set of CSS custom properties
for color, typography, spacing, shape, elevation, and motion. There is no
JavaScript or TypeScript implementation — example apps wire themes
themselves by toggling the data-theme attribute on <html>.

This README and DESIGN.md are the canonical guidance for both
humans and coding agents working in the examples/* workspace.

Token names are semantic and use-site-oriented, with the --fast- prefix
and coverage tuned for FAST example apps.

What ships Copy Chapter

The package ships exactly one stylesheet:

The package is "private": true and consumed via the workspace dependency
"@microsoft/fast-examples-design-system": "workspace:*".

tokens.css uses the CSS light-dark() function, which requires
Chrome / Edge 123+, Firefox 120+, or Safari 17.5+ (all shipped in
2023–2024). These example apps target evergreen browsers; there is no
fallback for older versions.

Install Copy Chapter

Add the workspace dependency in the consuming example app's package.json,
then run npm install from the repository root.

{
    "dependencies": {
        "@microsoft/fast-examples-design-system": "workspace:*"
    }
}

Use Copy Chapter

Import the stylesheet exactly once at the app entry point — typically the same
file that defines or bootstraps the root custom element. The bundler (Vite in
the existing examples) inlines the CSS into the document.

// src/main.ts
import "@microsoft/fast-examples-design-system/tokens.css";

<!doctype html>
<html lang="en">
    
    <body>
        <my-app></my-app>
    </body>
</html>

If the app is intentionally single-theme, hard-code the attribute and never
touch it from JavaScript:

<html lang="en" data-theme="light">

Referencing tokens from component CSS Copy Section

Reference tokens through var(--fast-...) in FAST css template literals or
in any other CSS context. Never hard-code colors, font sizes, spacing, radii,
border widths, shadows, durations, or curves.

import { css } from "@microsoft/fast-element";

export const styles = css`
    :host {
        display: block;
        padding: var(--fast-padding-content-medium);
        background: var(--fast-background-layer-primary-solid);
        color: var(--fast-foreground-ctrl-neutral-primary-rest);
        border: var(--fast-stroke-width-default) solid
            var(--fast-stroke-divider-subtle);
        border-radius: var(--fast-corner-large);
        box-shadow: var(--fast-shadow-card-rest);
        font-family: var(--fast-text-style-default-regular-font-family);
        font-size: var(--fast-text-global-body3-font-size);
        line-height: var(--fast-text-global-body3-line-height);
        transition: background var(--fast-duration-fast)
            var(--fast-curve-easy-ease);
    }
`;

Theme switching Copy Chapter

The active theme is selected by the data-theme attribute on <html>:

Under the hood, tokens.css declares color-scheme: light dark on :root
and uses the CSS light-dark() function in every color/elevation token.
The browser picks the matching value based on the inherited
color-scheme. Setting data-theme="light" or data-theme="dark"
overrides color-scheme to that single value, which flips every
light-dark() resolution. No media query is needed.

To wire a toggle, write the attribute directly from your application code. The
design system itself contains no JavaScript — toggles, persistence, and event
plumbing are intentionally left to the consuming app so the system stays
framework-neutral and dependency-free.

// Force light
document.documentElement.setAttribute("data-theme", "light");

// Force dark
document.documentElement.setAttribute("data-theme", "dark");

// Restore system preference
document.documentElement.removeAttribute("data-theme");

See ../todo-app/ for a working consumer of the design
system. The example deliberately uses a single (light) theme set
statically in markup; it does not implement a runtime toggle.

Token catalog Copy Chapter

The complete list of tokens lives in tokens.css. Categories
at a glance:

State vocabulary on interactive tokens: rest, hover, pressed,
disabled. Optionally prefixed with selected- for selectable controls.

See DESIGN.md for the full naming grammar, the rationale, and
the rules for adding new tokens.

Overview (`examples/test/README.md`) Copy Section

FAST Examples — End-to-End Tests

Playwright end-to-end tests that exercise the three Todo example apps in this monorepo as black-box web applications. The same test suite runs against each app, asserting that the unified UI and functionality behave identically regardless of implementation.

Each project is configured in playwright.config.ts with its own webServer block — Playwright starts and stops them automatically.

Running Copy Chapter

From the monorepo root:

# install deps and browsers (once)
npm ci
npx playwright install --with-deps chromium

# build the example apps the tests depend on
npm run build -w @microsoft/fast-element
npm run build -w @microsoft/fast-todo-app-example
npm run build -w @microsoft/fast-todo-mobx-app-example
npm run build -w @microsoft/fast-webui-todo-app-example

# run all three suites
npm run test:e2e

To run a single app's suite:

npm run test:e2e -w @microsoft/fast-examples-e2e -- --project=csr-todo
npm run test:e2e -w @microsoft/fast-examples-e2e -- --project=csr-todo-mobx
npm run test:e2e -w @microsoft/fast-examples-e2e -- --project=ssr-webui-todo

Layout Copy Chapter

examples/test/
├── package.json
├── playwright.config.ts
├── DESIGN.md                    // design notes for contributors
├── support/
│   ├── fixtures.ts              // injects the per-project adapter
│   ├── global-setup.ts
│   ├── global-teardown.ts
│   └── adapters/
│       ├── index.ts             // resolves the adapter for a project
│       ├── types.ts             // TodoAppAdapter interface
│       ├── csr.ts               // shared adapter for both CSR apps
│       └── ssr-webui-todo.ts
└── tests/
    └── todo.pw.spec.ts          // shared suite, runs against every project

Adapters wrap the per-app DOM differences (e.g. SSR app uses a nested <todo-item> shadow root per row, while CSR apps render inline <li> content) behind a uniform interface (addTodo, descriptions, toggleByDescription, deleteByDescription, setFilter, getCounts, …). Test specs use that interface only — no app-specific selectors leak into the suite.

Spec files use the *.pw.spec.ts suffix so Playwright picks them up while leaving the *.spec.ts suffix free for future Node-based tests.

CI Copy Chapter

The test:e2e script is run as a separate step in .github/workflows/ci-validate-pr.yml after unit tests, gated on the same npx playwright install --with-deps invocation that already runs there.

Overview (`packages/fast-build/README.md`) Copy Section

FAST Build

The fast-build package renders the declarative HTML template syntax of @microsoft/fast-element, primarily for use in testing environments. It is powered by a WebAssembly core with zero runtime npm dependencies.

Note: For production server-side rendering, we recommend using the @microsoft/webui project instead.

Installation Copy Chapter

From NPM Copy Section

To install the latest @microsoft/fast-build package using npm:

npm install --save @microsoft/fast-build

Within your JavaScript or TypeScript code, you can then import library APIs like this:

import { render } from '@microsoft/fast-build';

CLI usage Copy Chapter

Once installed, the fast binary is available. Use the build subcommand to render an HTML template with an optional JSON state file, or convert to convert a FAST declarative HTML template to another supported syntax:

fast build [options]
fast convert [options]

Build options Copy Section

Example Copy Section

Given an index.html:

<html>
  <body>
    <h1>{{title}}</h1>
    <p>{{description}}</p>
  </body>
</html>

And a state.json:

{
  "title": "Hello FAST",
  "description": "Server-side rendered with WebAssembly."
}

Run:

fast build --entry=index.html --state=state.json --output=output.html

Produces output.html:

<html>
  <body>
    <h1>Hello FAST</h1>
    <p>Server-side rendered with WebAssembly.</p>
  </body>
</html>

Streaming output Copy Section

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.

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.

Performance benchmarks for contributors Copy Section

The renderer discovers tags and bindings in a forward scan, eliminating repeated
remaining-suffix searches for adjacent custom elements and plain tags. Existing
WASM exports, rendered bytes, default markers, and markers_v2 remain compatible.
Rendering is still synchronous, and --stream still buffers all chunks in WASM.

From a FAST repository checkout, not an installed npm package:

npm run build -w @microsoft/fast-build
npm run bench:render -w @microsoft/fast-build -- --case=url_sink_siblings --output=/tmp/fast-render.json
npm run bench:render -w @microsoft/fast-build -- --case=url_sink_siblings --check-scaling

The runner benchmarks the actual packaged WASM in fresh child processes in both
marker modes, recording timing, CPU, output hashes, throughput, and peak RSS.
Use --case, --counts, --samples, or --compare= to narrow
or compare a run. Output files are never overwritten. Normal tests verify the
same fixtures against pre-optimization hashes without flaky timing thresholds.
See the benchmark guide
for native Criterion benchmarks, fixture sizes, methodology, and limitations.

The guide includes post-scanner repeat/state-heavy and many-definition profiles.
Start expensive repeat cases with --counts=250,1000 --warmup-count=250;
state-overlay controls and separate native phases help identify the next
optimization without running an unbounded matrix. Native CPU samples are not
WASM allocation measurements, and no production rendering behavior is changed.

The guide also includes an opt-in native allocation baseline and a fresh-process
matrix command: node crates/microsoft-fast-build/benches/profile-allocations.mjs --output=/tmp/fast-allocations.json from the repository root. Its counters are
development-only Rust tooling, not part of the npm CLI or WASM; native peak
newly-live heap is not process RSS.

Missing or omitted state Copy Section

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.

Breaking change: Earlier versions implicitly loaded state.json from the current working directory when --state was omitted. To use a state file, pass --state=state.json or set "state": "state.json" in fast-build.config.json.

When a binding value is not present in state:

• Content bindings render nothing, including unresolved dot paths: {{foo.bar}} becomes ``.
• Attribute bindings omit the entire attribute, including unresolved dot paths: becomes.
• <f-repeat> treats a missing list binding, including unresolved dot paths, as an empty array and renders zero iterations. If the binding is present but is not an array, rendering still errors.

Explicit null also omits an attribute, even in an interpolated attribute
value. Empty strings remain present. Known HTML boolean attributes bound to
JSON booleans use presence/absence; ordinary attributes (including ARIA)
retain textual booleans. Use ?name for browser-side truthy/falsy bindings.
Author bindings resolving to absence still override template-host defaults.
These intentional output changes are described in the
plugin migration guide.

APIs for build-time plugins Copy Section

Import the actual exported WASM subpath; do not slice rendered host HTML:

import {
    parse_f_templates,
    render_shadow_root,
} from "@microsoft/fast-build/wasm/microsoft_fast_build.js";

const definitions = JSON.parse(parse_f_templates(templateHtml));
const templates = Object.fromEntries(
    definitions.filter(definition => definition.name !== null)
        .map(definition => [definition.name, definition]),
);
const shadowRootHtml = render_shadow_root(
    "my-card", JSON.stringify(templates), JSON.stringify(componentState),
);

The result is the complete DSD <template> fragment, with hydration markers
and nested components, but no host, host defaults, or light DOM. Pass resolved
component state; the API does not derive it from caller-owned host attributes.
It accepts the existing attribute-name strategy and v2 marker options.

Parsed records add formatVersion: 1 and bindings without changing the array
shape. Binding records expose name (null for compound expressions),
expression, syntax kind, lexical paths, and outer-to-inner repeat
scope frames. type is null except for repeat collections ("array");
optional is null because required state declarations are not inferable.
$index paths refer to the active repeat frame, not a root state key.
Client expressions are described lexically, not fully JavaScript-type-checked.
Code samples are excluded; metadata is not full syntax or state validation.
Generated WASM declarations expose these JSON interfaces.

Authored binding source spans

Each binding occurrence includes span: { start, end }. Both positions contain
offset, line, and column, relative to the complete HTML string passed to
parse_f_templates, not the extracted or trimmed template body. Duplicate
expressions have separate spans, including occurrences in host attributes,
interpolated attribute values, and nested directives.

• offset is a zero-based UTF-16 code-unit offset, compatible with JavaScript
  string slicing. It is not a UTF-8 byte offset.
• line and column are one-based. Columns count UTF-16 code units, not visual
  width or Unicode code points; a tab counts as one and a non-BMP character
  counts as two.
• Ranges are half-open: start is inclusive and end is exclusive. They cover
  the trimmed expression, excluding braces and surrounding whitespace.
• CRLF counts as one line break but two offset units. Lone CR and LF each count
  as one line break. Input line endings are not normalized.
• Repeat bindings locate the iterable expression, not the alias or in keyword,
  matching their existing expression field. Nested scope frames are unchanged.

const [definition] = JSON.parse(parse_f_templates(templateHtml));
for (const binding of definition.bindings) {
    const { start, end } = binding.span;
    const authoredExpression = templateHtml.slice(start.offset, end.offset);
    console.log(`${start.line}:${start.column}`, authoredExpression);
}

Positions refer to the original, entity-encoded attribute text. No entity decoding
is introduced. Code samples remain excluded without shifting subsequent spans.
Callers associate the input with its file name and must regenerate metadata after
editing that input. Bindings and directives inside HTML comments remain unsupported.

Render exports reject unsupported/malformed explicit versions before rendering.
Legacy unversioned maps and string definitions remain supported. The CLI keeps
version/binding fields when assembling a map; persisted metadata should do the
same instead of discarding them.

Structured errors

Failing render, conversion, composition, and metadata-validation APIs throw actual
JavaScript Error objects, retaining the existing human-readable message.
Both WASM modules export this TypeScript interface (not a runtime constructor):

interface FastBuildError extends Error {
    code: string;
    line?: number;
    column?: number;
    length?: number;
    templateName?: string;
}

Use code, such as unclosed-binding, repeat-not-array, or missing-template,
instead of parsing messages. The complete code lists are documented with the
renderer errors
and converter errors.

Locations use one-based lines and UTF-16 columns, with a UTF-16 highlight length.
Tabs count as one unit, non-BMP characters as two; CRLF is one line break and lone
CR/LF are also line breaks. A highlight covers the offending opening tag or
binding including its delimiters; an unclosed binding highlights its opening
delimiters. Unlike successful binding metadata, these are error-token ranges,
not trimmed expression ranges.

Entry-render and conversion coordinates refer to the original HTML argument,
even after code-sample escaping, inner-template extraction, or publisher-attribute
rewriting. Light DOM remains in its caller's source. Errors in separately supplied
custom-element definitions include templateName and use coordinates within that
definition's supplied content, not the entry HTML or the full file it was
extracted from. Maintain a name-to-source mapping when presenting these locations.
For a missing inner template, the highlight identifies its containing
<f-template>; duplicate-wrapper errors identify the second wrapper.

Coordinates are absent when there is no meaningful HTML position: invalid state
JSON, malformed metadata/options, missing template definitions or outer wrappers,
filesystem errors, and unsafe separately supplied CSS. A known templateName
can still be present without coordinates. parse_f_templates remains permissive:
it does not gain strict syntax validation or new failures.

For a direct render(html, stateJson) call, an integration can report:

try {
    render(html, stateJson);
} catch (error) {
    if (!(error instanceof Error)) throw error;
    const location = error.line === undefined
        ? inputPath
        : `${inputPath}:${error.line}:${error.column}`;
    console.error(`${location} [${error.code}]: ${error.message}`);
}

See the migration guide
when updating consumers that previously caught strings.

Custom element templates Copy Section

Pass a glob pattern (or comma-separated list of patterns) to --templates to expand custom elements into Declarative Shadow DOM:

fast build \
  --templates="./components/**/*.html" \
  --entry=index.html \
  --state=state.json \
  --output=output.html

Each matched .html file is scanned for <f-template> elements. The name attribute of each <f-template> determines the custom element name. A single file may contain multiple templates.

Template files must use the following format:

<f-template name="my-button">
    <template>
        <button>{{label}}</button>
    </template>
</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. 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.

Attribute name strategy Copy Section

The --attribute-name-strategy option controls how HTML attribute names on custom elements are mapped to state property names in their shadow templates.

The camelCase strategy only affects "plain" custom element attributes. It does not change:

• data-* attributes (always use dataset.* grouping)
• aria-* attributes (always use ARIA reflection lookup)
• HTML global attributes with known property names (e.g. tabindex → tabIndex)

fast build \
  --templates="./components/**/*.html" \
  --attribute-name-strategy=camelCase \
  --entry=index.html \
  --state=state.json \
  --output=output.html

Configuration file Copy Section

Instead of passing every option on the command line, you can place a fast-build.config.json file alongside your project files:

{
    "entry": "index.html",
    "state": "state.json",
    "output": "output.html",
    "templates": "./components/**/*.html",
    "markers_v2": true
}

The CLI automatically loads fast-build.config.json from the current directory when it exists. To use a different file, pass --config:

fast build --config=configs/my-build.json

Precedence: CLI arguments always override config file values. For example, --output=other.html will override the output value in the config file.

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, markers_v2, and stream. Unknown keys produce an error. Values must be strings except markers_v2 and stream, which must be JSON booleans (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.

Convert Copy Chapter

fast convert converts FAST declarative template files using the converter WASM module in wasm/convert/. Supported syntax names, output extensions, and default output suffixes are read from the converter WASM metadata so the Rust converter remains the source of truth for syntax targets.

fast convert --syntax=webui-prerelease --templates=example.html
fast convert --syntax=fast-v3-ts --templates=example.html --output=../*.template.ts
fast convert --syntax=fast-v3-ts --templates="src/**/*.html" --output=generated/*.template.ts
fast convert --syntax=fast-v3-ts --templates=example.html \
    --type-source=MyElement --type-source-import=./my-element.js

Convert options Copy Section

Only matched .html files are converted; non-.html files and directories are never matched. The output extension must match the selected syntax: .html for webui-prerelease/webui-framework-prerelease and .ts for fast-v3-ts. The output parent directory is created automatically if it doesn't exist (mkdir -p semantics), and an existing output file is rejected unless --overwrite or "overwrite": true is used. When a --templates pattern matches zero files, a warning is printed but the command does not fail unless every pattern matches zero files.

webui-framework-prerelease converts FAST's declarative syntax into the Microsoft WebUI Framework's own declarative runtime syntax (webui-prerelease remains unchanged — it emits HTML for WebUI's separate FAST parser plugin instead). When webui-framework-prerelease strips an unsupported f-slotted/f-children directive, the CLI prints Warning: <message> to stderr for each stripped directive without failing the command.

--type-source exists so templates that combine more than one differently-named
ref/children/slotted directive (which otherwise fail to type-check once a
real TSource is supplied, because html<TSource, TParent> infers a single
TSource for the whole tagged template) can be generated already type-checked
against a concrete element type. See
microsoft-fast-convert DESIGN.md.

Convert configuration file Copy Section

fast-convert.config.json follows the same precedence and path-resolution rules as fast-build.config.json: CLI arguments override config values, and templates/output paths from config are resolved relative to the config file directory.

{
    "syntax": "fast-v3-ts",
    "templates": "src/**/*.html",
    "output": "generated/*.template.ts",
    "overwrite": false,
    "type-source": "MyElement",
    "type-source-import": "./my-element.js"
}

Only syntax, templates, output, overwrite, type-source,
type-source-import, and typed are allowed. Values must be strings except
overwrite and typed, which must be JSON booleans.

For declaration-emitting consumers, use --typed --type-source=MyElement.
The converter WASM's convert_template_with_options accepts an appended
optional typed boolean. convert_stylesheet(css, "fast-v3-ts", "styles", true) emits an ElementStyles annotation. Existing calls remain untyped;
typed exports are tested with TypeScript isolatedDeclarations.

Running converter fixtures locally Copy Section

Build the package WASM, then run the fixture validation:

npm run build -w @microsoft/fast-build
npm run test:fixtures:convert -w @microsoft/fast-build

The fixture tests run fast convert from fixture directories that contain
fast-convert.config.json, so they verify the same default config discovery used
by fast build. Generated fixture output is written under
packages/fast-build/test/.fixture-output/ and removed by the tests.
test/fixtures/convert/type-source.test.js additionally type-checks
--type-source output with the TypeScript compiler API against a companion
element type, using a separate test/.fixture-output-type-source/ directory.

Template syntax Copy Chapter

Bindings and FAST directive markup inside HTML comments are unsupported.
Commenting out bound markup does not reliably disable its bindings and can cause
rendering errors or client hydration mismatches. Remove unused bound markup
instead, and keep explanatory comments free of binding syntax and FAST directive
tags.

Template syntax follows the FAST declarative HTML format. See the
@microsoft/fast-element declarative documentation
for full documentation on bindings, conditionals, repeats, and directives.

Overview (`packages/fast-element/README.md`) Copy Section

FAST Element

The fast-element library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework.

Installation Copy Chapter

From NPM Copy Section

To install the latest fast-element library using npm:

npm install --save @microsoft/fast-element

Within your JavaScript or TypeScript code, you can then import library APIs like this:

import { FASTElement } from '@microsoft/fast-element';

From CDN Copy Section

A pre-bundled script that contains all APIs needed to build web components with FAST Element is available on CDN. You can use this script by adding type="module" to the script element and then importing from the CDN.

<!DOCTYPE html>
<html lang="en">
    <head>
        <script type="module">
          import { FASTElement } from "https://cdn.jsdelivr.net/npm/@microsoft/fast-element/dist/fast-element.min.js";

          // your code here
        </script>
    </head>
    
</html>

The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:

<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/[email protected]/dist/fast-element.min.js"></script>

:::note
For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
:::

:::tip
Looking for a quick guide on building components? Check out our Cheat Sheet.
:::

Browser Requirements Copy Chapter

FAST Element v3 assumes a client-side browser Window runtime with native
globalThis, Custom Elements, DOM, Shadow DOM, and requestAnimationFrame.
The FAST object is now a module-scoped export (not on globalThis). If you
need to support an older browser without globalThis, load that polyfill before
importing @microsoft/fast-element.

The FAST Element client runtime is not intended to execute in workers,
server-side JavaScript runtimes, or other non-window hosts. Use server-side
rendering tools to produce HTML for the browser, and run FAST Element in the
client window where custom elements connect, render, update, and hydrate.

Debug entrypoint Copy Chapter

The declarative attribute fixture covers server-side omission of null/missing
attributes and subsequent hydration updates. Explicit empty strings remain
present, and omitted attributes retain binding slots. See the
server-rendering guide
for the rendering contract.

@microsoft/fast-element/debug.js exports enableDebug() instead of configuring
FAST at import time. The development root export and debug rollup bundle still
enable debug behavior automatically.

import { enableDebug } from "@microsoft/fast-element/debug.js";

enableDebug();

Server-rendered hydration Copy Chapter

Call enableHydration() from @microsoft/fast-element/hydration.js before
components connect to reuse their server-rendered DOM. Ordered sibling-bounded
views use pointer traversal and consume native markers without factory-index
arrays; unusual boundaries and potentially mutating cleanup retain the live
Range fallback. Nested and adjacent repeats pair only their own server ranges,
preserving SSR nodes while reconciling missing or excess items.

Call enableHydration() before components are registered with the platform to
also enable pointer-only native marker cleanup for FAST components that do not
observe data-fe. Observation tracking is opt-in and excluded from client-only
FASTElement bundles. Earlier registrations still hydrate correctly through
the conservative fallback, as do unknown registration, observed markers,
customized built-ins, and overridden attribute methods. Cleanup remains
synchronous.

Existing FAST 3 marker output and opt-in markers_v2 remain supported without
application changes. See the server-rendering guide
and contributor performance workloads.
Contributor-facing internals separate DOM traversal, binding target mapping,
and repeat-range discovery; the opt-in benchmark spec is independent of the
deterministic correctness and allocation regression spec.

Export Sizes Copy Chapter

Bundle sizes for each tree-shakeable export are tracked in SIZES.md and regenerated on every build. See the Export Sizes documentation page for the latest numbers.

Root Imports and Path Exports Copy Chapter

The root @microsoft/fast-element entrypoint exports the FAST Element
implementation APIs, including the element base class, kernel, controller,
definition APIs, template APIs, binding helpers, directives, styles, and schema
helpers. The FAST element registry is also available from
@microsoft/fast-element/registry.js for focused definition lookups and
fastElementRegistry.whenRegistered(tagName) registration promises.
Declarative, hydration, context, and dependency injection APIs are available
from their focused path exports.

Focused package path exports remain available for consumers that want to import
a narrower entrypoint directly. The website's
Path Exports page is
generated from package.json and lists each supported path.

Dynamic Style Application Copy Chapter

Import css, CSSTemplateTag, CSSValue, and style APIs such as
ElementStyles, CSSDirective, cssDirective, ComposableStyles,
HostBehavior, HostController, StyleStrategy, and StyleTarget from
@microsoft/fast-element:

import { ElementStyles, css } from "@microsoft/fast-element";

When runtime state or external signals need to add or remove styles, create the
ElementStyles with css and toggle it through
this.$fastController.addStyles() / this.$fastController.removeStyles() from
the element lifecycle or change handlers.

css templates remain static style definitions. Runtime CSS bindings and
behavior-producing CSS directives are no longer supported; keep the condition on
the element and toggle a separate ElementStyles instance through the
controller when styles need to change.

Declarative HTML Copy Chapter

Bindings and FAST directive markup inside HTML comments are unsupported in
declarative templates. Commenting out bound markup does not reliably disable its
bindings; remove unused markup instead. See the
template syntax restrictions.

FAST Element publishes its declarative HTML runtime from
@microsoft/fast-element/declarative.js. This entrypoint exports the
functional APIs for declarative templates: declarativeTemplate(),
TemplateParser, and related configuration types. attributeMap() and
observerMap() are available from their own focused path exports. The
declarative runtime is pure at import time; declarative APIs lazily install only
declarative debug messages. Hydration is separate and remains opt-in through
enableHydration() from @microsoft/fast-element/hydration.js.

import { FASTElement } from "@microsoft/fast-element";
import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";

class MyElement extends FASTElement {}

MyElement.define({
    name: "my-element",
    template: declarativeTemplate(),
});

declarativeTemplate() automatically defines FAST's internal native
<f-template> publisher in the relevant registry, resolves the matching
<f-template name="my-element">, and keeps the definition template concrete
before define() resolves. If multiple matching <f-template> elements are
connected, the first connected element supplies the template and later duplicates
do not reassign it. Consumers should not import or define the <f-template>
implementation directly.

Declarative schema behavior is enabled with define extensions:

import { attributeMap } from "@microsoft/fast-element/attribute-map.js";
import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";
import { observerMap } from "@microsoft/fast-element/observer-map.js";

MyElement.define(
    {
        name: "my-element",
        template: declarativeTemplate(),
    },
    [attributeMap(), observerMap()],
);

attributeMap() creates @attr-style accessors for leaf bindings, and
observerMap() creates deep observable accessors for discovered root
properties. Declarative templates assign definition.schema during template
resolution so these extensions always have schema data when used with
declarativeTemplate(). For non-declarative/manual schema use, import Schema
from @microsoft/fast-element and pass it on the element definition;
observerMap() can also receive
observerMap({ schema }) directly. When both extensions are present, attribute
mapping runs before observer mapping.

Declarative utilities such as deepMerge are available from
@microsoft/fast-element/declarative-utilities.js. See
docs/declarative/syntax.md for declarative implementation
details and the
Declarative HTML docs
for guides on writing f-templates, defining declarative elements, and
server-side rendering. Declarative event bindings use $e for the DOM event
object and $c for the execution context.

Prerendered Content Optimization Copy Chapter

Hydration of prerendered content is opt-in. Call enableHydration() from @microsoft/fast-element/hydration.js before any FAST elements connect to activate the hydration path:

import { enableHydration } from "@microsoft/fast-element/hydration.js";

const hydration = enableHydration();

await hydration.whenHydrated();
console.log("hydration complete");

By default, hydration handles the initial prerendered batch and then no-ops
after the active hydration batch completes. If your app streams Declarative
Shadow DOM after the initial batch, keep the hydration hook active. In this
mode, enableHydration().whenHydrated() intentionally remains pending because
hydration never reaches a global completion point.

import { enableHydration, StopHydration } from "@microsoft/fast-element/hydration.js";

enableHydration({
    stopHydration: StopHydration.never,
});

FAST Element 3.x data-free hydration markers are the only format recognized
by default. Server output that still emits the legacy FAST Element 2.x
indexed markers will fail to hydrate unless you opt into that reader on its
dedicated export path — an interoperability enhancement for backend systems
that have not yet adopted the data-free format:

import { enableHydration, markers_v2 } from "@microsoft/fast-element/hydration.js";

enableHydration({ markers: markers_v2 });

Because markers_v2 is only referenced when explicitly imported, its legacy
parsing logic is tree-shaken out of the bundle for consumers who don't use it.

When using @microsoft/fast-build, set "markers_v2": true in
fast-build.config.json so the renderer and client use the same format.

When hydration is enabled and a FAST element connects with an existing shadow root (from server-side rendering or declarative shadow DOM), ElementController detects this and hydrates instead of re-rendering. Two properties on the controller let you inspect the result:

• isPrerendered: Promise — resolves true when the element had a declarative shadow root (DSD) at connect time, regardless of whether hydration ran.
• isHydrated: Promise — resolves true only when hydration actually ran successfully.

This enables several optimizations:

• Hydration instead of re-render: The template uses hydrate() to map existing DOM nodes to binding targets rather than cloning new DOM.
• Declarative template resolution: declarativeTemplate() waits for the
  matching <f-template> before define() completes, so connected elements
  hydrate with a concrete template.
• Attribute skip: onAttributeChangedCallback() skips processing during initial upgrade when the element is prerendered, since server-rendered attribute values are already correct.
• Binding skip: HTMLBindingDirective.bind() skips updateTarget for attribute and booleanAttribute aspect types when the view is prerendered.

Hydration Mismatch Diagnostics Copy Section

If a prerendered DOM diverges from the client template in a way FAST cannot
reconcile (the render() empty-boundary and repeat() count-mismatch cases
recover silently), HydrationBindingError or HydrationTargetElementError is
thrown. By default the message is a single line pointing at the opt-in
hydrationDebugger(). Install the debugger to get a rich
"Expected … / Received …" report with the SSR HTML snippet and structured
expected / received fields on the thrown error:

import { enableHydration, hydrationDebugger } from "@microsoft/fast-element/hydration.js";

enableHydration({ debugger: hydrationDebugger() });

The debugger module is tree-shaken out of production hydration bundles when
not imported, so the rich diagnostic helpers only land in builds that opt in.

Component authors can await both promises to distinguish prerendered content from successful hydration:

const controller = this.$fastController;
const prerendered = await controller.isPrerendered;
const hydrated = await controller.isHydrated;

if (prerendered && !hydrated) {
    // Had DSD but hydration wasn't enabled — client-side rendered
}

Custom directives can also await controller.isPrerendered and controller.isHydrated (both Promise on the ViewController interface) to determine how the view's content was rendered.

Define Extensions Copy Chapter

The static define() method on a FASTElement subclass accepts an optional second argument — an array of extension callbacks that are invoked with the resolved element definition before the element is registered with the platform. This enables a plugin pattern where reusable behaviors can hook into element registration.

import { FASTElement, type FASTElementExtension } from "@microsoft/fast-element";

function logger(): FASTElementExtension {
    return definition => {
        console.log(`Defining element: ${definition.name}`);
    };
}

class MyComponent extends FASTElement {
    // component code
}

MyComponent.define({ name: "my-component", template, styles }, [logger()]);

Each extension receives the full FASTElementDefinition, which includes the resolved element name, type, template, styles, and attribute metadata. Extensions run before customElements.define(), so any setup they perform is available when existing DOM elements are upgraded.

Overview (`packages/fast-router/README.md`) Copy Section

FAST Router

The @microsoft/fast-router package contains a history-based navigation and routing solution designed around Web Components. By using fast-router, you can create multi-page and full application experiences. The router works with any Web Components, but has special support for Web Components built on FAST.

Installation Copy Chapter

From NPM Copy Section

To install the fast-router library using npm:

npm install --save @microsoft/fast-router

Within your JavaScript or TypeScript code, you can then import library APIs like this:

import { FASTRouter } from '@microsoft/fast-router';

Looking for a setup that integrates with a particular front-end framework or bundler? Check out our integration docs.

Configuration at a Glance Copy Chapter

The router is currently in alpha while we address a few bugs, finish up some final polish, and write the full documentation. Below is a quick sample of how to configure the router, to help get you going while we complete the full documentation.

A Sample Route Configuration

/* Detailed source-code truncated for AI context efficiency. */

Using the Configuration with a Router

import { FASTElement, customElement } from '@microsoft/fast-element/fast-element.js';
import { css } from '@microsoft/fast-element/css.js';
import { html } from '@microsoft/fast-element/html.js';
import { FASTRouter } from '@microsoft/fast-router';
import { AppRouterConfiguration } from './routes';

FASTRouter;

const template = html<MainApplication>`
    <fast-router :config=${x => x.routerConfiguration}></fast-router>
`;

const styles = css`
  :host {
    contain: content;
  }

  :host, fast-router {  
    display: block;
    width: 100%;
    height: 100%;
  }
`;

@customElement({
  name: 'main-application',
  template,
  styles
})
export class MainApplication extends FASTElement {
  routerConfiguration = new AppRouterConfiguration();
}

Overview (`packages/fast-test-harness/README.md`) Copy Section

FAST Test Harness

The fast-test-harness package is a Playwright testing harness for FAST Element web components with CSR and SSR support.

Requirements Copy Chapter

• Node.js 22.18 or later
• Playwright 1.56 or later

Installation Copy Chapter

To install fast-test-harness using npm:

npm install --save-dev @microsoft/fast-test-harness

Test directory setup Copy Chapter

The harness serves a Vite dev server from a test/ directory in your project. CSR and SSR modes use different entry points from the same directory.

test/
├── index.html              # CSR: loads main.ts
├── ssr.html                # SSR: template with comment placeholders
├── vite.config.ts          # Vite config (shared by both modes)
└── src/
    ├── main.ts             # CSR: registers components, applies theme
    ├── entry-client.ts     # SSR: registers components for hydration
    └── entry-server.ts     # SSR: exports render() for fixture generation

Writing tests Copy Chapter

Import test and expect from the harness. Configure the component tag name with test.use(), then call fastPage.setTemplate() in each test to render it.

import { expect, test } from "@microsoft/fast-test-harness";

test.describe("Button", () => {
    test.use({ tagName: "my-button", innerHTML: "Click me" });

    test("should render", async ({ fastPage }) => {
        await fastPage.setTemplate();
        await expect(fastPage.element).toBeVisible();
    });

    test("should accept attributes", async ({ fastPage }) => {
        await fastPage.setTemplate({
            attributes: { appearance: "primary", disabled: true },
        });
        await expect(fastPage.element).toHaveAttribute("appearance", "primary");
    });

    test("should work inside a form", async ({ fastPage }) => {
        await fastPage.setTemplate(`
            <form>
                <my-button type="submit">Submit</my-button>
            </form>
        `);
        await expect(fastPage.element).toBeVisible();
    });
});

Use updateTemplate() to modify attributes or innerHTML after the initial render without navigating away from the page:

await fastPage.setTemplate();
await fastPage.updateTemplate(fastPage.element, { attributes: { disabled: true } });

The toHaveCustomState assertion checks ElementInternals custom states:

await expect(element).toHaveCustomState("checked");

Fixture options Copy Chapter

CSR files Copy Section

index.html loads a script that registers your components:

<!doctype html>
<html lang="en">
    <head><meta charset="UTF-8" /></head>
    <body>
        <script type="module" src="/src/main.ts"></script>
    </body>
</html>

main.ts registers components and applies global config. The body starts empty; setTemplate() injects HTML per test.

import "./define-all.js";
import { setTheme } from "./theme.js";
setTheme(lightTheme);

SSR files Copy Section

ssr.html contains comment placeholders the server fills in per request:

<!doctype html>
<html lang="en">
    <head>
        <title></title>
        
    </head>
    <body>
        
        
        <script type="module" src="/src/entry-client.ts"></script>
    </body>
</html>

entry-client.ts imports the harness SSR entry (which enables hydration) and registers components. Component definition modules should use template: declarativeTemplate(); this automatically defines FAST's internal <f-template> publisher.

import "@microsoft/fast-test-harness/ssr/entry-client.js";
import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";

import { MyButton, definition } from "../../src/button/index.js";

MyButton.define({
    name: definition.name,
    template: declarativeTemplate(),
});

entry-server.ts exports a render() function that the server calls for each setTemplate() request. It returns three strings that get injected into ssr.html:

export function render(queryObj: Record<string, string>): {
    template: string;    // <f-template> HTML → 
    fixture: string;     // rendered element HTML → 
    preloadLinks: string; // <link> tags → 
};

Use createSSRRenderer from the harness to build the render() function. It scans for component build artifacts (f-templates, stylesheets) and uses the @microsoft/fast-build WASM renderer to produce declarative shadow DOM on each request.

Multi-component package (all components in one package):

import { createSSRRenderer } from "@microsoft/fast-test-harness/ssr/render.js";

const { render } = createSSRRenderer({
    packageName: "@my-scope/web-components",
    tagPrefix: "my",
});

export { render };

Per-component packages (each component is a separate npm package):

import { createSSRRenderer } from "@microsoft/fast-test-harness/ssr/render.js";

const { render } = createSSRRenderer({
    tagPrefix: "my",
    components: [
        { name: "button", packageName: "@my-scope/button" },
        { name: "checkbox", packageName: "@my-scope/checkbox" },
    ],
});

export { render };

Server Copy Chapter

The package includes a Node.js HTTP server with Vite middleware that handles both CSR page serving and SSR fixture generation. Run it directly or let Playwright manage it via webServer:

// playwright.config.ts
export default defineConfig({
    webServer: {
        command: "fast-test-harness",
        port: 3278,
        reuseExistingServer: true,
    },
});

For custom setup, import startServer:

import { startServer } from "@microsoft/fast-test-harness/server.mjs";
await startServer(process.cwd(), "./test", "./test/vite.config.ts", {
    port: 4000,
    debug: true,
});

One server can host several test directories at separate paths. Set the matching
base fixture option for each test group.

await startServer(process.cwd(), process.cwd(), "./vite.config.ts", {
    routes: [
        { base: "/button/", root: "./packages/button/test" },
        { base: "/dialog/", root: "./packages/dialog/test" },
    ],
});

test.use({ base: "/button/", tagName: "my-button" });

CLI flags Copy Section

fast-test-harness [command] [options]

Commands:
  serve                    Start the test harness dev server (default)
  generate-templates       Generate <f-template> HTML files from compiled templates
  generate-stylesheets     Generate CSS files from compiled ElementStyles
  generate-webui-templates Generate WebUI-compatible DSD templates

Serve options:
  -p, --port <number>    Server port (default: 3278)
  -b, --base <path>      Base URL path (default: /)
  -r, --root <path>      Vite root directory (default: <cwd>/test)
  -c, --config <path>    Vite config file path (default: Vite auto-discovery)
  -d, --debug            Write SSR fixtures to temp/ for inspection
  -v, --version          Show version number
  -h, --help             Show help message

CLI flags take precedence over environment variables.

generate-templates preserves browser-valid <template> wrappers and strips
static wrappers even when the opening or closing tag includes ASCII whitespace
before >.

SSR renderer Copy Chapter

createSSRRenderer(options) scans for component build artifacts and returns a { render } object compatible with the server's entry-server.ts contract. It uses the @microsoft/fast-build WASM module to parse f-templates and render them into declarative shadow DOM, including wrapper tags whose opening or closing > is preceded by ASCII whitespace.

Exports Copy Chapter

Overview (`sites/benchmarks/README.md`) Copy Section

Benchmarking FAST templates and rendering scenarios

This package benchmarks FAST Element and FAST HTML rendering scenarios. It uses Playwright to automate Chrome, collects CDP trace data, computes timing statistics, and generates an interactive HTML report.

Prerequisites Copy Chapter

• Node.js >=22.12.0
• npm >=10
• Dependencies installed from repo root:

npm install

Running benchmarks Copy Chapter

From this folder (sites/benchmarks):

npm run bench

This will:

1. Build the scenarios with Vite (into server/dist)
2. Start the static server on http://localhost:5174
3. Run all discovered scenarios through Playwright
4. Print stats tables to the console
5. Generate an interactive HTML report at results/latest.html

Iteration count Copy Section

Default is 50 iterations per benchmark. Override with BENCH_ITERATIONS:

BENCH_ITERATIONS=100 npm run bench

Running specific scenarios Copy Section

Pass scenario names as arguments to filter which benchmarks run:

npm run bench -- basic attr-reflect

Each argument is matched as a substring, so basic runs basic/csr and basic/hydration. You can also target a specific variant:

npm run bench -- basic/csr

Running from repo root Copy Chapter

npm run bench -w @microsoft/fast-bench

Project structure Copy Chapter

src/
  bench.ts        Runner orchestrator (Playwright + CDP)
  chart.ts        SVG chart rendering
  report.ts       HTML report assembly
  trace.ts        CDP trace event parsing + stats
  scenarios/
    harness.ts    Shared benchmark runtime
    tree.ts       Tree data generator for scenarios
    report.css    Report styles (inlined into output)
    report.js     Report interaction (inlined into output)
    index.html    Dev server landing page
    basic/        Scenario directories...
    attr-reflect/
    bind-event/
    dot-syntax/
    ref-slotted/
    repeat/
    when/

Each scenario follows a consistent structure:

<scenario>/
  element.ts        Shared element class definition
  template.html     <f-template> for hydration variants
  csr/
    index.html      Client-side rendering entry
    main.ts         CSR variant script
  hydration/
    index.html      SSR + hydration entry (uses )
    main.ts         Hydration variant script
    render.ts       SSR HTML generator for Vite build-time rendering

Output Copy Chapter

The report at results/latest.html (symlinked to the most recent timestamped run) includes:

• Overlaid line charts per scenario with all variants (csr, hydration) on shared axes
• Hover-to-emphasize and click-to-select variant interaction
• Winner table showing the best value per metric/stat, color-coded by variant
• Variant drill-down — click a variant to see its full stats

Metrics collected per iteration:

Summary statistics: Min, Median, Mean, Geometric Mean, P95, Max. All values are in milliseconds.

Dev server Copy Chapter

For iterating on scenarios without running the full benchmark:

npm run serve

This starts Vite on http://localhost:5173 with hot reload.

Overview (`sites/website/README.md`) Copy Section

Website

This website is built using 11ty, a modern static website generator.

Installation Copy Chapter

Run the following commands in the root directory:

npm ci
npm run build

Local Development Copy Chapter

npm start

Build Copy Chapter

npm run build

This command generates static content into the build directory and can be served using any static content hosting service.

Version Banners Copy Chapter

The site supports configurable banners on documentation pages to communicate version status (e.g., stable, legacy, prerelease). Banners are defined in src/_data/versionBanners.js and rendered via src/_includes/version-banner.njk.

Configuration Copy Section

Edit src/_data/versionBanners.js to add, remove, or modify banners. Each version key maps to a configuration object:

"3.x": {
    enabled: false,             // Toggle the banner on/off
    type: "stable",             // "legacy" | "stable" | "prerelease"
    message: "You are viewing the current stable version of FAST.",
}

Prerelease banners should include any version-specific copy directly in the message.

Styles Copy Section

Banner CSS lives in src/css/version-banner.css and is loaded on all pages via root.njk.

Overview (`crates/microsoft-fast-build/benchmark-baselines/README.md`) Copy Section

Renderer performance baselines

Run all commands from the repository root. These are explicit measurements,
not portable timing assertions or automatically refreshed golden files.

npm run build -w @microsoft/fast-build
npm run bench:render -w @microsoft/fast-build -- --case=url_sink_siblings --output=/tmp/fast-render.json
npm run bench:render -w @microsoft/fast-build -- --case=url_sink_siblings --check-scaling
cargo bench --manifest-path crates/microsoft-fast-build/Cargo.toml --bench render

The native Criterion groups separate rendering with parsed state, state parsing
plus rendering, and locator construction. The Node runner calls the packaged
WASM export in a fresh --expose-gc child for each sample, warms it once with up
to 1,000 instances (configurable with --warmup-count), forces
GC, and reports median/p95 wall time, CPU time, JSON stringify time, input/output
bytes, throughput, before/after memory, process peak RSS, and parent-sampled RSS
(100 ms on macOS/Linux). Peak RSS includes warmup and verification, not just the
measured call. No in-child timer is used to observe a blocked WASM call.
Sampled RSS is null if the child exits before a sample or the platform is not
macOS/Linux. Process peak RSS remains available independently of timer sampling.
Node throughput uses the requested rendered-instance count (not only custom
host count); Criterion reports instances/second for render phases and template
definitions/second for locator construction.

--case, --counts, and --samples narrow a run. Both marker modes always run.
Omit --case to run the full matrix; repeat/state-clone workloads can be very
expensive, so begin with the primary URL regression on a development machine.
Definitions use 50/200/1,000 definitions with payloads 1/20; other cases use
1,000/5,000/20,000 instances. State overlays run with 0/200 extra root keys, with
and without host attributes. corpus.json is the shared recipe used by native
benchmarks, Rust parity tests, and the Node fixture generator.

Use --compare= to enforce output hash/length parity and report
speedups. --check-scaling explicitly checks the URL case's 20k/5k ratio <= 5
and fits setup + coefficient * count^exponent from all three sizes, requiring
exponent <= 1.15. Timing checks are opt-in: do not enable them on unpinned PR
runners. At least three samples on otherwise idle, stable hardware are recommended.
Output paths are created exclusively; a run never overwrites an existing baseline.
Reports snapshot the starting git revision, dirty-worktree flag, and WASM
SHA-256. A dirty worktree can include benchmark helpers, reports, or generated
files; it does not necessarily mean the renderer implementation is uncommitted.
Use the artifact hash and source provenance together.

Local before/after measurements Copy Chapter

The checked-in aarch64-apple-darwin-before.json and
aarch64-apple-darwin-after.json measure the URL sibling regression on an Apple
M3 Pro with Node 22.22.1, three fresh-child samples per size/mode, and a
1,000-instance warmup. These are local macOS measurements, not Linux/reference
machine results or full-corpus performance claims.

All six before/after output hashes and byte lengths match. The optimized
20k/5k ratios are 3.77 (v3) and 3.68 (v2), with fitted exponents 0.99 and
0.96 respectively. Both pass the 1.15 exponent threshold. The original v3
ratio is 16.49 with exponent 2.02; its
--check-scaling run intentionally failed after writing the baseline report.

Process peak RSS at 20,000 instances was 106.06 -> 108.94 MiB (v3) and
99.17 -> 114.52 MiB (v2). This scanner change does not demonstrate a memory
reduction. Peak RSS includes warmup and hash verification; shorter optimized
calls also make 100 ms RSS samples sparse or unavailable.

The before artifact was built from a38c2f1aea2840ea530de42d055f0a03cefe5872
before renderer edits, with the new benchmark helpers present. Its WASM SHA-256 is
c749f46306b561bb55e45700cf19f7ed3db8ad67d01cd8e9a3b7198943c4ca51.
The after artifact was built from 3e9117770a8da29c369d3d31a04e37da25fa08fb;
its WASM SHA-256 is
c128e5d88ff457dedc0549438ec9e2d11450e0a89e997899b003898e587063bc.
Both reports retain their starting provenance even if the worktree changes
during measurement.

To reproduce an optimized comparison after building the package:

node packages/fast-build/test/performance/render-entry.mjs --case=url_sink_siblings --compare=crates/microsoft-fast-build/benchmark-baselines/aarch64-apple-darwin-before.json --output=/tmp/fast-render-after.json --check-scaling

Profiling the remaining workloads Copy Chapter

The aarch64-apple-darwin-*-profile.json reports were captured after the scanner
fix at a58548a5cec9f4508fd46693f9ec63443e07b0b6. Five reports contain 36
fresh-child packaged-WASM measurements in both marker modes; the native report
summarizes six symbolized CPU captures and separate Criterion quick estimates.
No renderer optimization was made during this investigation.

The WASM runs use three samples and a 250-instance warmup. Repeat and plain
controls use 250/1,000 instances, state cases use 1,000/5,000 hosts with 0/200
extra root keys, and definitions use 50/200/1,000 templates with payloads 1/20.
These bounded sizes avoid multiplying an already expensive state-cloning path
into an unhelpful full-matrix run. They do not establish 20k acceptance targets.

Findings and next optimization Copy Section

Child-state construction is the strongest measured next target. In native v3
profiles, build_custom_element_child_root occurs in 1,075/2,001 main-thread
samples (53.72%) for repeated custom elements and 1,205/2,049 (58.81%) for
attribute overlays with 200 root keys. Its descendant stacks include
RawTable::clone, Vec::clone, String::clone, and allocator/copy routines.
Separate destruction stacks and frequent free routines show additional cleanup
work outside those inclusive counts.

The repeat fixture's root contains the entire items array. Every attributed
child clones that root before overlaying host attributes; increasing the
number of items therefore increases both the number and size of those copies.
Packaged-WASM repeat times rise from 53.55 to 422.71 ms (v3) and 45.86 to
431.95 ms (v2) for a 4x instance increase. This is evidence for the remaining
state-copying hazard, not a fitted 1k/5k/20k scaling claim. Removing attributes
is not a valid optimization because it would change state semantics.

The overlay controls reinforce this finding: adding 200 unused root keys
increases v3 time from 4.30 to 35.25 ms at 1,000 attributed hosts, while the
no-overlay case changes only from 3.40 to 3.70 ms. Output hashes within each
overlay/no-overlay workload are unchanged by those extra unused keys.
Borrowed child-state overlays should be the next focused optimization, with
state precedence/inheritance parity preserved.

The many-definition case has a different profile. Native locator construction
takes about 0.243 ms for 1,000 definitions with payload 20, versus about
34.48 ms for rendering with an already prepared locator. Code-sample
preprocessing appears in 1,257/2,148 (58.52%) locator-phase samples, but that
phase is small here; its percentage must not be interpreted as 58.52% of
end-to-end rendering. The render profile instead contains string searching,
attribute parsing/binding resolution, escaping, and copying. Compiled
templates, parse-once attributes, and buffered sinks remain relevant follow-ons.

Native quick estimates are independent, low-sample diagnostic runs; do not
subtract them to infer isolated parsing costs. Native sampling percentages
are inclusive stack frequencies, not exclusive CPU time, allocation counts,
or WASM phase percentages. Zero observed frames do not prove zero work,
especially with inlining. Native allocator behavior does not establish WASM
memory behavior. Raw captures remain local; the compact report retains their
hashes, selected symbols/counts, compiler/build flags, and binary provenance.

Reproducing the investigation Copy Section

Use new output paths; these commands do not refresh the checked-in reports:

npm run bench:render -w @microsoft/fast-build -- --case=repeat_custom_elements --counts=250,1000 --samples=3 --warmup-count=250 --output=/tmp/fast-repeat-profile.json
npm run bench:render -w @microsoft/fast-build -- --case=plain_bound_elements --counts=250,1000 --samples=3 --warmup-count=250 --output=/tmp/fast-plain-profile.json
npm run bench:render -w @microsoft/fast-build -- --case=large_state_overlay --counts=1000,5000 --samples=3 --warmup-count=250 --output=/tmp/fast-overlay-profile.json
npm run bench:render -w @microsoft/fast-build -- --case=large_state_no_overlay --counts=1000,5000 --samples=3 --warmup-count=250 --output=/tmp/fast-no-overlay-profile.json
npm run bench:render -w @microsoft/fast-build -- --case=many_definitions --samples=3 --warmup-count=250 --output=/tmp/fast-definitions-profile.json
CARGO_PROFILE_BENCH_DEBUG=true RUSTFLAGS="-C force-frame-pointers=yes" cargo bench --manifest-path crates/microsoft-fast-build/Cargo.toml --bench render -- '^repeat_custom_elements/v3/render/1000/payload1/root0$' --profile-time 8 --noplot

For a native CPU capture, run the final command in one terminal. Once Criterion
prints Profiling for, attach macOS sample 3 1 -file <new-path>
from another terminal. Sample the benchmark executable, not Cargo. Building
first with the same environment and --no-run --message-format=json reveals
its path in the compiler-artifact record. A direct invocation of that binary
must include --bench, otherwise Criterion performs a correctness run rather
than a profiling loop. The profiling environment is opt-in and does not change
production WASM build settings or add dependencies.

The six filters used for CPU captures were:

^repeat_custom_elements/v3/render/1000/payload1/root0$
^plain_bound_elements/v3/render/1000/payload1/root0$
^large_state_overlay/v3/render/1000/payload1/root200$
^large_state_no_overlay/v3/render/1000/payload1/root200$
^many_definitions/v3/locator/1000/payload20/root0$
^many_definitions/v3/render/1000/payload20/root0$

Replace --profile-time 8 with --quick for diagnostic timing estimates.
The compact native report sums counts across call-graph entries for each
named non-recursive function; recursive frame totals must not be summed as if
they represented distinct samples. Platform-specific Linux profiling remains
outstanding; native allocation baselines are described below.

Native allocation baselines Copy Chapter

aarch64-apple-darwin-allocations.json records 30 isolated release-build samples
using allocation-counter 0.8.1. Each request starts a fresh native process;
the feature-gated example and its integration test are the only executables
that use this development allocator. No library allocator, WASM export,
production build setting, or rendering behavior changes.

Run from the repository root, writing only to a new output path:

node crates/microsoft-fast-build/benches/profile-allocations.mjs --output=/tmp/fast-allocations.json
cargo run --manifest-path crates/microsoft-fast-build/Cargo.toml --release --features allocation-profiling --example profile-allocations -- --case=large_state_overlay --count=1000 --root-keys=200 --mode=v2 --phase=render --output=/tmp/fast-overlay-allocations.json
cargo test --manifest-path crates/microsoft-fast-build/Cargo.toml --features allocation-profiling --test allocation-profiling
node --test crates/microsoft-fast-build/benches/profile-allocations.test.mjs

Single-request options are --case, --count, --payload, --root-keys,
--mode=v3|v2, --phase=render|parse_state_and_render|locator, and --output,
all in --option=value form. Defaults are repeat/250/payload 1/root 0/v3/render.
Counts/payloads must be positive; only definition workloads accept payload
changes, and only large-state workloads accept root-key changes. Unknown,
duplicate, or invalid options fail explicitly. Reports refuse overwrites,
including a second exclusive-create check at write time.

Runner matrix/provenance/output-safety tests also run through
npm run test:node -w @microsoft/fast-build; they do not invoke Cargo.
The feature-enabled Rust integration test above exercises the actual counter.

The matrix covers repeat/plain controls at 100/250/1,000 instances, overlays
with/without attributes and 0/200 extra root keys at 1,000 hosts, state parsing
plus rendering at 1,000 repeat/plain items, and all three phases for 1,000
definitions with payload 20. Every case runs in both marker modes. One sample
per request is recorded; these counters are not timing medians.

Measurement boundaries and interpretation Copy Section

Fixture generation, pre-parsed state, and prepared locators are outside the
measurement. render counts only rendering; parse_state_and_render also
counts parsing the state JSON; locator counts cloning/preprocessing templates
and building the new locator, not template-JSON parsing or rendering.
Locator output is validated by rendering afterward, outside the counter.
Output hashes and byte lengths are checked against ordinary native rendering
in default tests, without asserting platform-specific allocation thresholds.

The returned HTML string or locator stays alive at the counter boundary:
retainedBytes includes its capacity, not just logical HTML length, and does
not indicate a leak. peakLiveBytes excludes inputs allocated before the
phase; it is not total process heap, RSS, or WASM memory pages. Byte and block
peaks are independent maxima. Cumulative totalBytes and totalBlocks count
allocation events, including replacement allocations during reallocation,
not the number or size of currently live objects. This profiler captures the
current thread only; future threaded rendering would require another strategy.
The counter uses allocate/copy/free reallocation rather than in-place system
reallocation: event totals and temporary old/new-buffer overlap reflect that
instrumentation strategy, not necessarily the production allocator's peaks.
It does not collect allocation-site stacks or measure bytes copied/allocator
overhead, and should not be used for uninstrumented speed comparisons.

Provenance includes starting commit/dirty status, release executable SHA-256,
Cargo.lock SHA-256, compiler, target, and allocator identification. The matrix
rejects changed provenance or duplicate samples. The checked-in captures were
made with the new harness uncommitted against renderer source
8b9c524f3a6a7544919588e708c4ad0c98a8197b; their binary/lock hashes identify
the measured development artifact. Neither captured timing nor allocation
data is silently regenerated by tests.

Findings Copy Section

The 4x repeat increase produces about 15x more allocation events/bytes, while
plain controls remain approximately proportional to instance count. Adding
200 unused root keys multiplies attributed-host allocation volume by about
40x, yet leaves the no-attribute control unchanged. Within each state control,
unused keys do not change output hashes. Both marker modes show the same
state-copying pattern; native locator counters are identical across modes
because marker rendering is outside that phase.

This strengthens the case for borrowed child-state overlays as the next
runtime optimization. It is a baseline, not the proposed 50% allocation
reduction or any 20k/stable-host/Linux/WASM acceptance claim.

Output compatibility and remaining work Copy Chapter

Correctness runs in normal Rust/Node tests at 0/1/2/1,000 instances in both marker
modes. The shared benches/fixtures/expected-baseline.json records pre-optimization
SHA-256, byte length, host count, binding/repeat marker counts, and attribute marker
counts. It also verifies normal/legacy-stream byte parity. Regeneration is explicit:

node packages/fast-build/test/performance/render-entry.mjs --golden=/tmp/fast-golden.json

Review changes against the checked-in golden; do not replace it just to make a
regression pass. Profiles and output hashes must be compared with the same
toolchain and fixture recipe. The runner cannot isolate internal WASM phases,
WASM memory pages (not exported), native allocation counts, or file writes; those
require separate profiling. The schema does not invent measurements for them.

Rust parity tests also render every remaining-workload WASM report record and
verify its output hash, bytes, and marker counts, including the larger
definition payloads and state-overlay controls. They do not assert timing.

The completed optimization addresses directive discovery only. Compiled templates, buffered
recursive writes, state overlays, prepared WASM handles, and genuinely incremental
sessions remain separate work. stream: true still materializes all chunks.

Overview (`examples/csr/todo-app/README.md`) Copy Section

Todo app tutorial

A To-Do app, written entirely with fast-element.

Note: A step by step tutorial will be coming to the site soon. In the mean
time, you can run npm install and then npm start to see the example.

Note: This example uses an LSP, to enable this in VS Code try the following:

• Open a javascript/typescript file and use the command palette to Select typescript version and choose the local workspace version.

Design system Copy Chapter

This example consumes the shared @microsoft/fast-examples-design-system
workspace package. The design-system package is CSS-only — there are no
JavaScript or TypeScript exports. src/main.ts imports
@microsoft/fast-examples-design-system/tokens.css once, and the rest of the
app references the registered --fast-* design tokens through var(...).

The app uses the light theme. <html data-theme="light"> is set
statically in index.html; the app does not implement a
theme toggle. (The shared design-system package supports dark and
system-preference themes via the same data-theme attribute — see
examples/design-system/README.md — but this
example deliberately keeps the surface area minimal and demonstrates only
token consumption.)

For the shared package overview, the token catalog, and authoring rules,
see examples/design-system/README.md and
examples/design-system/DESIGN.md.

Token usage Copy Chapter

The todo app styles use shared tokens for layout, surfaces, typography, and
interaction states. For example:

• App shell surface: --fast-background-layer-primary-solid,
  --fast-foreground-ctrl-neutral-primary-rest,
  --fast-stroke-divider-subtle, --fast-corner-large,
  --fast-shadow-card-rest, --fast-padding-content-medium.
• Primary action (Add): --fast-background-ctrl-brand-rest,
  --fast-foreground-ctrl-on-brand-rest, --fast-stroke-divider-brand,
  --fast-background-ctrl-brand-hover, --fast-background-ctrl-brand-pressed.
• Typography: --fast-text-style-default-regular-font-family,
  --fast-text-global-body3-font-size paired with
  --fast-text-global-body3-line-height,
  --fast-text-global-display2-font-size paired with
  --fast-text-global-display2-line-height.
• Destructive action (per-row delete button):
  --fast-status-danger-tint-foreground (red text at rest),
  --fast-status-danger-tint-background (subtle red hover fill),
  --fast-status-danger-tint-stroke (focus outline).
• Focus rings: --fast-ctrl-focus-outer-stroke paired with
  --fast-ctrl-focus-outer-stroke-width.
• Motion: --fast-duration-fast and --fast-curve-easy-ease for hover and
  press transitions.

No design value (color, font size, line height, padding, gap, corner,
stroke width, shadow, duration, or curve) is hard-coded in the app's
component styles.

Overview (`examples/csr/todo-mobx-app/README.md`) Copy Section

MobX Todo App (FAST)

A small Todo app that uses MobX as its state library and @microsoft/fast-element for its Web Components. It is the MobX counterpart to examples/csr/todo-app, and the two render an identical UI — the same <h1>FAST Todos</h1>, <todo-form> (input + "Add Todo"), <select> filter (All / Active / Completed), and `` of rows with a checkbox, description, and × button. Like every example app it consumes the shared @microsoft/fast-examples-design-system tokens for styling.

The example shows that you do not need a custom decorator or any bridge code to integrate MobX with @microsoft/fast-element — a single autorun per component, set up in connectedCallback and disposed in disconnectedCallback, is all that is needed.

Running Copy Chapter

# from the monorepo root
npm ci
npm run build -w @microsoft/fast-element
npm start -w @microsoft/fast-todo-mobx-app-example

The Vite dev server runs at http://localhost:9001.

To produce a production build:

npm run build -w @microsoft/fast-todo-mobx-app-example

The output is written to examples/csr/todo-mobx-app/www/.

The pattern, in one component Copy Chapter

<todo-app> mirrors the slices of MobX state it renders into FAST @observable fields with a single autorun set up in connectedCallback. The template binds to those plain FAST observables as usual.

import { FASTElement, observable } from "@microsoft/fast-element";
import { autorun } from "mobx";
import { type Todo, type TodoListFilter, todoStore } from "./state/index.js";

export class TodoApp extends FASTElement {
    @observable public items: readonly Todo[] = [];
    @observable public activeFilter: TodoListFilter = "all";

    private _disposer?: () => void;

    public connectedCallback(): void {
        this._disposer = autorun(() => {
            this.items = todoStore.filtered.map(t => ({
                id: t.id,
                description: t.description,
                done: t.done,
            }));
            this.activeFilter = todoStore.activeFilter;
        });
        super.connectedCallback();
    }

    public disconnectedCallback(): void {
        super.disconnectedCallback();
        this._disposer?.();
        this._disposer = undefined;
    }

    public activeFilterChanged(
        _prev: TodoListFilter | undefined,
        next: TodoListFilter | undefined,
    ): void {
        if (next !== undefined && next !== todoStore.activeFilter) {
            todoStore.setFilter(next);
        }
    }
}

That is the entire integration. The template binds ${x => x.items}, ${x => x.activeFilter}, etc. exactly as it would for any other FAST element.

Why this works Copy Section

• autorun runs immediately, then re-runs whenever any MobX-observable it read changes.
• Each re-run reassigns FAST @observable fields, which fires FAST's own change notification, which patches the bound DOM.
• The .map(...) copies each todo into a plain {id, description, done} object — that simultaneously creates a fresh array reference on every run (so FAST always sees the assignment) and ensures the autorun depends on every observable field it serializes.
• Calling autorun before super.connectedCallback() ensures the mirror fields have correct values before the template binds, avoiding any initial flicker.
• The disposer returned by autorun is stored on the element and released on disconnect, so reactions never outlive the element.

The <select> element uses a twoWay binding to activeFilter. activeFilterChanged propagates user changes back to the MobX store (gated by an equality check, so the autorun's store-driven assignment never loops).

What the app demonstrates Copy Chapter

Project layout Copy Chapter

examples/csr/todo-mobx-app/
├── index.html                     # mounts <todo-app>, sets data-theme="light"
├── package.json
├── tsconfig.json
├── vite.config.ts
├── README.md                      # this file
├── DESIGN.md                      # why the autorun pattern, lifecycle details
└── src/
    ├── design-system.d.ts         # module shim for the tokens stylesheet import
    ├── exports.ts                 # barrel for tooling
    ├── main.ts                    # entry — imports tokens.css, wires storage, defines <todo-app>
    ├── state/                     # MobX layer (framework-agnostic)
    │   ├── index.ts
    │   ├── persistence.ts
    │   └── todo-store.ts
    ├── todo-app.{ts,template.ts,styles.ts}
    └── todo-form.{ts,template.ts,styles.ts}

See DESIGN.md for an explanation of why this pattern is sufficient.

License Copy Chapter

MIT — see the monorepo root.

Overview (`examples/ssr/chat-app/README.md`) Copy Section

Chat App Example

A small declarative FAST chat demo that pre-renders its initial markup with @microsoft/fast-build and streams canned assistant replies with a hidden iframe plus document.write().

Design system Copy Chapter

This example consumes the shared @microsoft/fast-examples-design-system
workspace package. The design-system package is CSS-only — src/main.ts
imports @microsoft/fast-examples-design-system/tokens.css once, and
public/styles.css references the registered --fast-* tokens through
var(...).

The app uses the dark theme statically. <html data-theme="dark"> is set
in entry.html, so the FAST build step carries that attribute
into the generated index.html. The example does not implement a runtime
theme toggle.

For the shared package overview, the token catalog, and authoring rules, see
../../design-system/README.md and
../../design-system/DESIGN.md.

What it demonstrates Copy Chapter

• declarative FAST custom elements via subclass define() calls + @microsoft/fast-element/declarative.js <f-template>s
• initial markup rendered from entry.html + templates.html
• chunked assistant response streaming with the Jake Archibald iframe technique
• mixed native HTML and FAST custom elements in each canned reply
• exact-match canned prompts with a fallback response

Suggested prompts Copy Chapter

Use these exact prompts to walk through the conversation:

• Hi
• How are you?
• What's the weather like?
• Tell me a joke
• What can you do?
• Goodbye

Run locally Copy Chapter

From the repository root:

npm run build -w @microsoft/fast-chat-app-example
npm run start -w @microsoft/fast-chat-app-example

Or from this folder:

npm run build
npm start

The build first regenerates index.html from entry.html, state.json, and templates.html, then runs TypeScript and Vite.

Files Copy Chapter

• entry.html — source document for the FAST build step
• state.json — initial state used while pre-rendering the page shell
• templates.html — declarative FAST templates for the custom elements
• build-markup.mjs — runs @microsoft/fast-build and injects the templates into index.html
• public/styles.css — token-based shared stylesheet for the page shell and component shadow roots
• src/ — runtime classes, canned conversation data, and hydration bootstrap
• index.html — generated pre-rendered page used by Vite

See DESIGN.md for architecture details, design-system notes, and the canned conversation data.

Overview (`examples/ssr/webui-todo-app/README.md`) Copy Section

WebUI Todo App

A Todo app demonstrating FAST declarative HTML templates with
webui prerendering and hydration.

This example shows how to combine @microsoft/fast-element/declarative.js declarative templates
with @microsoft/webui for server-side prerendering, producing a fast initial
render that hydrates into a fully interactive FAST web component application.

Features Copy Chapter

• Declarative templates: Uses .html and .css files instead of
  imperative html/css tagged template literals
• Server-side prerendering: webui serve compiles declarative templates
  and renders initial state into static HTML
• Client-side hydration: @microsoft/fast-element/declarative.js picks up prerendered DOM
  and attaches FAST reactive bindings
• Todo functionality: Add items via a form, filter by status (all,
  active, completed), toggle completion via native checkbox, delete items

Prerequisites Copy Chapter

From the monorepo root, install dependencies and build packages:

npm ci
npm run build

Running Copy Chapter

# Build client bundle and start the webui dev server
npm start -w @microsoft/fast-webui-todo-app-example

The app will be available at http://localhost:8081.

For development with live reloading, run the client and server in separate
terminals:

# Terminal 1: Watch and rebuild client bundle
npm run start:client -w @microsoft/fast-webui-todo-app-example

# Terminal 2: Start webui dev server with --watch
npm run start:server -w @microsoft/fast-webui-todo-app-example

Design system Copy Chapter

This example consumes the shared @microsoft/fast-examples-design-system
workspace package. The design-system package is CSS-only — there are no
JavaScript or TypeScript exports. src/index.ts imports
@microsoft/fast-examples-design-system/tokens.css once, and the rest of the
app references the registered --fast-* design tokens through var(...).

The app uses the light theme. <html data-theme="light"> is set
statically in src/index.html; the app does not implement
a runtime theme toggle. (The shared design-system package supports dark and
system-preference themes via the same data-theme attribute — see
../../design-system/README.md — but this
example deliberately keeps the SSR surface area minimal and demonstrates only
token consumption.)

For the shared package overview, the token catalog, and authoring rules, see
../../design-system/README.md and
../../design-system/DESIGN.md.

Architecture Copy Chapter

Server-side (`webui serve`) Copy Section

The webui CLI serves the app with the --plugin=fast flag, which enables
FAST-aware template processing:

1. Scans ./src for declarative HTML templates (.html files wrapped in
   <f-template> or containing <template shadowrootmode="open">)
2. Reads initial state from ./data/state.json
3. Renders templates server-side with {{}} bindings resolved from state
4. Injects Declarative Shadow DOM for instant first paint
5. Serves the bundled client assets from ./dist

src/index.ts imports @microsoft/fast-examples-design-system/tokens.css.
When esbuild bundles the entry point, it emits both dist/index.js and
dist/index.css. src/index.html links /index.css so the shared --fast-*
tokens are available during prerendering and after hydration.

Templates (`src/todo-app/`, `src/todo-item/`) Copy Section

Each component uses co-located files:

• *.html — Declarative template with <template shadowrootmode="open">
  and FAST bindings
• *.css — Scoped styles loaded via <link rel="stylesheet"> in the shadow
  DOM
• *.ts — Component class using FASTElement with define()

Client entry (`src/index.ts`) Copy Section

Bootstraps hydration by:

1. Enabling hydration with enableHydration({ markers: markers_v2 }) — the
   markers_v2 reader is required because the webui --plugin=fast server
   still emits FAST Element 2.x indexed hydration markers
2. Importing components, which register themselves via subclass define() calls
   using declarativeTemplate() and observerMap()
3. Resolving matching <f-template> definitions to hydrate prerendered shadow DOM

Binding syntax Copy Section

Template directives Copy Section

Packages Fast Element Docs Architecture Intro (`packages/fast-element/docs/architecture/intro.md`) Copy Section

Introduction

This document (and the linked documents) explains how the exports and side effects of @microsoft/fast-element are used to create custom elements.

@microsoft/fast-element is designed to run in a client-side browser Window
runtime. Its element lifecycle, rendering, and update queue assume browser DOM,
Custom Elements, Shadow DOM, and requestAnimationFrame are available. Workers,
server-side JavaScript runtimes, and other non-window hosts are not supported
targets for the FAST Element client runtime.

Glossary Copy Chapter

• Overview: How the @microsoft/fast-element should be used by a developer and what code is executed during the first render.
• FASTElement: How the FASTElement is architected.
• html tagged template literal: How the html tagged template literal takes and converts the contents into a ViewTemplate.
• Updates queue: How updates to attributes and observables are processed.

Packages Fast Element Docs Architecture Overview (`packages/fast-element/docs/architecture/overview.md`) Copy Section

General FAST usage

FASTElement is an extension of HTMLElement which makes use of Custom Element APIs native to the browser. It also supplies the following methods:

• The define method combines the Custom Element name, template, style, and other options into a FASTElementDefinition, then uses the native Custom Element define() to register the Custom Element with a Custom Element Registry.
• The from method allows the use of Customized Built-in elements, which extend from native elements such as HTMLButtonElement.

Creating a Custom Element from FASTElement Copy Section

A basic developer flow for defining a custom element looks like this:

flowchart TD
    A[Create a <code>FASTElement</code> web component by extending the <code>FASTElement</code> class] --> F
    F[Prepare the definition with template and styles] --> G[Define the component in the browser with <code>define()</code>]

Let's take a look at the definition step to see what the FAST architecture is doing at this stage.

Defining a Custom Element Copy Section

The subclass define() method creates a new FASTElementDefinition, which includes all metadata needed for the element (such as templates, attributes, and styles), and registers it with the configured Custom Element Registry. The resulting object can be retrieved via ElementController.definition.

A Custom Element in JavaScript is sent to the Browser Copy Chapter

Let's step back from defining the Custom Element and consider what is happening when we import from the @microsoft/fast-element package.

The FAST Element client runtime is expected to run in the browser Window.
Custom element definition, connection, rendering, and update scheduling all rely
on browser APIs such as the Custom Element Registry, DOM, Shadow DOM, and
requestAnimationFrame.

First, a global FAST property will be created if one does not already exist, typically in browser on the window.

Additionally, when Custom Elements are included in a script a few things might happen even before a Custom Element gets detected by the browser. First, there are initial side effects caused by the use of decorators. These include the attr decorator from @microsoft/fast-element and the observable decorator from @microsoft/fast-element.

Here is a basic flow of what code is executed and when during initial load of a script that contains a FAST defined Custom Element:

flowchart TD
    A@{ shape: circle, label: "The browser loads the JavaScript file containing FAST and FAST Custom Element definitions" }
    B@{ shape: rect, label: "The FAST global is added to the window" }
    A --> B
    C@{ shape: rect, label: "A Custom Element executes the <code>compose</code> step"}
    B --> C
    D@{ shape: procs, label: "<ul style='text-align: left'><li>Any defined observable decorators are added to the FAST global</li><li>An attribute decorator locates the associated Custom Elements constructor which it uses to push itself to the Custom Elements attribute collection</li></ul>"}
    C --> D
    F@{ shape: rect, label: "An HTML tagged template literal is executed for the FAST Custom Element and applied to the definition" }
    D --> F
    G@{ shape: rect, label: "The <code>define</code> step is hit and the <code>customElement</code> is registered with the Custom Element Registry" }
    F --> G
    H@{ shape: rect, label: "A Custom Element is detected on the page and the browser initializes it" }
    I@{ shape: dbl-circ, label: "The lifecycle steps for <code>FASTElement</code> are executed" }
    G --> H
    H --> I

Sites Website Src Docs 2.X Getting Started (`sites/website/src/docs/2.x/getting-started.md`) Copy Section

layout: 2x eleventyNavigation: key: getting-started2x title: Getting Started order: 2 navigationOptions: activeKey: getting-started2x permalink: false Copy Chapter

Sites Website Src Docs 3.X Getting Started (`sites/website/src/docs/3.x/getting-started.md`) Copy Section

layout: 3x eleventyNavigation: key: getting-started3x title: Getting Started order: 2 navigationOptions: activeKey: getting-started3x permalink: false Copy Chapter

Sites Website Src Docs 1.X Api Fast Colors.Histogram.Gethistogramindex (`sites/website/src/docs/1.x/api/fast-colors.histogram.gethistogramindex.md`) Copy Section

id: fast-colors.histogram.gethistogramindex title: Histogram.getHistogramIndex property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-colors > Histogram > getHistogramIndex

Histogram.getHistogramIndex property Copy Chapter

Signature:

getHistogramIndex: (r: number, g: number, b: number) => number;

Sites Website Src Docs 1.X Api Fast Colors.Matchlightnessindex (`sites/website/src/docs/1.x/api/fast-colors.matchlightnessindex.md`) Copy Section

id: fast-colors.matchlightnessindex title: matchLightnessIndex() function hide_title: true layout: 1x Copy Chapter

@microsoft/fast-colors > matchLightnessIndex

matchLightnessIndex() function Copy Chapter

Takes the input color and compares it to each color in the reference array to find the index with the closest Lightness value in HSL color space

Signature:

export declare function matchLightnessIndex(input: ColorRGBA64, reference: ColorRGBA64[]): number;

Parameters Copy Chapter

Returns:

number

Sites Website Src Docs 1.X Api Fast Element.Executioncontext.Index (`sites/website/src/docs/1.x/api/fast-element.executioncontext.index.md`) Copy Section

id: fast-element.executioncontext.index title: ExecutionContext.index property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-element > ExecutionContext > index

ExecutionContext.index property Copy Chapter

The index of the current item within a repeat context.

Signature:

index: number;

Sites Website Src Docs 1.X Api Fast Element.Htmldirective.Targetindex (`sites/website/src/docs/1.x/api/fast-element.htmldirective.targetindex.md`) Copy Section

id: fast-element.htmldirective.targetindex title: HTMLDirective.targetIndex property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-element > HTMLDirective > targetIndex

HTMLDirective.targetIndex property Copy Chapter

The index of the DOM node to which the created behavior will apply.

Signature:

targetIndex: number;

Sites Website Src Docs 1.X Api Fast Element.Nodebehaviorfactory.Targetindex (`sites/website/src/docs/1.x/api/fast-element.nodebehaviorfactory.targetindex.md`) Copy Section

id: fast-element.nodebehaviorfactory.targetindex title: NodeBehaviorFactory.targetIndex property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-element > NodeBehaviorFactory > targetIndex

NodeBehaviorFactory.targetIndex property Copy Chapter

The index of the DOM node to which the created behavior will apply.

Signature:

targetIndex: number;

Sites Website Src Docs 1.X Api Fast Element.Splice.Index (`sites/website/src/docs/1.x/api/fast-element.splice.index.md`) Copy Section

id: fast-element.splice.index title: Splice.index property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-element > Splice > index

Splice.index property Copy Chapter

The index that the splice occurs at.

Signature:

index: number;

Sites Website Src Docs 1.X Api Fast Foundation.Datagrid.Focuscolumnindex (`sites/website/src/docs/1.x/api/fast-foundation.datagrid.focuscolumnindex.md`) Copy Section

id: fast-foundation.datagrid.focuscolumnindex title: DataGrid.focusColumnIndex property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-foundation > DataGrid > focusColumnIndex

DataGrid.focusColumnIndex property Copy Chapter

The index of the column that will receive focus the next time the grid is focused. This value changes as focus moves to different rows within the grid. Changing this value when focus is already within the grid moves focus to the specified column.

Signature:

focusColumnIndex: number;

Sites Website Src Docs 1.X Api Fast Foundation.Datagrid.Focusrowindex (`sites/website/src/docs/1.x/api/fast-foundation.datagrid.focusrowindex.md`) Copy Section

id: fast-foundation.datagrid.focusrowindex title: DataGrid.focusRowIndex property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-foundation > DataGrid > focusRowIndex

DataGrid.focusRowIndex property Copy Chapter

The index of the row that will receive focus the next time the grid is focused. This value changes as focus moves to different rows within the grid. Changing this value when focus is already within the grid moves focus to the specified row.

Signature:

focusRowIndex: number;

Sites Website Src Docs 1.X Api Fast Foundation.Datagridrow.Rowindex (`sites/website/src/docs/1.x/api/fast-foundation.datagridrow.rowindex.md`) Copy Section

id: fast-foundation.datagridrow.rowindex title: DataGridRow.rowIndex property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-foundation > DataGridRow > rowIndex

DataGridRow.rowIndex property Copy Chapter

The index of the row in the parent grid. This is typically set programmatically by the parent grid.

Signature:

rowIndex: number;

Sites Website Src Docs 1.X Api Fast Foundation.Listbox.Selectedindex (`sites/website/src/docs/1.x/api/fast-foundation.listbox.selectedindex.md`) Copy Section

id: fast-foundation.listbox.selectedindex title: Listbox.selectedIndex property hide_title: true layout: 1x Copy Chapter

@microsoft/fast-foundation > Listbox > selectedIndex

Listbox.selectedIndex property Copy Chapter

The index of the selected option.

Signature:

selectedIndex: number;

Sites Website Src Docs 1.X Api Index (`sites/website/src/docs/1.x/api/index.md`) Copy Section

id: index title: API Reference hide_title: true layout: 1x Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Sites Website Src Docs 1.X Components Getting Started (`sites/website/src/docs/1.x/components/getting-started.md`) Copy Section

id: components-quickstart
title: Components QuickStart
eleventyNavigation:
key: components-quickstart1x
parent: components1x
title: Components QuickStart
navigationOptions:
activeKey: components-quickstart1x
keywords:
- getting started

layout: 1x Copy Chapter

The @microsoft/fast-components library contains Web Components built on top of our standard component and design system foundation. @microsoft/fast-components expresses the FAST design language (FAST Frame).

Installation Copy Chapter

From NPM Copy Section

To install the components:

npm install --save @microsoft/fast-components

yarn add @microsoft/fast-components

To use a Web Component as a custom element in HTML, the custom element must be registered. Importing the necessary component definition into your JavaScript bundle and registering it with a DesignSystem will register the custom element with the platform. Here's how to do that for @microsoft/fast-components:

import { 
    fastButton, 
    provideFASTDesignSystem 
} from "@microsoft/fast-components";

provideFASTDesignSystem()
    .register(
        fastButton()
    );

As a shortcut, if you wish to easily register all available components, rather than registering each one, you can use the following pattern:

import { 
    allComponents, 
    provideFASTDesignSystem 
} from "@microsoft/fast-components";

provideFASTDesignSystem().register(allComponents);

:::note
When working with a tree-shaking supporting bundler such as Webpack or Rollup, you will want to import and register the individual components. This will ensure that any unused components are tree-shaken out of your builds.
:::

:::tip
Looking for a setup that integrates with a particular front-end framework or bundler? Check out our integration docs.
:::

From CDN Copy Section

A pre-bundled script that contains all APIs needed to use the components is available on CDN. You can use this script by adding type="module" to the script element and then importing from the CDN. Here's what that would look like for the FAST Web Components:

<!DOCTYPE html>
<html lang="en">
    <head>
        <script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/fast-components/dist/fast-components.min.js"></script>
    </head>
    
</html>

The markup above always references the latest release of the components. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:

<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/[email protected]/dist/fast-components.min.js"></script>

When using FAST from CDN, there is no need to register the components. The CDN script includes code that automatically sets up the design system and registers all the components.

:::note
For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
:::

Add components Copy Chapter

With the components registered, add any component to the HTML. That's it! For a comprehensive list of all elements, see the Components section.

<fast-button>Hello world</fast-button>

Sites Website Src Docs 1.X Design Systems Overview (`sites/website/src/docs/1.x/design-systems/overview.md`) Copy Section

id: overview
title: What is a Design System?
eleventyNavigation:
key: overview1x
parent: design-systems1x
title: What is a Design System?
navigationOptions:
activeKey: overview1x
keywords:

• design systems
  layout: 1x

A Design System can be generally thought of as a collection of interactive media resources that promotes brand alignment. While that definition is intentionally broad, in UI development, Design Systems manifest as component libraries surrounded by usage guidance and design principles.

How does FAST facilitate development of design systems? Copy Chapter

FAST helps by both providing a highly configurable design system that you can drop into any app and by providing a set of building blocks you can use to construct your own design system from scratch, with very little work.

A highly configurable design system Copy Chapter

FAST Frame is the name of our highly configurable design system. It's made up of a set of web components and accompanying design tokens. The visual design can be impacted in myriad ways using the exported Design Tokens, element templates and styles can be augmented or overridden, and shadow roots can be opened or closed as necessary for your application. If you’re looking to get up and running with FAST Web Components and the FAST Frame design system, start here.

Design Tokens Copy Section

Design Tokens are powerful tools that are used to express design abstractions like color, typography, spacing units, and other design-led values. FAST exposes powerful tools for creating and using Design Tokens for your Design System. FAST Frame leverages FAST's design tokens extensively. FAST Frame's use of design tokens is so extensive that you might be able to create your own design system simply by modifying the existing tokens. Of course, you can always create your own tokens and even base your tokens on compositions of existing tokens. To learn more see our documentation on design tokens.

Your own design system based on FAST components Copy Chapter

If you need more control than you can get through modifying design token values or recipes, you can wrap your styling around the foundation components. By exporting raw JavaScript Custom Element classes, @microsoft/fast-foundation handles the business-logic driving a large catalog of UI components. These Custom Element classes can be taken as-is and composed with your templates and styles to match your application or library requirements, reducing the development time and overhead of creating your own design system. For example, rather than implementing a Tree View from scratch, you can use the Foundation Tree View class and simply compose it with your own CSS to create a reusable web component as part of your own system.

Sites Website Src Docs 1.X Fast Element Getting Started (`sites/website/src/docs/1.x/fast-element/getting-started.md`) Copy Section

id: getting-started
title: Getting Started with FAST Element
eleventyNavigation:
key: getting-started1x
parent: fast-element1x
title: Getting Started with FAST Element
navigationOptions:
activeKey: getting-started1x
keywords:

• getting started
  layout: 1x

The fast-element library is a lightweight means to easily build performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework.

Installation Copy Chapter

From NPM Copy Section

To install the fast-element library, use either npm or yarn as follows:

npm install --save @microsoft/fast-element

yarn add @microsoft/fast-element

Within your JavaScript or TypeScript code, you can then import library APIs like this:

import { FASTElement } from '@microsoft/fast-element';

:::tip
Looking for a setup that integrates with a particular front-end framework or bundler? Check out our integration docs.
:::

From CDN Copy Section

A pre-bundled script that contains all APIs needed to build web components with FAST Element is available on CDN. You can use this script by adding type="module" to the script element and then importing from the CDN.

<!DOCTYPE html>
<html lang="en">
    <head>
        <script type="module">
          import { FASTElement } from "https://cdn.jsdelivr.net/npm/@microsoft/fast-element/dist/fast-element.min.js";

          // your code here
        </script>
    </head>
    
</html>

The markup above always references the latest release. When deploying to production, you will want to ship with a specific version. Here's an example of the markup for that:

<script type="module" src="https://cdn.jsdelivr.net/npm/@microsoft/[email protected]/dist/fast-element.min.js"></script>

:::note
For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
:::

:::tip
Looking for a quick guide on building components? Check out our Cheat Sheet.
:::

Sites Website Src Docs 2.X Api Fast Element.Executioncontext.Index (`sites/website/src/docs/2.x/api/fast-element.executioncontext.index.md`) Copy Section

id: "fast-element.executioncontext.index" title: "ExecutionContext.index property" layout: 2x-api eleventyNavigation: key: "api2xfast-element.executioncontext.index" parent: "api2xfast-element" title: "ExecutionContext.index property" navigationOptions: activeKey: "api2xfast-element.executioncontext.index" Copy Chapter

@microsoft/fast-element > ExecutionContext > index

ExecutionContext.index property Copy Chapter

The index of the current item within a repeat context.

Signature:

index: number;

Sites Website Src Docs 2.X Api Fast Element.Splice.Index (`sites/website/src/docs/2.x/api/fast-element.splice.index.md`) Copy Section

id: "fast-element.splice.index" title: "Splice.index property" layout: 2x-api eleventyNavigation: key: "api2xfast-element.splice.index" parent: "api2xfast-element" title: "Splice.index property" navigationOptions: activeKey: "api2xfast-element.splice.index" Copy Chapter

@microsoft/fast-element > Splice > index

Splice.index property Copy Chapter

Signature:

index: number;

Sites Website Src Docs 2.X Api Index (`sites/website/src/docs/2.x/api/index.md`) Copy Section

id: "index" title: "API Reference" layout: 2x eleventyNavigation: key: "api2xapi2x" parent: "api2x" title: "@microsoft/fast-element" navigationOptions: activeKey: "api2xapi2x" Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Sites Website Src Docs 3.X Api Fast Element.Defaultexecutioncontext.Index (`sites/website/src/docs/3.x/api/fast-element.defaultexecutioncontext.index.md`) Copy Section

id: "fast-element.defaultexecutioncontext.index" title: "DefaultExecutionContext.index property" layout: 3x-api eleventyNavigation: key: "api3xfast-element.defaultexecutioncontext.index" parent: "api3xfast-element" title: "DefaultExecutionContext.index property" navigationOptions: activeKey: "api3xfast-element.defaultexecutioncontext.index" Copy Chapter

@microsoft/fast-element > DefaultExecutionContext > index

DefaultExecutionContext.index property Copy Chapter

The index of the current item within a repeat context.

Signature:

index: number;

Sites Website Src Docs 3.X Api Fast Element.Executioncontext.Index (`sites/website/src/docs/3.x/api/fast-element.executioncontext.index.md`) Copy Section

id: "fast-element.executioncontext.index" title: "ExecutionContext.index property" layout: 3x-api eleventyNavigation: key: "api3xfast-element.executioncontext.index" parent: "api3xfast-element" title: "ExecutionContext.index property" navigationOptions: activeKey: "api3xfast-element.executioncontext.index" Copy Chapter

@microsoft/fast-element > ExecutionContext > index

ExecutionContext.index property Copy Chapter

The index of the current item within a repeat context.

Signature:

index: number;

Sites Website Src Docs 3.X Api Fast Element.Splice.Index (`sites/website/src/docs/3.x/api/fast-element.splice.index.md`) Copy Section

id: "fast-element.splice.index" title: "Splice.index property" layout: 3x-api eleventyNavigation: key: "api3xfast-element.splice.index" parent: "api3xfast-element" title: "Splice.index property" navigationOptions: activeKey: "api3xfast-element.splice.index" Copy Chapter

@microsoft/fast-element > Splice > index

Splice.index property Copy Chapter

Signature:

index: number;

Sites Website Src Docs 3.X Api Index (`sites/website/src/docs/3.x/api/index.md`) Copy Section

id: "index" title: "API Reference" layout: 3x eleventyNavigation: key: "api3xapi3x" parent: "api3x" title: "@microsoft/fast-element" navigationOptions: activeKey: "api3xapi3x" Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Sites Website Src Docs 3.X Declarative Templates Overview (`sites/website/src/docs/3.x/declarative-templates/overview.md`) Copy Section

id: declarative-templates-overview
title: Declarative HTML Overview
layout: 3x
eleventyNavigation:
key: declarative-templates-overview3x
parent: declarative-templates3x
title: Overview
navigationOptions:
activeKey: declarative-templates-overview3x
keywords:

• declarative
• html
• templates
• web components
• f-template

{% raw %}

Declarative HTML Overview

FAST Element provides two ways to author web component templates:

1. Imperative — JavaScript tagged template literals using the html function.
2. Declarative — Plain HTML <f-template> elements parsed at runtime.

The declarative model moves template authoring from JavaScript into HTML. Because templates are expressed as standard markup, they can be rendered by any server-side technology without running the FAST Element client runtime — enabling true stack-agnostic server-side rendering. Hydration and client rendering still run in the browser Window.

When to Use Declarative Templates Copy Chapter

Choose declarative HTML when:

• You want server-rendered initial HTML that hydrates on the client.
• Your rendering pipeline does not run JavaScript (e.g. Rust, Go, or .NET servers).
• You prefer authoring templates in HTML files rather than JavaScript modules.
• You need the same template to be consumable by both a build tool and the browser.

The imperative html tagged template remains the right choice for purely client-side applications where templates are authored alongside component logic in TypeScript.

Hello World Copy Chapter

A declarative FAST component requires three pieces: a JavaScript class, an <f-template> element, and a host element in the page.

1. Define the component class (main.ts):

import { attr, FASTElement } from "@microsoft/fast-element";
import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";

class HelloWorld extends FASTElement {
    @attr greeting: string = "Hello";
}

HelloWorld.define({
    name: "hello-world",
    template: declarativeTemplate(),
});

2. Write the template (templates.html):

<f-template name="hello-world">
    <template>
        <p>{{greeting}}, world!</p>
    </template>
</f-template>

3. Use the element in your page (index.html):

<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"></head>
<body>
    <hello-world greeting="Hi"></hello-world>
    <script type="module" src="./main.ts"></script>
</body>
</html>

When the page loads, declarativeTemplate() automatically defines FAST's internal <f-template> publisher in the relevant registry, finds the <f-template name="hello-world"> element, parses its inner <template>, and resolves the template for the hello-world definition. If you call enableHydration() before elements connect, matching pre-rendered content is hydrated; otherwise the component renders client-side. Reactive bindings keep the DOM in sync with property changes.

How It Works Copy Chapter

The declarative pipeline follows these steps:

1. Define — The component class is registered with template: declarativeTemplate(), which tells FAST to wait for a matching <f-template> element and automatically defines the <f-template> custom element in the registry.
2. Parse — When <f-template> connects to the DOM, TemplateParser converts the declarative markup into the same internal ViewTemplate that the imperative html tag produces.
3. Resolve — The template is resolved through the bridge and assigned to the element definition before define() completes.
4. Render or hydrate — If enableHydration() was called and the page contains pre-rendered content, existing DOM nodes are reused. Otherwise the template renders client-side.

Declarative vs. Imperative Syntax Copy Chapter

The same component can be expressed either way. Here is a side-by-side comparison:

Imperative:

import { attr, FASTElement, html } from "@microsoft/fast-element";

const template = html<NameTag>`
    <h3>${x => x.greeting}</h3>
`;

class NameTag extends FASTElement {
    @attr greeting: string = "Hello";
}

NameTag.define({ name: "name-tag", template });

Declarative:

import { attr, FASTElement } from "@microsoft/fast-element";
import { declarativeTemplate } from "@microsoft/fast-element/declarative.js";

class NameTag extends FASTElement {
    @attr greeting: string = "Hello";
}

NameTag.define({
    name: "name-tag",
    template: declarativeTemplate(),
});

<f-template name="name-tag">
    <template>
        <h3>{{greeting}}</h3>
    </template>
</f-template>

Both produce the same runtime behavior. The declarative version separates the template into HTML, making it available for server-side rendering without JavaScript.

Next Steps Copy Chapter

• Writing f-templates — Template syntax, bindings, directives, and expressions.
• Defining Elements — Component registration and extension configuration.
• Server-Side Rendering — Rendering templates on the server and hydrating on the client.

{% endraw %}

Sites Website Src Docs 2.X Api Fast Element Context Index (`sites/website/src/docs/2.x/api/fast-element/context/index.md`) Copy Section

id: "index" title: "API Reference" layout: 2x eleventyNavigation: key: "api2x@microsoft/fast-element/context.js2x" parent: "api2x" title: "@microsoft/fast-element/context.js" navigationOptions: activeKey: "api2x@microsoft/fast-element/context.js2x" Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Sites Website Src Docs 2.X Api Fast Element Di Index (`sites/website/src/docs/2.x/api/fast-element/di/index.md`) Copy Section

id: "index" title: "API Reference" layout: 2x eleventyNavigation: key: "api2x@microsoft/fast-element/di.js2x" parent: "api2x" title: "@microsoft/fast-element/di.js" navigationOptions: activeKey: "api2x@microsoft/fast-element/di.js2x" Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Sites Website Src Docs 3.X Api Fast Element Context Index (`sites/website/src/docs/3.x/api/fast-element/context/index.md`) Copy Section

id: "index" title: "API Reference" layout: 3x eleventyNavigation: key: "api3x@microsoft/fast-element/context.js3x" parent: "api3x" title: "@microsoft/fast-element/context.js" navigationOptions: activeKey: "api3x@microsoft/fast-element/context.js3x" Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Sites Website Src Docs 3.X Api Fast Element Declarative Index (`sites/website/src/docs/3.x/api/fast-element/declarative/index.md`) Copy Section

id: "index" title: "API Reference" layout: 3x eleventyNavigation: key: "api3x@microsoft/fast-element/declarative.js3x" parent: "api3x" title: "@microsoft/fast-element/declarative.js" navigationOptions: activeKey: "api3x@microsoft/fast-element/declarative.js3x" Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Sites Website Src Docs 3.X Api Fast Element Di Index (`sites/website/src/docs/3.x/api/fast-element/di/index.md`) Copy Section

id: "index" title: "API Reference" layout: 3x eleventyNavigation: key: "api3x@microsoft/fast-element/di.js3x" parent: "api3x" title: "@microsoft/fast-element/di.js" navigationOptions: activeKey: "api3x@microsoft/fast-element/di.js3x" Copy Chapter

Home

API Reference Copy Chapter

Packages Copy Chapter

Packages Fast Element Docs ACKNOWLEDGEMENTS (`packages/fast-element/docs/ACKNOWLEDGEMENTS.md`) Copy Section

Acknowledgements

There are many great open source projects that have inspired us and enabled us to build FAST. Below are a few that stand out.

• .NET - Many thanks to the .NET team for sharing their policies and practices upon which our issue management and release planning docs and practices were based.
• asap - An awesome, time-tested async task queue implementation that heavily inspired our DOM update system.
• Aurelia 1 and Aurelia 2 - Various details of Aurelia 2's decorator and metadata model inspired us in the design of fast-element. Additionally, Aurelia 1's mechanisms for array observation, binding, and template compilation also guided us in our work.
• faastjs - A project with a similar name but a very different purpose. Their API documentation approach leveraging api-extractor was a huge help to us.
• Knockout - One of the first JavaScript libraries (if not the first) to implement an observer system. The original techniques for observables and computed observables have influenced many libraries over the years. Re-interpreting these ideas in terms of modern JavaScript and DOM has helped us to build a powerful and robust system.
• lit-html - One of the first libraries to leverage standard JavaScript tagged template literals for HTML templates. We were inspired by this technique and wanted to explore whether it could be combined with our idea of arrow function binding expressions.
• Polymer - One of the first libraries (if not the first) to embrace Web Components.
• Vue - We liked the terseness of the : and @ syntax in templates, so we adapted it along with some modifications in our templates.

Packages Fast Element Docs Api Report.Api (`packages/fast-element/docs/api-report.api.md`) Copy Section

API Report File for "@microsoft/fast-element" Copy Chapter

Do not edit this file. It is a report generated by API Extractor.

/* Detailed source-code truncated for AI context efficiency. */

Packages Fast Element Docs Template Bindings (`packages/fast-element/docs/template-bindings.md`) Copy Section

FAST Element Template Bindings Architecture

This document explains how the FAST Element html tagged template system stores bindings, applies them to DOM elements, triggers updates on data changes, and handles HTML-specific behaviors like event listeners.

Overview Copy Chapter

The template binding pipeline has five major stages:

1. Template Authoring – The html tagged template collects binding expressions and builds placeholder-marked HTML.
2. Compilation – The compiler parses the placeholder HTML into a DocumentFragment, walks the DOM tree, and records where each binding targets.
3. View Creation – The compiled result clones the fragment and creates a targets object that maps each binding to its DOM node.
4. Binding (first render) – Each factory creates a behavior that attaches to its target node: adding event listeners, setting attributes, or observing expressions.
5. Reactive Updates – When observed data changes, one-way binding observers notify their directive, which re-evaluates the expression and pushes the new value to the DOM through a "sink" function.

Mermaid Diagrams Copy Chapter

1. Template Creation & Storage Copy Section

This diagram shows how the html tagged template literal processes interpolated values and stores them as factories keyed by unique IDs.

flowchart TD
    A["html`<div class='${expr}'>${text}</div>`"] --> B["ViewTemplate.create(strings, values)"]
    B --> C{"For each interpolated value"}
    C -->|Function| D["Wrap in oneWay() → HTMLBindingDirective"]
    C -->|Binding instance| E["Wrap in HTMLBindingDirective"]
    C -->|HTMLDirective| F["Use directly"]
    C -->|Static value| G["Wrap in oneTime() → HTMLBindingDirective"]
    D --> H["directive.createHTML(add)"]
    E --> H
    F --> H
    G --> H
    H --> I["add(factory) assigns unique ID"]
    I --> J["factories Record<string, ViewBehaviorFactory>"]
    I --> K["Returns placeholder marker in HTML string"]
    K --> L["Aspect Detection via lastAttributeNameRegex"]
    L -->|In attribute context| M["HTMLDirective.assignAspect(directive, attrName)"]
    L -->|In text content| N["aspectType = DOMAspect.content"]
    M --> O{"Attribute prefix"}
    O -->|No prefix| P["DOMAspect.attribute"]
    O -->|: prefix| Q["DOMAspect.property"]
    O -->|? prefix| R["DOMAspect.booleanAttribute"]
    O -->|"@" prefix| S["DOMAspect.event"]
    O -->|:classList| T["DOMAspect.tokenList"]
    J --> U["new ViewTemplate(html, factories)"]

2. Compilation – Walking the DOM & Storing Target Locations Copy Section

The compiler transforms the placeholder-laden HTML into a DocumentFragment and builds a prototype with lazy property descriptors that navigate to target nodes by child index.

/* Detailed source-code truncated for AI context efficiency. */

3. View Creation – Cloning the Fragment & Resolving Targets Copy Section

flowchart TD
    A["compilationResult.createView(hostBindingTarget?)"] --> B["fragment.cloneNode(true) → new DocumentFragment"]
    B --> C["targets = Object.create(proto)"]
    C --> D["targets.r = fragment (root)"]
    D --> E["targets.h = hostBindingTarget (host element)"]
    E --> F{"For each registered nodeId"}
    F --> G["Access targets[nodeId] — triggers lazy getter chain"]
    G --> H["Getter resolves: this[parentId].childNodes[childIndex]"]
    H --> I["Caches result in targets._nodeId field"]
    I --> J["new HTMLView(fragment, factories, targets)"]

    subgraph "HTMLView Structure"
        K["fragment: DocumentFragment with cloned DOM"]
        L["factories: CompiledViewBehaviorFactory[]"]
        M["targets: ViewBehaviorTargets {nodeId → Node}"]
        N["firstChild / lastChild: boundary nodes"]
        O["source: null (until bound)"]
        P["behaviors: null (created on first bind)"]
    end
    J --> K
    J --> L
    J --> M

4. Binding – Attaching Behaviors to DOM Nodes Copy Section

flowchart TD
    A["view.bind(source)"] --> B{"First bind?"}
    B -->|Yes| C["Set view.source = source"]
    C --> D["Create behaviors array"]
    D --> E{"For each factory"}
    E --> F["factory.createBehavior()"]
    F --> G["Select sink from sinkLookup based on aspectType"]
    G --> H["Wrap sink through policy.protect()"]
    H --> I["behavior.bind(controller/view)"]

    B -->|Subsequent| J["Unbind previous, set new source"]
    J --> K["Re-bind existing behaviors"]

    I --> L{"aspectType?"}

    L -->|DOMAspect.event| M["Store controller ref on target node"]
    M --> N["target.addEventListener(targetAspect, directive, options)"]
    N --> O["directive IS the EventListener via handleEvent()"]

    L -->|DOMAspect.content| P["Register unbind handler"]
    P --> Q["Create observer via dataBinding.createObserver()"]

    L -->|attribute / property / etc.| Q

    Q --> R["observer.bind(controller) → evaluates expression"]
    R --> S["updateTarget(target, aspect, value, controller)"]

    subgraph "Sink Functions (sinkLookup)"
        S1["attribute → DOM.setAttribute(target, name, value)"]
        S2["booleanAttribute → DOM.setBooleanAttribute(target, name, value)"]
        S3["property → target[name] = value"]
        S4["content → updateContent() — manages text or composed views"]
        S5["tokenList → updateTokenList() — classList with versioning"]
        S6["event → no-op (handled via addEventListener)"]
    end

5. Reactive Update Cycle – Change Detection & DOM Updates Copy Section

sequenceDiagram
    participant Source as Data Source
    participant Observable as Observable System
    participant Observer as ExpressionObserver (OneWayBinding)
    participant Directive as HTMLBindingDirective
    participant Sink as UpdateTarget (sink fn)
    participant DOM as Target DOM Node

    Note over Source,DOM: Initial Bind
    Directive->>Observer: dataBinding.createObserver(directive, directive)
    Observer->>Source: Evaluate expression (tracks property access)
    Source-->>Observer: Return value + record dependencies
    Directive->>Sink: updateTarget(target, aspect, value, controller)
    Sink->>DOM: Apply value (setAttribute, textContent, etc.)

    Note over Source,DOM: Data Change
    Source->>Observable: Property setter triggered
    Observable->>Observer: Notify subscriber of change
    Observer->>Directive: handleChange(binding, observer)
    Directive->>Observer: observer.bind(controller) — re-evaluate
    Observer->>Source: Re-evaluate expression
    Source-->>Observer: Return new value
    Directive->>Sink: updateTarget(target, aspect, newValue, controller)
    Sink->>DOM: Update DOM with new value

6. Event Handling – Click Events and Other DOM Events Copy Section

sequenceDiagram
    participant User as User Interaction
    participant DOM as Target DOM Element
    participant Directive as HTMLBindingDirective (EventListener)
    participant Context as ExecutionContext
    participant Binding as dataBinding.evaluate()
    participant Source as Component Source

    Note over DOM: During bind: target.addEventListener("click", directive)
    Note over DOM: directive stores controller ref on target[data]

    User->>DOM: Click event fires
    DOM->>Directive: handleEvent(event)
    Directive->>DOM: Read controller from event.currentTarget[data]
    Directive->>Directive: Check controller.isBound
    Directive->>Context: ExecutionContext.setEvent(event)
    Directive->>Binding: evaluate(controller.source, controller.context)
    Binding->>Source: Execute handler: (s, c) => s.handleClick(c.event)
    Source-->>Binding: Return result
    Binding-->>Directive: Return result
    alt result !== true
        Directive->>DOM: event.preventDefault()
    end
    Directive->>Context: ExecutionContext.setEvent(null)

7. Content Binding – Template Composition Copy Section

When a binding expression returns a ContentTemplate (e.g., another ViewTemplate), the content update sink composes a child view into the DOM.

flowchart TD
    A["updateContent(target, aspect, value, controller)"] --> B{"value is null/undefined?"}
    B -->|Yes| C["Treat as empty string"]
    B -->|No| D{"value.create exists? (ContentTemplate)"}

    D -->|Yes — Template| E["Clear target.textContent"]
    E --> F{"Existing view on target.$fastView?"}
    F -->|No| G["view = value.create()"]
    F -->|Yes, same template| H["Reuse existing view"]
    F -->|Yes, different template| I["Remove old view, create new"]
    G --> J["view.bind(source, context)"]
    I --> J
    J --> K["view.insertBefore(target)"]
    K --> L["Cache: target.$fastView = view, target.$fastTemplate = value"]

    D -->|No — Primitive| M{"Existing composed view?"}
    M -->|Yes| N["view.remove(), view.unbind()"]
    N --> O["target.textContent = value"]
    M -->|No| O

Key Data Structures Copy Chapter

Binding Type Summary Copy Chapter

Hydration: Attaching Bindings to Server-Rendered DOM Copy Chapter

When a page is server-side rendered (SSR) with Declarative Shadow DOM, the HTML arrives in the browser fully formed. Instead of creating new DOM nodes, FAST's hydration system reuses the existing DOM and attaches reactive bindings to it. This section explains how hydration markers in the SSR output guide the client-side binding process.

Enabling Hydration Copy Section

Hydration is an opt-in feature. Calling enableHydration() patches
ViewTemplate.prototype with:

1. A Hydratable symbol — marks the template as hydration-capable (checked via isHydratable()).
2. A hydrate(firstChild, lastChild, hostBindingTarget?) method — creates a HydrationView instead of an HTMLView.

import { enableHydration } from "@microsoft/fast-element/hydration.js";

enableHydration();

Hydration Marker Format Copy Section

The SSR renderer embeds comment nodes and data attributes into the HTML to mark where bindings should attach. These markers encode the factory index (position in the compiled factories array) so the client can map each marker back to its corresponding ViewBehaviorFactory.

Attribute Binding Markers

Elements with attribute/property/event bindings receive a data-fe attribute with the binding count:

<div data-fe="2">server-rendered content</div>

The attribute marker format is:

Content Binding Markers

Text/template content bindings are wrapped in paired data-free comment nodes (matched by string equality, paired by balanced depth counting):

Hello, World!

Repeat Directive Markers

Each repeated item is bracketed by data-free repeat markers:

<li>First item</li>


<li>Second item</li>

Element Boundary Markers

Nested custom elements that also need hydration are demarcated so the parent's walker can skip over them:

<child-element>
  <template shadowrootmode="open">...child shadow DOM...</template>
</child-element>

Hydration Binding Flow Copy Section

hydration/traversal.ts owns pointer navigation and its live Range fallback.
hydration/target-builder.ts consumes that traversal to map factories, keeping
direct native marker reads inline. HydrationView uses the same range utility
when producing diagnostic fragments, without coupling it to target discovery.

enableHydration() replaces the small core components/element-registration.ts
strategy with hydration/attribute-observation.ts. Client-only FASTElement
bundles do not include observation tracking. Immediately before FAST's platform
registration, tracking records only a boolean proving that data-fe is
unobserved, after extensions and asynchronous template resolution. The proof is
available during synchronous upgrades and restored if registration fails.
Earlier untracked registrations remain conservative; calling enableHydration()
again does not reset existing proof. Hydration never reconstructs the platform
snapshot by rereading constructor.observedAttributes.

For a known unobserved data-fe attribute and native attribute methods, removal
cannot invoke an attribute-change callback, so pointers remain active.
Registration/lifecycle accessors, custom attribute iterators, unknown registry
wrappers, customized built-ins, and overridden attribute methods remain
conservative. Legacy/custom marker cleanup still captures live boundaries from
the outset. Marker removal is not deferred and callback order is unchanged.

/* Detailed source-code truncated for AI context efficiency. */

HydrationView vs HTMLView Copy Section

flowchart LR
    subgraph "HTMLView (client-rendered)"
        A1["Compiler produces DocumentFragment"] --> A2["fragment.cloneNode(true)"]
        A2 --> A3["Resolve targets via prototype getter chain"]
        A3 --> A4["Create behaviors & bind"]
    end

    subgraph "HydrationView (server-rendered)"
        B1["DOM already exists in shadow root"] --> B2["Bounded pointer DFS scans markers; live Range fallback when needed"]
        B2 --> B3["buildViewBindingTargets maps markers → nodes"]
        B3 --> B4["Create behaviors & bind to existing nodes"]
        B4 --> B5["Marker comments cleared (data set to empty string)"]
    end

Content Binding Hydration Copy Section

When HTMLBindingDirective.bind() runs during hydration and the binding returns a ContentTemplate, the updateContent sink checks for pre-rendered boundaries:

sequenceDiagram
    participant Directive as HTMLBindingDirective
    participant Controller as HydrationView (controller)
    participant Sink as updateContent()
    participant Template as ContentTemplate

    Directive->>Controller: bind(controller)
    Note over Directive: aspectType = DOMAspect.content
    Directive->>Sink: updateTarget(target, aspect, value, controller)
    Sink->>Sink: value is ContentTemplate?

    alt Hydrating & boundaries exist
        Sink->>Controller: Check bindingViewBoundaries[targetNodeId]
        Controller-->>Sink: { first: Node, last: Node }
        Sink->>Template: value.hydrate(first, last)
        Template-->>Sink: HydrationView (reuses existing nodes)
        Sink->>Sink: view.bind(source, context) — attaches to pre-rendered DOM
    else Already hydrated or no boundaries
        Sink->>Template: value.create()
        Template-->>Sink: HTMLView (creates new nodes)
        Sink->>Sink: view.bind + view.insertBefore
    end

Repeat Directive Hydration Copy Section

The repeat directive scans forward from its own content boundary to its
location, pairing top-level ranges with a stack. This avoids reverse collection
and rescanning prefixes belonging to earlier adjacent repeats. Nested markers
remain untouched until child views hydrate. Both unmatched starts and unmatched
ends throw before repeat markers are cleared.

The read-only collectHydrationRepeatRanges() helper in
hydration/repeat-ranges.ts owns this discovery and validation. RepeatBehavior
supplies its own binding boundaries, then clears top-level markers and hydrates,
creates, or removes views. The discovery helper does not alter marker data or
bind views.

flowchart TD
    A["RepeatBehavior.bind(controller)"] --> B{"isHydratable(template) && hydrating?"}
    B -->|Yes| C["hydrateViews(template)"]
    B -->|No| D["refreshAllViews() — normal client path"]

    C --> E["Allocate views array sized to items.length"]
    E --> F["Scan bindingViewBoundaries[targetNodeId].first through location"]
    F --> G{"Repeat marker?"}
    G -->|Start| H["Push start marker"]
    G -->|End| I["Pop start; throw if absent"]
    I --> J{"Stack empty?"}
    J -->|Yes| K["Append top-level range in item order"]
    J -->|No| F
    H --> F
    K --> F
    G -->|Other node| F
    F -->|Reached location| L["Throw if stack nonempty; otherwise clear top-level markers"]
    L --> M["Hydrate overlapping SSR/client ranges in order"]
    M --> N["Create missing client views and remove excess server ranges"]

    subgraph "Result"
        S["Each array item mapped to a HydrationView"]
        T["Views reuse server-rendered DOM between markers"]
        U["Markers cleared to empty strings (invisible in DOM)"]
    end

Hydration CPU regression coverage Copy Section

src/hydration/hydration-performance.pw.spec.ts instruments Range/TreeWalker
creation and native factory-index array allocation across 500 sibling-bounded
views. Those counters must all be zero on the ordinary native path. It also
asserts exact linear repeat predicate visits (four starts and two ends per
four-comment nested item), scope isolation from earlier siblings, nested marker
preservation, malformed-marker diagnostics, installed markers_v2, empty items,
and missing/excess reconciliation. Existing target-builder tests compare live
endpoint mutations with the legacy Range walker. The declarative repeat fixture
checks SSR node identity, three nested repeat levels, an empty inner list, and an
adjacent repeat before exercising reactive updates. The co-located
src/hydration/repeat-ranges.pw.spec.ts also verifies that successful discovery
leaves native and legacy marker data unchanged and excludes adjacent ranges.

src/hydration/native-marker-cleanup.pw.spec.ts exercises a 1,000-record,
three-repeat-level workload with 20 adjacent prefix items: 4,021 FAST elements,
4,020 native attribute markers, and 8,041 hydrated views. Range/TreeWalker setup,
comparePoint, and intersectsNode counts are all zero; all 7,020 SSR descendant
elements retain their identity. Mutation fixtures require the fallback and
verify immediate insertion/removal, endpoint moves, unstable observation
metadata, method accessors, customized built-ins, and legacy/custom strategies.
Registration-order cases cover disabled tracking, enabling after registration,
repeated enablement after observation changes, and platform registration deferred
until after asynchronous template resolution.
The declarative repeat fixture includes bound FAST child elements, checks zero
live traversal setup, and exercises reactive updates after hydration.

Run focused correctness coverage from the monorepo root:

npm exec -w @microsoft/fast-element -- playwright test src/hydration/target-builder.pw.spec.ts src/hydration/hydration-performance.pw.spec.ts src/hydration/native-marker-cleanup.pw.spec.ts src/hydration/repeat-ranges.pw.spec.ts src/templating/repeat.pw.spec.ts --project=chromium

CPU timings live separately in src/hydration/hydration-benchmark.pw.spec.ts
and are opt-in rather than flaky wall-clock CI gates:

FAST_HYDRATION_BENCHMARK=1 npm exec -w @microsoft/fast-element -- playwright test src/hydration/hydration-benchmark.pw.spec.ts --project=chromium --retries=0

The workloads measure 4,000 marker-free sibling views, 4,000 native
attribute/content marker groups, 4,000 nested repeat ranges with stubbed child
hydration, 20 adjacent repeats with 200 flat item ranges each, and a combined
1,000-record page with three repeat levels, 4,000 minimal native custom elements,
and 8,001 hydrated views. Setup, custom-element registration, and template
construction are outside the timed interval; repeat workloads include bind and unbind. Each
workload has one warm-up and ten recorded samples, each in a fresh document so
live Ranges from earlier samples cannot amplify later DOM mutation costs.
Compare the same test on the base and changed revisions on the same browser and
machine. To attribute improvements, also compare traversal-only, native-only,
and repeat-only source variants in an isolated worktree, reversing variant order
for a second pass. The combined workload includes conservative live-Range
fallbacks for custom-element attribute cleanup, not just ordinary element views.
These microbenchmarks time template hydration, not the issue's application
registration or hydration-completion tracking, and should not be presented as
that application's hydration timings.

The separate native FAST workload times bind/unbind for the 4,021-element /
8,041-view case above. Setup and registration are excluded, identity and marker
removal are verified after every sample, and the same fresh-document sampling
rules apply. Use this workload to compare the known-unobserved cleanup path;
the original combined workload intentionally registers ordinary custom elements
outside FAST and therefore retains its conservative fallback.

Hydration Stage Lifecycle Copy Section

stateDiagram-v2
    [*] --> unhydrated: HydrationView created

    unhydrated --> hydrating: bind() called
    note right of hydrating
        buildViewBindingTargets() scans DOM
        Markers parsed, targets resolved
        Behaviors created and bound
        Attribute bindings skip DOM update
        (server already set correct values)
    end note

    hydrating --> hydrated: All behaviors bound
    note right of hydrated
        Subsequent bind() calls
        behave like normal HTMLView rebind
        (re-evaluate expressions, update DOM)
    end note

    hydrated --> hydrated: rebind with new source

During the hydrating stage, attribute and boolean-attribute bindings skip their initial DOM update (the server already rendered the correct value). This avoids unnecessary DOM writes during hydration:

// In HTMLBindingDirective.bind(), during hydration:
if (isHydrating && (this.aspectType === DOMAspect.attribute ||
                    this.aspectType === DOMAspect.booleanAttribute)) {
    observer.bind(controller);  // Set up observation only
    break;                      // Skip updateTarget — server value is current
}

Error Handling Copy Section

When the server-rendered DOM doesn't match the client template, hydration throws descriptive errors:

These errors typically indicate a mismatch between the server-rendered HTML and the client-side template definition.

By default, both errors emit a minimal one-line message that points at the opt-in hydrationDebugger(). Install the debugger from @microsoft/fast-element/hydration.js and pass it to enableHydration to swap in the rich format:

import { enableHydration, hydrationDebugger } from "@microsoft/fast-element/hydration.js";

enableHydration({ debugger: hydrationDebugger() });

With the debugger installed, both errors format their message as:

Hydration mismatch in <host-element>.
  Expected: <tag> with <aspect> binding   (or a structural description)
  Received: <SSR HTML snippet>

and expose the same information programmatically through the expected and received fields so tooling can read the structured description without parsing the message string. Keeping the debugger out of the import graph saves ~0.5 KB on the production hydration bundle.

Packages Fast Router Docs Api Report.Api (`packages/fast-router/docs/api-report.api.md`) Copy Section

API Report File for "@microsoft/fast-router" Copy Chapter

Do not edit this file. It is a report generated by API Extractor.

/* Detailed source-code truncated for AI context efficiency. */

Packages Fast Build Docs Migration Plugin Integrations (`packages/fast-build/docs/migration/plugin-integrations.md`) Copy Section

Migrating plugin integration pipelines

Structured errors Copy Chapter

WASM failures now throw JavaScript Error objects rather than strings. Read
error.message for the previous human-readable text; String(error) now has the
standard Error: prefix. Replace message matching with stable error.code
checks. Both WASM declaration modules export a FastBuildError interface extending
Error; it is a type only, not an exported constructor.

Optional line/column are one-based UTF-16 coordinates, and length is a UTF-16
error-token highlight length. CRLF is one break; lone CR/LF also break lines.
Entry and conversion coordinates refer to the complete supplied HTML. A named
custom-element render failure instead refers to its separately supplied content.
Use templateName to select that source, rather than attaching its coordinates
to the entry or to a full file from which content was extracted. Older metadata
does not carry enough provenance to reconstruct those full-file positions.
Do not fabricate HTML locations when these fields are absent (JSON/options,
missing sources, filesystem errors, or separate CSS).

Native Rust RenderError and ConvertError expose code(), location() returning
an optional ErrorLocation, template_name(), and kind(). Source-annotated
validation errors may use the new Located variant; match error.kind() to
inspect the underlying variant. Context fields now use boxed ErrorContext
instead of String; use context.to_string() to read the unchanged snippet and
String::into() when constructing a context without source provenance.
Update exhaustive enum matches for Located. These are intentional pre-1.0
native API changes. Successful rendering/conversion, warnings, missing-state
behavior, and permissive parse_f_templates parsing are unchanged.

Attribute output changes Copy Chapter

Missing and explicit null bindings now omit the entire attribute, including
mixed literal/binding values. To intentionally keep href="", provide ""
instead of null. JSON booleans on known HTML boolean attributes use presence:
false omits disabled, true emits it. ARIA/ordinary attribute booleans remain
textual. Use FAST's ?name syntax for matching client-side truthy/falsy behavior.
Author bindings resolving to absence suppress matching template-host defaults.
Remove wrapper regular expressions that strip empty values: they would erase
intentional empty strings. Hydration slot counts remain unchanged.

Typed converter output Copy Chapter

The default output remains unchanged. Opt into typed: true (or --typed)
for explicit ElementViewTemplate<TSource> / ElementStyles annotations and
type-only imports, then remove wrapper string replacements. Supply
type_source/--type-source when strict source-property checking is required.
Rust ConvertOptions struct literals must include the new typed field or
use ..ConvertOptions::default().
The pre-1.0 native error enums also gain integration-related variants; update
exhaustive RenderError / ConvertError matches accordingly.

Caller-owned host markup Copy Chapter

Replace throwaway-host rendering and substring extraction with
render_shadow_root (WASM) or render_shadow_root_*_with_locator (Rust).
Pass resolved component state and insert the returned complete DSD <template>
into the host you own. The fragment does not include host/default attributes
or light-DOM children.

Persisted template metadata Copy Chapter

parse_f_templates keeps its JSON array shape and existing fields, adding
per-record formatVersion: 1 and bindings. Preserve these fields when
persisting or constructing a keyed map. Unsupported/malformed explicit versions
now fail before rendering. Unversioned legacy maps remain supported, but cannot
receive stale-version protection. Regenerate metadata on format changes rather
than rewriting a version number onto incompatible data.

Bindings describe names, expression kinds, paths, and repeat scopes. Unknown
types and state optionality are explicitly null, not inferred declarations.
Repeat collections alone have a known array requirement. Complex/client
references are lexical descriptions; metadata is not a full state schema or
syntax-validation certificate. Use application declarations for definitive
type/requiredness checks.

Each newly parsed binding now includes an authored span with half-open start
and end positions in the complete input string. Offsets are zero-based UTF-16;
lines and UTF-16 columns are one-based. Use the original input, not the returned
trimmed content, when slicing or attaching diagnostics. The range covers the
trimmed expression without braces; repeat bindings locate only the iterable.
CRLF counts as one line break and two offset units; lone CR and LF each count
as a line break. Raw attribute entities are not decoded.

Format version 1 is unchanged, and renderers still accept older records without
spans. Regenerate persisted metadata to obtain authored locations; preserve spans
when mapping or serializing records. Native BindingMetadata struct literals
must now supply the public span: SourceSpan field; prefer parse_f_templates
to constructing descriptive metadata manually. Generated WASM declarations expose
TemplateSourceSpan and TemplateSourcePosition.

Packages Fast Element Docs Architecture Fastelement (`packages/fast-element/docs/architecture/fastelement.md`) Copy Section

FASTElement

The FASTElement is our extension of the HTMLElement. As such it leverages the lifecycles but also requires additional setup before before the class constructor or the connectedCallback method is executed which are explained in the overview. This document explains specifically what FASTElement leverages inside the HTMLElements lifecycle hooks.

For an explanation into HTMLElement lifecycle hooks refer to the MDN documentation.

Because FASTElement extends HTMLElement, it is a browser Window runtime
API. It is not intended to execute in workers, server-side JavaScript runtimes,
or other non-window hosts where custom element lifecycle callbacks and animation
frame scheduling are unavailable.

A Custom Element is Detected by the Browser Copy Chapter

Because the FASTElement is an extension of the HTMLElement, it makes use of the same lifecycle hooks and extends them with $fastController. It also initializes using another class ElementController, the methods this are called during the custom elements native constructor, connectedCallback, disconnectedCallback, and attributeChangedCallback lifecycle hooks.

🔄 **Lifecycle**: Initialization Copy Section

flowchart TD
    A[A <code>FASTElement</code> web component is added to the <code>DOM</code>] --> B
    B[<code>FASTElement</code> initializes the <code>ElementController.forCustomElement</code> passing the Custom Element instance] --> C
    B --> F[Observables applied to the <code>FASTElement</code> are updated on the FAST global without values]
    C{Is an <code>ElementController</code> available?}
    C --> |yes|E
    C --> |no|D
    D[Initialize a new <code>ElementController</code> referred to as setting an element controller strategy]
    D --> F
    E[<code>ElementController</code> captures the Custom Element instance and the definition and attaches them to the <code>$fastController</code> which is then attached to the instance]

🔄 **Lifecycle**: Component is connected Copy Section

flowchart TD
    A[browser <code>HTMLElement</code>'s <code>connectedCallback</code> is called] --> B
    B[<code>this.$fastController.connect</code> in FASTElement is called] --> C
    B --> D
    B --> E
    B --> F
    C[bind observables by capturing public own Custom Element properties and setting those values through the matching accessors]
    D[connect behaviors by call the <code>connectedCallback</code> on all behaviors]
    E[render template, execute an <code>ElementViewTemplate</code>'s render method]
    F[add styles either as an appended <code>StyleElement</code> node or an <code>adoptedStylesheet</code> which may include and attach behaviors]

Render Template

The rendering of the template on the ElementController is by the renderTemplate method which is called during the ElementController.connect method which is triggered by HTMLElements connectedCallback lifecycle.

The renderTemplate identifies the Custom Element, and the shadow root associated with the Custom Element. This then places a rendering of the template (an ElementView) onto the internal view of the controller. When creating the ElementView/HTMLView using the ViewTemplate.render, the Compiler.compile() method identifies a DocumentFragment either by using an existing <template> tag, or creating one to wrap the contents of the shadow root. A new CompilationContext is created and the compileAttributes function is called, this results in the replacement of the placeholder attributes initally set-up during the pre-render step with their values if a value has been assigned. The factories with the associated nodes identified are then passed to the context. The view then binds all behaviors to the source element. The CompilationContext.createView is executed with the DocumentFragment as the root, and returns an HTMLView. This HTMLView includes an appendTo method to attach the fragment to the host element, which it then does. It should be noted that the compiled HTML is a string, which when set on the DocumentFragment as innerHTML, this allows the browser to dictate the creation of HTML nodes.

🔄 **Lifecycle**: Component is disconnected Copy Section

When a component is disconnected, a cleanup step is created to remove associated behaviors.

🔄 **Lifecycle**: Attribute has been changed Copy Section

Attributes have an AttributeDefinition which allows for converters, attachment of the <attributName>Changed aspect of the @attr decorator among other capabilities.

flowchart TD
    A[The browser <code>HTMLElement</code>'s <code>attributeChangedCallback</code> is called] --> B
    B[<code>this.$fastController.onAttributeChangedCallback</code> in <code>FASTElement</code> is called] --> C
    C[calls the attribute definitions <code>onAttributeChangedCallback</code> method with the updated value] --> D
    D[An <code>Updates.enqueue</code> is called which places the update in the task queue which is then executed, these are performed async unless otherwise specified]

These changes are observed and similar to the way Observables work, they utilize an Accessor pattern which has a getValue and setValue in which DOM updates are applied.

Observable backing slots such as _foo are FAST-owned internal state. The
controller's connection-time observable binding only replays public own
properties that shadow prototype accessors; it does not normalize backing slots
into public property assignments. This keeps attribute converter output in its
already-converted model form while preserving pre-upgrade public property
assignments and opt-in extension behavior.

Packages Fast Element Docs Architecture Html Tagged Template Literal (`packages/fast-element/docs/architecture/html-tagged-template-literal.md`) Copy Section