marko 5.22.2 → 5.22.4

package/README.md

@@ -1,84 +1,75 @@
-<h1 align="center">
-    <a href="https://markojs.com/"><img src="https://raw.githubusercontent.com/marko-js/branding/master/marko-logo-medium-cropped.png" alt="Marko" width="250" /></a>
-</h1>
+<div align="center">
 
-<p align="center">
-    <strong>A declarative, HTML-based language that makes building web apps fun 🔥</strong>
-</p>
+# [<img alt="Marko" src="https://raw.githubusercontent.com/marko-js/branding/master/marko-logo-medium-cropped.png" width="250">](https://markojs.com/)
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/marko"><img alt="NPM" src="https://img.shields.io/npm/v/marko.svg"/></a>
-  <a href="https://discord.gg/RFGxYGs"><img alt="Discord" src="https://img.shields.io/badge/discord-chat-7188da.svg"/></a>
-  <a href="https://github.com/marko-js/marko/actions/workflows/ci.yml">
-    <img src="https://github.com/marko-js/marko/actions/workflows/ci.yml/badge.svg" alt="Build status"/>
-  </a>
-  <a href="https://codecov.io/gh/marko-js/marko"><img alt="Coverage Status" src="https://codecov.io/gh/marko-js/marko/branch/master/graph/badge.svg"/></a>
-  <a href="http://npm-stat.com/charts.html?package=marko"><img alt="Downloads" src="https://img.shields.io/npm/dm/marko.svg"/></a>
-</p>
+**A declarative, HTML-based language that makes building web apps fun 🔥**
 
-<p align="center">
-    <a href="https://markojs.com/docs/getting-started/">Docs</a> ∙ <a href="https://markojs.com/try-online/">Try Online</a> ∙ <a href="#contributors">Contribute</a> ∙ <a href="#community--support">Get Support</a>
-</p>
+[![NPM](https://img.shields.io/npm/v/marko.svg)](https://www.npmjs.com/package/marko)
+[![Discord Chat](https://img.shields.io/badge/discord-chat-7188da.svg)](https://discord.gg/RFGxYGs)
+[![Continuous Integration status](https://github.com/marko-js/marko/actions/workflows/ci.yml/badge.svg)](https://github.com/marko-js/marko/actions/workflows/ci.yml)
+[![Code coverage %](https://codecov.io/gh/marko-js/marko/branch/master/graph/badge.svg)](https://codecov.io/gh/marko-js/marko)
+[![# of monthly downloads](https://img.shields.io/npm/dm/marko.svg)](https://npm-stat.com/charts.html?package=marko)
 
-# Intro
+[Docs](https://markojs.com/docs/getting-started/) ∙ [Try Online](https://markojs.com/try-online/) ∙ [Contribute](#contributors) ∙ [Get Support](#community--support)
 
-Marko is HTML _re-imagined_ as a language for building dynamic and reactive user interfaces.
-Just about any valid HTML is valid Marko, but Marko extends the HTML language to allow
-building modern applications in a declarative way.
+</div>
+
+## Intro
 
-Among these extensions are [conditionals](https://markojs.com/docs/conditionals-and-lists/#conditionals), [lists](https://markojs.com/docs/conditionals-and-lists/#lists), [state](https://markojs.com/docs/state/), and [components](https://markojs.com/docs/class-components/).
-Marko supports both single-file components and components broken into separate files.
+Marko is HTML _reimagined_ as a language for building dynamic and reactive user interfaces. Almost any valid HTML is valid Marko, and Marko extends HTML for building modern applications more declaratively. Among these extensions are [conditionals and lists](https://markojs.com/docs/conditionals-and-lists/), [state](https://markojs.com/docs/state/), and [components](https://markojs.com/docs/class-components/).
 
-## Single file component
+Marko supports both single-file components and components across separate files.
 
-The following single-file component renders a button and a counter with the
-number of times the button has been clicked.
+### Single-file component
+
+The following renders a button and a counter of how many times the button has been pressed:
 
 **click-count.marko**
 
 ```marko
 class {
-    onCreate() {
-        this.state = { count: 0 };
-    }
-    increment() {
-        this.state.count++;
-    }
+  onCreate() {
+    this.state = { count: 0 };
+  }
+  increment() {
+    this.state.count++;
+  }
 }
 
 style {
-    .count {
-        color: #09c;
-        font-size: 3em;
-    }
-    .example-button {
-        font-size: 1em;
-        padding: 0.5em;
-    }
+  .count {
+    color: #09c;
+    font-size: 3em;
+  }
+  .press-me {
+    padding: 0.5em;
+  }
 }
 
-<div.count>
-    ${state.count}
-</div>
-<button.example-button on-click('increment')>
-    Click me!
+<output.count>
+  ${state.count}
+</output>
+<button.press-me on-click('increment')>
+  Press me!
 </button>
 ```
 
-## Multi-file component
+### Multi-file component
+
+The same component as above, but split into:
 
-The same component as above split into an `index.marko` template file,
-`component.js` containing your component logic, and `style.css` containing your
-component style:
+- `index.marko` template file
+- `component.js` component JS logic file
+- `style.css` component styles file
 
 **index.marko**
 
 ```marko
-<div.count>
-    ${state.count}
-</div>
-<button.example-button on-click('increment')>
-    Click me!
+<output.count>
+  ${state.count}
+</output>
+<button.press-me on-click('increment')>
+  Press me!
 </button>
 ```
 
@@ -102,59 +93,68 @@ export default {
   color: #09c;
   font-size: 3em;
 }
-.example-button {
-  font-size: 1em;
+.press-me {
   padding: 0.5em;
 }
 ```
 
 ## Concise Syntax
 
-Marko also supports a beautifully concise syntax as an alternative to its HTML
-syntax. Find out more about the [concise syntax here](https://markojs.com/docs/concise/).
+Marko also supports [a beautifully concise syntax as an alternative](https://markojs.com/docs/concise/) to its HTML syntax:
+
+<table><thead><tr><th>Concise syntax<th>HTML syntax
+<tbody><tr>
+<td>
 
 ```marko
-<!-- Marko HTML syntax -->
-<ul class="example-list">
-    <for|color| of=['a', 'b', 'c']>
-        <li>${color}</li>
-    </for>
-</ul>
+ul.example-list
+  for|color| of=[a, b, c]
+    li -- ${color}
 ```
 
+<td>
+
 ```marko
-// Marko concise syntax
-ul.example-list
-    for|color| of=['a', 'b', 'c']
-        li -- ${color}
+<ul class="example-list">
+  <for|color| of=[a, b, c]>
+    <li>${color}</li>
+  </for>
+</ul>
 ```
 
-# Getting Started
+</table>
+
+## Getting Started
 
 1. `npm install marko`
 2. Read the [docs](https://markojs.com/docs/getting-started/)
 
-# Community & Support
+## Community & Support
 
-| <a alt="See Marko questions on Stack Overflow" href="https://stackoverflow.com/questions/tagged/marko"><img src="https://user-images.githubusercontent.com/1958812/56055468-619b3e00-5d0e-11e9-92ae-200c212cafb8.png" height="50px"/></a> | <a alt="Chat with us on Discord" href="https://discord.gg/RFGxYGs"><img src="https://user-images.githubusercontent.com/4985201/89313514-6edbea80-d62d-11ea-8447-ca2fd8983661.png" height="55px"/></a> | <a alt="Tweet about Marko" href="https://twitter.com/intent/tweet?hashtags=markojs"><img src="https://user-images.githubusercontent.com/1958812/56055707-07e74380-5d0f-11e9-8a59-d529fbb5a81e.png" height="40px"/></a> |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Ask and answer StackOverflow questions with the [`marko` tag](https://stackoverflow.com/questions/tagged/marko)                                                                                                                           | Come hang out in our Discord chat room, ask questions, and discuss project direction                                                                                                                  | Tweet to [`@MarkoDevTeam`](https://twitter.com/MarkoDevTeam) or with the [`#markojs` hashtag](https://twitter.com/search?q=%23markojs&f=live)                                                                          |
+<table>
+<thead><tr>
+  <th><img alt="Stack Overflow" src="https://user-images.githubusercontent.com/1958812/56055468-619b3e00-5d0e-11e9-92ae-200c212cafb8.png" width="205"> 
+  <th><img alt="Discord" src="https://user-images.githubusercontent.com/4985201/89313514-6edbea80-d62d-11ea-8447-ca2fd8983661.png" width="162">
+  <th><img alt="Twitter" src="https://user-images.githubusercontent.com/1958812/56055707-07e74380-5d0f-11e9-8a59-d529fbb5a81e.png" width="53">
+<tbody><tr><td>
+  
+  Ask and answer [StackOverflow questions with the `#marko` tag](https://stackoverflow.com/questions/tagged/marko)<td>
 
-# Contributors
+Come [hang out in our Discord chat](https://discord.gg/RFGxYGs), ask questions, and discuss project direction<td>
 
-Marko would not be what it is without all those who have contributed ✨
+[Tweet to `@MarkoDevTeam`](https://twitter.com/MarkoDevTeam), or with the [`#markojs` hashtag](https://twitter.com/search?q=%23markojs&f=live)
 
-<a href="https://github.com/marko-js/marko/graphs/contributors">
-    <img src="https://opencollective.com/marko-js/contributors.svg?width=890&button=false"/>
-</a>
+</table>
 
-## Get Involved!
+### Contributors
 
-- Pull requests are welcome!
-- Read [`CONTRIBUTING.md`](.github/CONTRIBUTING.md) and check out our [bite-sized](https://github.com/marko-js/marko/issues?q=is%3Aissue+is%3Aopen+label%3Adifficulty%3Abite-sized) and [help-wanted](https://github.com/marko-js/marko/issues?q=is%3Aissue+is%3Aopen+label%3Astatus%3Ahelp-wanted) issues
-- Submit github issues for any feature enhancements, bugs or documentation problems
-- By participating in this project you agree to abide by its [Code of Conduct](https://ebay.github.io/codeofconduct).
+Marko would not be what it is without all those who have contributed ✨
+
+[![All marko-js/marko GitHub contributors](https://opencollective.com/marko-js/contributors.svg?width=890&button=false)](https://github.com/marko-js/marko/graphs/contributors)
 
-# License
+### Get Involved!
 
-MIT
+- Pull requests are welcome!
+- Submit [GitHub issues](https://github.com/marko-js/marko/issues) for any feature enhancements, bugs, or documentation problems
+- [Read the Contribution Tips and Guidelines](.github/CONTRIBUTING.md)
+- Participants in this project agree to abide by [its Code of Conduct](https://github.com/eBay/.github/blob/main/CODE_OF_CONDUCT.md)

package/dist/core-tags/core/await/index.marko

@@ -0,0 +1,13 @@
+/**
+ * @template T
+ * @typedef {{
+ *   value?: T;
+ *   then?: Marko.Body<[Awaited<T>], void>;
+ *   catch?: Marko.Body<[unknown], void>;
+ *   placeholder?: Marko.Body<[], void>;
+ *   client-reorder?: boolean;
+ *   name?: string;
+ *   timeout?: number;
+ *   show-after?: string;
+ * }} Input
+ */

package/docs/rollup.md

@@ -1,155 +1,309 @@
 # Marko + Rollup
 
-# Installation
+This is Marko’s official integration plugin for [the Rollup bundler](https://rollupjs.org/).
 
-```console
-npm install @marko/rollup rollup @rollup/plugin-node-resolve @rollup/plugin-commonjs -D
+## Installation
+
+```sh
+npm install --save-dev \
+  @marko/rollup \
+  rollup \
+  @rollup/plugin-node-resolve \
+  @rollup/plugin-commonjs
 ```
 
-# Basic example config
+> **Note**: The Marko runtime is CommonJS, so don’t forget the `@rollup/plugin-commonjs` package!
+
+## Configuration
+
+`@marko/rollup` exports two methods for use in [Rollup configuration files](https://rollupjs.org/guide/en/#configuration-files): `.browser()` and `.server()`.
+
+You _probably_ want to use both, since that’ll get you…
+
+- Automatic [`input` entrypoint configuration](https://rollupjs.org/guide/en/#input) for route-based bundle splitting
+- Complete control over asset loading with [the `<rollup>` tag](#rollup-tag)
+- The strengths behind why Marko exists in the first place: cooperation between servers and browsers for high performance in both
+
+> **ProTip**: You _could_ use only `.browser()` or only `.server()` to build a completely client-side-rendered or server-side-rendered app. That would be a little odd, but you could.
 
-**Note: The Marko runtime is authored in commonjs, this means the `@rollup/plugin-commonjs` is required!**
+### Config example
 
-```javascript
+```js
 import nodeResolve from "@rollup/plugin-node-resolve";
 import commonjs from "@rollup/plugin-commonjs";
 import marko from "@marko/rollup";
 
-export default {
-  ...,
+const sharedPlugins = [
+  commonjs({
+    extensions: [".js", ".marko"]
+  }),
+  // If using Marko’s `style {}` blocks, you’ll need an appropriate plugin, like npmjs.com/rollup-plugin-postcss
+  postcss({ external: true })
+]
+
+const serverAssetsConfig = {
+  input: "src/start-server.js",
+  plugins: [
+    marko.server(),
+    nodeResolve({ preferBuiltins: true })
+    ...sharedPlugins
+  ]
+};
+const browsersAssetsConfig = {
   plugins: [
     marko.browser(),
-    nodeResolve({
-      browser: true,
-      extensions: [".js", ".marko"]
-    }),
-    // NOTE: The Marko runtime uses commonjs so this plugin is also required.
-    commonjs({
-      extensions: [".js", ".marko"]
-    }),
-    // If using `style` blocks with Marko you must use an appropriate plugin.
-    postcss({
-      external: true
-    })
+    nodeResolve({ browser: true })
+    ...sharedPlugins
   ]
 };
+
+export default [serverAssetsConfig, browsersAssetsConfig];
 ```
 
-Likewise, if bundling the components for the server use `marko.server()` as the plugin.
+### Advanced config example
 
-# Linked config
+The following configuration file is long and hairy, which may be upsetting to some viewers. However, it does show how to accomplish the following:
 
-If you use _both_ the `server` and `browser` plugins (in a [multi rollup config setup](https://rollupjs.org/guide/en/#configuration-files:~:text=export%20an%20array)) `@marko/rollup` will go into a _linked_ mode.
-In the linked mode you will have access to the [`<rollup>` tag](#rollup-tag) on the server, and the browser config
-will automatically have the [`input`](https://rollupjs.org/guide/en/#input) option set.
+- Support for Rollup’s watch mode
+- A bundle analyzer
+- The ability to `import` JSON files to use their data
+- The ability to `import` image files to use their asset URLs for `img[src]` and such
+- Dead-code elimination for development-only code
+- Static compression of assets for something like [NGiNX’s `gzip_static`](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html)
+- A CSS preprocessor (Sass, in this case)
+- Browserslist to automatically configure:
+  - Babel for JS transpilation
+  - Autoprefixer for CSS transpilation
 
-```javascript
-export default [{
-  // Config object for bundling server assets.
-  input: "src/your-server-entry.js",
-  plugins: [
-    marko.server()
-    ...
-  ]
-}, {
-  // Config object for bundling browser assets.
-  plugins: [
-    marko.browser()
-    ...
-  ]
-}];
+<details><summary>Big ugly production-esque Rollup config</summary>
+
+```js
+import { builtinModules } from "module";
+import path from "path";
+import autoprefixer from "autoprefixer";
+import babelPlugin from "@rollup/plugin-babel";
+import commonjsPlugin from "@rollup/plugin-commonjs";
+import jsonPlugin from "@rollup/plugin-json";
+import markoPlugin from "@marko/rollup";
+import nodeResolvePlugin from "@rollup/plugin-node-resolve";
+import replacePlugin from "@rollup/plugin-replace";
+import runPlugin from "@rollup/plugin-run";
+import stylesPlugin from "rollup-plugin-styles";
+import urlPlugin from "@rollup/plugin-url";
+import pkg from "./package.json";
+
+const __DEV__ = process.env.NODE_ENV === "development";
+const __PROD__ = !__DEV__;
+
+const isWatch = Boolean(process.env.ROLLUP_WATCH);
+
+const publicPath = "/s/"; // Guess what character is only 5 bits under HPACK
+const assetFileNames = "[name]-[hash][extname]";
+
+const externalDependencies = [
+  ...Object.keys(pkg.dependencies),
+  ...builtinModules
+];
+
+process.env.SASS_PATH = "./:./node_modules";
+
+export default (async () => [
+  compiler("server", {
+    input: "index.js",
+    output: {
+      dir: "built/server/",
+      assetFileNames: `../browser/${assetFileNames}`,
+      format: "cjs",
+      sourcemap: true
+    },
+    external: id =>
+      externalDependencies.some(
+        dependency => id === dependency || id.startsWith(dependency + "/")
+      ),
+    plugins: [isWatch && runPlugin({ execArgv: ["--enable-source-maps"] })]
+  }),
+
+  compiler("browser", {
+    output: {
+      dir: "built/browser/",
+      chunkFileNames: __PROD__ ? "[name]-[hash].js" : null,
+      entryFileNames: __PROD__ ? "[name]-[hash].js" : null,
+      assetFileNames,
+      sourcemap: true,
+      sourcemapExcludeSources: __PROD__
+    },
+    plugins: [
+      stylesPlugin({
+        mode: "extract",
+        sourceMap: true,
+        config: {
+          target: "browserslist:css",
+          plugins: [autoprefixer({ env: "css" })]
+        },
+        minimize: __PROD__,
+        url: {
+          publicPath,
+          hash: assetFileNames
+        }
+      }),
+      __PROD__ && (await import("rollup-plugin-terser")).terser(),
+      __PROD__ &&
+        (await import("rollup-plugin-gzip")).default({
+          filter: /\.(?:js|css|svg|json|xml|txt)$/,
+          minSize: 1024,
+          gzipOptions: {
+            level: 9,
+            memLevel: 9
+          }
+        }),
+      __PROD__ &&
+        !isWatch &&
+        (await import("rollup-plugin-visualizer")).default(),
+      __PROD__ &&
+        !isWatch && {
+          name: "bundle-visualizer-location",
+          writeBundle() {
+            console.info(
+              `📊 Bundle visualizer at \x1b[4;36mfile://${path.join(
+                __dirname,
+                "../../",
+                bundleAnalyzerFilename
+              )}\x1b[0m`
+            );
+          }
+        }
+    ]
+  })
+])();
+
+function compiler(target, config) {
+  const isBrowser = target === "browser";
+  const browserslistEnv = isBrowser ? "js" : "server";
+  const babelConfig = {
+    comments: false,
+    browserslistEnv,
+    compact: false,
+    babelrc: false,
+    caller: { target }
+  };
+  if (isBrowser) {
+    babelConfig.presets = [
+      [
+        "@babel/preset-env",
+        {
+          browserslistEnv,
+          bugfixes: true
+        }
+      ]
+    ];
+  }
+
+  return {
+    ...config,
+    preserveEntrySignatures: false,
+    plugins: [
+      markoPlugin[target]({ babelConfig }),
+      nodeResolvePlugin({
+        browser: isBrowser,
+        preferBuiltins: !isBrowser
+      }),
+      commonjsPlugin(),
+      replacePlugin({
+        preventAssignment: true,
+        values: { __DEV__, __PROD__ }
+      }),
+      babelPlugin({
+        babelHelpers: "bundled",
+        ...babelConfig
+      }),
+      jsonPlugin(),
+      urlPlugin({
+        publicPath,
+        destDir: "built/browser/",
+        fileName: assetFileNames,
+        include: "**/*.{svg,png,jpg,jpeg}",
+        limit: 0, // Never Base64 & inline
+        emitFiles: !isBrowser
+      }),
+      ...config.plugins
+    ]
+  };
+}
 ```
 
+</details>
+
 ## `<rollup>` tag
 
-In a [linked setup](#linked-config) you have access to the `<rollup>` tag which will provide two [tag parameters](https://markojs.com/docs/syntax/#parameters) that allow you to write out the asset links for your server rendered app.
+Using both `.server()` and `.browser()` enables **the `<rollup>` tag**, which gives you complete control over how your app loads assets. That lets you do things like:
 
-The first parameter `entry` is the generated `input` name that the server plugin gave to the browser compiler.
-You can use it to find the corresponding entry chunk from rollups build.
+- [Critical CSS](https://web.dev/extract-critical-css/) for components as they write out within a kB budget, or [as components first appear on the page](https://jakearchibald.com/2016/link-in-body/#a-simpler-better-way), or any other style-loading mad science
+- [`module`/`nomodule` scripts](https://philipwalton.com/articles/using-native-javascript-modules-in-production-today/) for smaller bundles in modern browsers
+- [Content-Security Policy `nonce`s](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) or [Subresource `integrity` hashes](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
+- Anything a web page can do, really. You can even combine `<rollup>` with [the `serialize` option](#options.serialize) to be as fancy as you wanna be.
 
-The second parameter `output` is an array of `AssetInfo | ChunkInfo` objects with most of the same properties returned from rollup's [`generateBundle` hook](https://rollupjs.org/guide/en/#generatebundle). Some properties have been stripped, notably `code` and `map` since they would be too large to inline directly. A `size` property is also available for all chunks to allow you to be able to filter out empty chunks, or inline chunks of certain size.
+The `<rollup>` tag provides two [tag parameters](https://markojs.com/docs/syntax/#parameters):
+
+1. `entry` is the generated `input` string that the `server` plugin gave to the `browser` plugin. You can use it to find the corresponding entry chunk from Rollup’s `output` (the next parameter).
+
+2. `output` is an array of `AssetInfo | ChunkInfo` objects with most of [the data returned from Rollup's `generateBundle` hook](https://rollupjs.org/guide/en/#generatebundle). Some properties are omitted, like `code` and `map`, since they’re often too large to inline directly. However, each chunk also has a `size` property, to let you filter out empty chunks, inline code yourself below a certain size, or other delightful devilishness.
+
+For example, using the `entry` name and properties of `output` items to load scripts:
 
 ```marko
 <head>
   <rollup|entry, output|>
     $ const entryChunk = output.find(chunk => chunk.name === entry);
 
-    <if(entryChunk.size /* skip scripts all together if empty js file */)>
+    <if(entryChunk.size /* only load non-empty JS entry points */)>
       <for|fileName| of=entryChunk.imports>
-        <link rel="modulepreload" href=fileName/>
+        <link rel="modulepreload" href=fileName />
       </for>
 
-      <script async type="module" src=entryChunk.fileName/>
+      <script async type="module" src=entryChunk.fileName></script>
     </if>
   </rollup>
 </head>
 ```
 
-Ultimately it is up to you to map the chunk data (sometimes referred to as a manifest) into the `<link>`'s and `<script>`'s rendered by your application.
+> **Note**: It’s up to you to transform the chunk data (also called the **manifest**) into `<link>`s, `<script>`s, and other HTML to load assets. Opting into complete control means we can’t do any of it for you.
 
-If your rollup browser config contains multiple `output` options, or you have multiple browser configs, all of the `chunks` for each `output` are passed into the `<rollup>` tag.
+If your Rollup `browser` config contains multiple `output` options, or you have multiple `browser` configs, every `output`’s chunk is passed to the `<rollup>` tag.
 
-For example if you have an `esm` and `iife` build:
+For example, if you have both `esm` and `iife` build outputs configured:
 
-```javascript
+```js
 {
-  plugins: [
-    marko.browser()
-    ...
-  ],
   output: [
-    { dir: 'dist/iife', format: 'iife' },
-    { dir: 'dist/esm', format: 'esm' }
-  ]
+    { dir: "dist/iife", format: "iife" },
+    { dir: "dist/esm", format: "esm" }
+  ];
 }
 ```
 
-we could access the assets from both builds:
+…you could cross-reference assets from both…
 
 ```marko
-<head>
-  <rollup|entry, iifeOutput, esmOutput|>
-    $ const iifeEntryChunk = iifeOutput.find(chunk => chunk.name === entry);
-    $ const esmEntryChunk = esmOutput.find(chunk => chunk.name === entry);
+<rollup|entry, iifeOutput, esmOutput|>
+  $ const iifeEntryChunk = iifeOutput.find(chunk => chunk.name === entry);
+  $ const esmEntryChunk = esmOutput.find(chunk => chunk.name === entry);
 
-    <script async type="module" src=esmEntryChunk.fileName/>
-    <script nomodule src=iifeEntryChunk.fileName></script>
-  </rollup>
-</head>
+  <script src=esmEntryChunk.fileName type="module" async></script>
+  <script src=iifeEntryChunk.fileName nomodule async></script>
+</rollup>
 ```
 
-and _boom_ you now have a [`module/nomodule` setup](https://philipwalton.com/articles/using-native-javascript-modules-in-production-today/).
-
-# Top level components
-
-Marko was designed to send as little JavaScript to the browser as possible. One of the ways we do this is by automatically determining which templates in your app should be shipped to the browser. When rendering a template on the server, it is only necessary to bundle the styles and interactive components rendered by that template.
-
-To send the minimal amount of Marko templates to the browser you can provide a Marko template directly as the `input`.
-This will also automatically invoke code to initialize the components in the browser, so there is no need to call
-`template.render` yourself in the browser.
-
-> Note: if you are using _linked_ plugins then the server plugin will automatically tell the browser compiler which Marko templates to load.
-
-```js
-export default {
-  input: "./my-marko-page.marko",
-  plugins: [
-    marko.browser(),
-    ...
-  ],
-  ...
-}
-```
+…and _boom:_ you now have [a `module`/`nomodule` setup](https://philipwalton.com/articles/using-native-javascript-modules-in-production-today/).
 
 ## Options
 
-Both the `server` and `browser` plugins can receive the same options.
+### `options.babelConfig`
 
-### options.babelConfig
+Both the `.server()` and `.browser()` plugins accept this option.
 
-You can manually override the Babel configuration used by passing a `babelConfig` object to the `@marko/rollup` plugin. By default Babels regular [config file resolution](https://babeljs.io/docs/en/config-files) will be used.
+You can manually override the builtin Babel configuration by passing a `babelConfig` object. By default, [Babel’s regular config file resolution](https://babeljs.io/docs/en/config-files) will be used.
 
-```javascript
+```js
 marko.browser({
   babelConfig: {
     presets: ["@babel/preset-env"]
@@ -157,42 +311,40 @@ marko.browser({
 });
 ```
 
-### options.runtimeId
+### `options.runtimeId`
+
+Both the `.server()` and `.browser()` plugins accept this option. In fact, you _really_ want to use it with both simultaneously.
 
-In some cases you may want to embed multiple isolated copies of Marko on the page. Since Marko relies on some `window` properties to initialize this can cause issues. For example, by default Marko will read the server rendered hydration code from `window.$components`. In Marko you can change these `window` properties by rendering with `{ $global: { runtimeId: "MY_MARKO_RUNTIME_ID" } }` as input on the server side.
+In some cases, you may want to embed multiple isolated copies of Marko on the page. (If you can’t think of why, then don’t worry about this option.)
 
-This plugin exposes a `runtimeId` option produces output that automatically sets `$global.runtimeId` on the server side and initializes properly in the browser.
+Since Marko uses some `window` properties to initialize, multiple instances can cause issues. For example, by default Marko checks `window.$components` for server-rendered hydration. Usually you can change these `window` properties by [rendering with `{ $global: { runtimeId: "MY_MARKO_RUNTIME_ID" } }` as input](https://markojs.com/docs/rendering/#global-data) on the server, but since `@marko/rollup` usually writes the autoinitialization code for you, instead this plugin exposes a `runtimeId` option to automatically set `$global.runtimeId` to initialize properly in the browser:
 
 ```js
 const runtimeId = "MY_MARKO_RUNTIME_ID";
-// Make sure the `runtimeId` is the same across all of your plugins!
+// Make the `runtimeId` the same across `server` and `browser`, or it’ll error!
 marko.server({ runtimeId });
 marko.browser({ runtimeId });
 ```
 
-### options.serialize
+### `options.serialize`
 
-This option is only available for the `browser` plugin. It allows you to transform the list of chunks serialzed in a [_linked config_](#linked-config) to include whatever you like.
-For example if you _did_ want to include the `code` property from the rollup chunk, to say inline some content, the following would work:
+This option is only available for the `.browser()` plugin. It lets you inspect and transform the `output` chunks before they’re passed to [the `<rollup>` tag](#rollup-tag).
+
+For example, if you _did_ want to include the `code` property from the Rollup chunk — say, to inline code small enough that it’s not worth the overhead of an HTTP request, you’d try something like the following:
 
 ```js
 marko.browser({
   serialize(output) {
-    return output.map(chunk =>
-      chunk.type === "asset"
-        ? {
-            type: "asset",
-            fileName: chunk.fileName
-          }
+    return output.map(({ type, fileName, isEntry, code }) =>
+      type === "asset"
+        ? { type, fileName }
         : {
-            type: "chunk",
-            name: chunk.name,
-            isEntry: chunk.isEntry,
-            fileName: chunk.fileName,
-            code:
-              chunk.code.replace(/^\s+$/, "").length < 1024
-                ? chunk.code
-                : undefined // only inline small code chunks
+            type,
+            name,
+            isEntry,
+            fileName,
+            // only inline code chunks below 1kB
+            inline: code.trim().length < 1024 && code
           }
     );
   }

package/docs/troubleshooting-streaming.md

@@ -10,10 +10,16 @@
 
 - Some software doesn’t support HTTP/2 or higher “upstream” connections at all or very well — if your Node server uses HTTP/2, you may need to downgrade.
 
-- Automatic gzip/brotli compression may have their buffer sizes set too high; you can tune their buffers to be smaller for faster streaming in exchange for slightly worse compression.
-
 - Check if “upstream” connections are `keep-alive`: overhead from closing and reopening connections may delay responses.
 
+- For typical modern webpage filesizes, the following bullet points probably won’t matter. But if you want to stream **small chunks of data with the lowest latency**, investigate these sources of buffering:
+
+  - Automatic gzip/brotli compression may have their buffer sizes set too high; you can tune their buffers to be smaller for faster streaming in exchange for slightly worse compression.
+
+  - You can [tune HTTPS record sizes for lower latency, as described in High Performance Browser Networking](https://hpbn.co/transport-layer-security-tls/#optimize-tls-record-size).
+
+  - Turning off MIME sniffing with [the `X-Content-Type-Options`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options) header eliminates browser buffering at the very beginning of HTTP responses
+
 ### NGiNX
 
 Most of NGiNX’s relevant parameters are inside [its builtin `http_proxy` module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering):

package/index.d.ts

@@ -0,0 +1,317 @@
+declare module "*.marko" {
+  const template: Marko.Template;
+  export default template;
+}
+
+declare namespace NodeJS {
+  // eslint-disable-next-line @typescript-eslint/no-empty-interface
+  interface ReadableStream {}
+}
+
+declare namespace Marko {
+  /** A mutable global object for the current render. */
+  export interface Global {
+    serializedGlobals?: Record<string, boolean>;
+    [attr: PropertyKey]: unknown;
+  }
+
+  export type TemplateInput<Input = { [attr: PropertyKey]: any }> = Input & {
+    $global?: Global;
+  };
+
+  export interface Out<Component extends Marko.Component = Marko.Component>
+    extends PromiseLike<RenderResult<Component>> {
+    /** The underlying ReadableStream Marko is writing into. */
+    stream: unknown;
+    /** A mutable global object for the current render. */
+    global: Global;
+    /** Disable all async rendering. Will error if something beings async. */
+    sync(): void;
+    /** Returns true if async rendering is disabled. */
+    isSync(): boolean;
+    /** Write unescaped text at the current stream position. */
+    write(val: string | void): this;
+    /** Write javascript content to be merged with the scripts Marko sends out on the next flush. */
+    script(val: string | void): this;
+    /** Returns the currently rendered html content. */
+    toString(): string;
+    /** Starts a new async/forked stream. */
+    beginAsync(options?: {
+      name?: string;
+      timeout?: number;
+      last?: boolean;
+    }): Out;
+    /** Marks the current stream as complete (async streams may still be executing). */
+    end(val?: string | void): this;
+    emit(eventName: PropertyKey, ...args: any[]): boolean;
+    on(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+    once(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+    prependListener(
+      eventName: PropertyKey,
+      listener: (...args: any[]) => any
+    ): this;
+    removeListener(
+      eventName: PropertyKey,
+      listener: (...args: any[]) => any
+    ): this;
+    /** Register a callback executed when the last async out has completed. */
+    onLast(listener: (next: () => void) => unknown): this;
+    /** Pipe Marko's stream to another stream. */
+    pipe(stream: unknown): this;
+    /** Emits an error on the stream. */
+    error(e: Error): this;
+    /** Schedules a Marko to flush buffered html to the underlying stream. */
+    flush(): this;
+    /** Creates a detached out stream (used for out of order flushing). */
+    createOut(): Out;
+    /** Write escaped text at the current stream position. */
+    text(val: string | void): void;
+  }
+
+  /** Body content created from by a component, typically held in an object with a renderBody property. */
+  // eslint-disable-next-line @typescript-eslint/no-empty-interface
+  export interface Body<
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    in Params extends readonly any[] = [],
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    out Return = void
+  > {}
+
+  /** Valid data types which can be passed in as a <${dynamic}/> tag name. */
+  export type DynamicTagName =
+    | {
+        renderBody?: Body<any, any> | Template | string | void | false;
+      }
+    | Body<any, any>
+    | Template
+    | string
+    | void
+    | false;
+
+  /** Extract the return tag type from a renderBody. */
+  export type BodyReturnType<B> = B extends Body<any, infer Return>
+    ? Return
+    : never;
+
+  /** Extract the tag parameter types received by a renderBody. */
+  export type BodyParamaters<B> = B extends Body<infer Params, any>
+    ? Params
+    : never;
+
+  export abstract class Component<
+    Input extends Record<PropertyKey, any> = Record<PropertyKey, any>
+  > implements Emitter
+  {
+    /** A unique id for this instance. */
+    public readonly id: string;
+    /** The top level element rendered by this instance. */
+    public readonly el: Element | void;
+    /** The attributes passed to this instance. */
+    public readonly input: Input;
+    /** @deprecated */
+    public readonly els: Element[];
+    /** Mutable state that when changed causes a rerender. */
+    abstract state: undefined | null | Record<PropertyKey, any>;
+
+    /** Returns the amount of event handlers listening to a specific event. */
+    listenerCount(eventName: PropertyKey): number;
+    /**
+     * Used to wrap an existing event emitted and ensure that all events are
+     * cleaned up once this component is destroyed
+     * */
+    subscribeTo(
+      emitter: unknown
+    ): Omit<Emitter, "listenerCount" | "prependListener" | "emit">;
+    /** Emits an event on the component instance. */
+    emit(eventName: PropertyKey, ...args: any[]): boolean;
+    /** Listen to an event on the component instance. */
+    on(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+    /** Listen to an event on the component instance once. */
+    once(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+    /** Listen to an event on the component instance before all other listeners. */
+    prependListener(
+      eventName: PropertyKey,
+      listener: (...args: any[]) => any
+    ): this;
+    /** Remove a listener from the component instance. */
+    removeListener(
+      eventName: PropertyKey,
+      listener: (...args: any[]) => any
+    ): this;
+    /** Remove all listeners from the component instance. */
+    removeAllListeners(eventName?: PropertyKey): this;
+    /** Removes the component instance from the DOM and cleans up all active event handlers including all children. */
+    destroy(): void;
+    /** Schedule an update (similar to if a state had been changed). */
+    forceUpdate(): void;
+    /** Generates a unique id derived from the current unique instance id (similar to :scoped in the template). */
+    elId(key?: string, index?: number): string;
+    /** @alias elId */
+    getElId(key?: string, index?: number): string;
+    /** Gets an element reference by its `key` attribute in the template. */
+    getEl<T extends Element | void = Element | void>(
+      key?: string,
+      index?: number
+    ): T;
+    /** Gets all element references by their `key` attribute in the template. */
+    getEls<T extends Element[] = Element[]>(key: string): T;
+    /** Gets a component reference by its `key` attribute in the template. */
+    getComponent<T extends Component | void = Component | void>(
+      key: string,
+      index?: number
+    ): T;
+    /** Gets all component references by their `key` attribute in the template. */
+    getComponents<T extends Component[] = Component[]>(key: string): T;
+    /** True if this instance has been removed from the dom. */
+    /** True if this instance is scheduled to rerender. */
+    isDestroyed(): boolean;
+    /** Replace the entire state object with a new one, removing old properties. */
+    replaceState(state: this["state"]): void;
+    /**
+     * Update a property on this.state (should prefer mutating this.state directly).
+     * When passed an object as the first argument, it will be merged into the state.
+     */
+    setState<Key extends PropertyKey>(
+      name: Key & keyof this["state"],
+      value: (this["state"] & Record<PropertyKey, unknown>)[Key]
+    ): void;
+    setState(value: Partial<this["state"]>): void;
+
+    /** Schedules an update related to a specific state property and optionally updates the value. */
+    setStateDirty<Key extends PropertyKey>(
+      name: Key & keyof this["state"],
+      value?: (this["state"] & Record<PropertyKey, unknown>)[Key]
+    ): void;
+    /** Synchronously flush any scheduled updates. */
+    update(): void;
+    /** Appends the dom for the current instance to a parent DOM element. */
+    appendTo(target: ParentNode): this;
+    /** Inserts the dom for the current instance after a sibling DOM element. */
+    insertAfter(target: ChildNode): this;
+    /** Inserts the dom for the current instance before a sibling DOM element. */
+    insertBefore(target: ChildNode): this;
+    /** Prepends the dom for the current instance to a parent DOM element. */
+    prependTo(target: ParentNode): this;
+    /** Replaces an existing DOM element with the dom for the current instance. */
+    replace(target: ChildNode): this;
+    /** Replaces the children of an existing DOM element with the dom for the current instance. */
+    replaceChildrenOf(target: ParentNode): this;
+    /** Called when the component is firsted created. */
+    abstract onCreate?(input: this["input"], out: Marko.Out): void;
+    /** Called every time the component receives input from it's parent. */
+    abstract onInput?(
+      input: this["input"],
+      out: Marko.Out
+    ): void | this["input"];
+    /** Called after a component has successfully rendered, but before it's update has been applied to the dom. */
+    abstract onRender?(out: Marko.Out): void;
+    /** Called after the first time the component renders and is attached to the dom. */
+    abstract onMount?(): void;
+    /** Called when a components render has been applied to the DOM (excluding when it is initially mounted). */
+    abstract onUpdate?(): void;
+    /** Called when a component is destroyed and removed from the dom. */
+    abstract onDestroy?(): void;
+  }
+
+  /** The top level api for a Marko Template. */
+  export abstract class Template {
+    /** Creates a Marko compatible output stream. */
+    createOut(): Out;
+
+    /**
+     * The folowing types are processed up by the @marko/language-tools
+     * and inlined into the compiled template.
+     *
+     * This is done to support generics on each of these methods
+     * until TypeScript supports higher kinded types.
+     *
+     * https://github.com/microsoft/TypeScript/issues/1213
+     */
+
+    /** @marko-overload-start */
+    /** Asynchronously render the template. */
+    abstract render(
+      input: Marko.TemplateInput,
+      stream?: {
+        write: (chunk: string) => void;
+        end: (chunk?: string) => void;
+      }
+    ): Marko.Out<Marko.Component>;
+
+    /** Synchronously render the template. */
+    abstract renderSync(
+      input: Marko.TemplateInput
+    ): Marko.RenderResult<Marko.Component>;
+
+    /** Synchronously render a template to a string. */
+    abstract renderToString(input: Marko.TemplateInput): string;
+
+    /** Render a template and return a stream.Readable in nodejs or a ReadableStream in a web worker environment. */
+    abstract stream(
+      input: Marko.TemplateInput
+    ): ReadableStream<string> & NodeJS.ReadableStream;
+    /** @marko-overload-end */
+  }
+
+  export interface RenderResult<
+    out Component extends Marko.Component = Marko.Component
+  > {
+    /** Returns the component created as a result of rendering the template. */
+    getComponent(): Component;
+    getComponents(selector?: any): any;
+    /** Triggers the mount lifecycle of a component without necessarily attaching it to the DOM. */
+    afterInsert(host?: any): this;
+    /** Gets the DOM node rendered by a template. */
+    getNode(host?: any): Node;
+    /** Gets the HTML output of the rendered template. */
+    toString(): string;
+    /** Appends the dom of the rendered template to a parent DOM element. */
+    appendTo(target: ParentNode): this;
+    /** Inserts the dom of the rendered template after a sibling DOM element. */
+    insertAfter(target: ChildNode): this;
+    /** Inserts the dom of the rendered template before a sibling DOM element. */
+    insertBefore(target: ChildNode): this;
+    /** Prepends the dom of the rendered template to a parent DOM element. */
+    prependTo(target: ParentNode): this;
+    /** Replaces an existing DOM element with the dom of the rendered template. */
+    replace(target: ChildNode): this;
+    /** Replaces the children of an existing DOM element with the dom of the rendered template. */
+    replaceChildrenOf(target: ParentNode): this;
+    out: Out<Component>;
+    /** @deprecated */
+    document: any;
+    /** @deprecated */
+    getOutput(): string;
+    /** @deprecated */
+    html: string;
+    /** @deprecated */
+    context: Out<Component>;
+  }
+
+  export interface Emitter {
+    listenerCount(eventName: PropertyKey): number;
+    emit(eventName: PropertyKey, ...args: any[]): boolean;
+    on(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+    once(eventName: PropertyKey, listener: (...args: any[]) => any): this;
+    prependListener(
+      eventName: PropertyKey,
+      listener: (...args: any[]) => any
+    ): this;
+    removeListener(
+      eventName: PropertyKey,
+      listener: (...args: any[]) => any
+    ): this;
+    removeAllListeners(eventName?: PropertyKey): this;
+  }
+
+  export type Repeated<T> = [T, T, ...T[]];
+  export type Repeatable<T> = T | Repeated<T>;
+  export type MaybeRepeatable<T> = undefined | Repeatable<T>;
+
+  export interface NativeTags {
+    [name: string]: {
+      input: Record<string, unknown>;
+      return: unknown;
+    };
+  }
+}

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "marko",
-    "version": "5.22.2",
+    "version": "5.22.4",
     "license": "MIT",
     "description": "UI Components + streaming, async, high performance, HTML templating for Node.js and the browser.",
     "dependencies": {
-        "@marko/compiler": "^5.23.2",
-        "@marko/translator-default": "^5.22.2",
+        "@marko/compiler": "^5.23.4",
+        "@marko/translator-default": "^5.22.4",
         "app-module-path": "^2.2.0",
         "argly": "^1.2.0",
         "browser-refresh-client": "1.1.4",
@@ -68,8 +68,10 @@
         "components-browser.marko",
         "components.js",
         "env.js",
+        "index.d.ts",
         "index-browser.marko",
         "index.js",
         "node-require.js"
-    ]
+    ],
+    "types": "index.d.ts"
 }

package/src/core-tags/core/await/index.marko

@@ -0,0 +1,13 @@
+/**
+ * @template T
+ * @typedef {{
+ *   value?: T;
+ *   then?: Marko.Body<[Awaited<T>], void>;
+ *   catch?: Marko.Body<[unknown], void>;
+ *   placeholder?: Marko.Body<[], void>;
+ *   client-reorder?: boolean;
+ *   name?: string;
+ *   timeout?: number;
+ *   show-after?: string;
+ * }} Input
+ */