From 80b02c6f66bbe0b6d25011a3406a89fdc0f3b3ee Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Wed, 25 Sep 2024 13:10:53 +1200
Subject: [PATCH 01/15] feat: html streaming

---
 example/streaming/podlets/content.js |  45 +++++++
 example/streaming/podlets/footer.js  |  45 +++++++
 example/streaming/podlets/header.js  |  50 ++++++++
 example/streaming/podlets/menu.js    |  62 ++++++++++
 example/streaming/server.js          | 169 +++++++++++++++++++++++++++
 example/streaming/views/template.js  |  86 ++++++++++++++
 lib/layout.js                        |  15 +++
 lib/response-stream.js               |  37 ++++++
 lib/template.js                      |  86 ++++++++++++++
 package.json                         |   6 +-
 10 files changed, 598 insertions(+), 3 deletions(-)
 create mode 100644 example/streaming/podlets/content.js
 create mode 100644 example/streaming/podlets/footer.js
 create mode 100644 example/streaming/podlets/header.js
 create mode 100644 example/streaming/podlets/menu.js
 create mode 100644 example/streaming/server.js
 create mode 100644 example/streaming/views/template.js
 create mode 100644 lib/response-stream.js
 create mode 100644 lib/template.js

diff --git a/example/streaming/podlets/content.js b/example/streaming/podlets/content.js
new file mode 100644
index 00000000..5ebc8418
--- /dev/null
+++ b/example/streaming/podlets/content.js
@@ -0,0 +1,45 @@
+import Podlet from '@podium/podlet';
+import express from 'express';
+
+const podlet = new Podlet({
+    name: 'content',
+    version: Date.now().toString(),
+    pathname: '/',
+});
+
+podlet.css({ value: 'http://localhost:6103/css' });
+
+const app = express();
+
+app.use(podlet.middleware());
+
+app.get('/manifest.json', (req, res) => {
+    res.send(podlet);
+});
+
+app.get('/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+		.content {
+			border: 1px solid black;
+			border-radius: 5px;
+			width: 100%;
+			padding: 20px;
+			margin: 0;
+			margin-bottom: 20px;
+			box-sizing: border-box;
+		}
+	`);
+});
+
+app.get('/', (req, res) => {
+    res.send(`
+			<section class="content">
+				main content goes here
+			</section>	
+		`);
+});
+
+app.listen(6103, () => {
+    console.log(`content podlet server running at http://localhost:6103`);
+});
diff --git a/example/streaming/podlets/footer.js b/example/streaming/podlets/footer.js
new file mode 100644
index 00000000..f556e1db
--- /dev/null
+++ b/example/streaming/podlets/footer.js
@@ -0,0 +1,45 @@
+import Podlet from '@podium/podlet';
+import express from 'express';
+
+const podlet = new Podlet({
+    name: 'footer',
+    version: Date.now().toString(),
+    pathname: '/',
+});
+
+podlet.css({ value: 'http://localhost:6104/css' });
+
+const app = express();
+
+app.use(podlet.middleware());
+
+app.get('/manifest.json', (req, res) => {
+    res.send(podlet);
+});
+
+app.get('/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+		footer {
+			border: 1px solid black;
+			border-radius: 5px;
+			width: 100%;
+			padding: 20px;
+			margin: 0;
+			margin-bottom: 20px;
+			box-sizing: border-box;
+		}
+	`);
+});
+
+app.get('/', (req, res) => {
+    res.send(`
+			<footer>
+				footer content
+			</footer>	
+		`);
+});
+
+app.listen(6104, () => {
+    console.log(`footer podlet server running at http://localhost:6104`);
+});
diff --git a/example/streaming/podlets/header.js b/example/streaming/podlets/header.js
new file mode 100644
index 00000000..b2c98eb9
--- /dev/null
+++ b/example/streaming/podlets/header.js
@@ -0,0 +1,50 @@
+import Podlet from '@podium/podlet';
+import express from 'express';
+
+const podlet = new Podlet({
+    name: 'header',
+    version: Date.now().toString(),
+    pathname: '/',
+});
+
+podlet.css({ value: 'http://localhost:6101/css' });
+
+const app = express();
+
+app.use(podlet.middleware());
+
+app.get('/manifest.json', (req, res) => {
+    res.send(podlet);
+});
+
+app.get('/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+		header {
+			border: 1px solid black;
+			border-radius: 5px;
+			width: 100%;
+			padding: 20px;
+			margin: 0;
+			margin-bottom: 20px;
+			box-sizing: border-box;
+		}
+		header h1 {
+			text-align: center;
+			margin: 0;
+			padding: 0;
+		}
+	`);
+});
+
+app.get('/', (req, res) => {
+    res.send(`
+			<header>
+				<h1>Header</h1>
+			</header>	
+		`);
+});
+
+app.listen(6101, () => {
+    console.log(`header podlet server running at http://localhost:6101`);
+});
diff --git a/example/streaming/podlets/menu.js b/example/streaming/podlets/menu.js
new file mode 100644
index 00000000..d86db66e
--- /dev/null
+++ b/example/streaming/podlets/menu.js
@@ -0,0 +1,62 @@
+import Podlet from '@podium/podlet';
+import express from 'express';
+
+const podlet = new Podlet({
+    name: 'menu',
+    version: Date.now().toString(),
+    pathname: '/',
+});
+
+podlet.css({ value: 'http://localhost:6102/css' });
+
+const app = express();
+
+app.use(podlet.middleware());
+
+app.get('/manifest.json', (req, res) => {
+    res.send(podlet);
+});
+
+app.get('/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+		menu {
+			border: 1px solid black;
+			border-radius: 5px;
+			width: 100%;
+			padding: 10px;
+			margin: 0;
+			margin-bottom: 20px;
+			box-sizing: border-box;
+		}
+		menu ul {
+			list-style: none;
+			padding: 0;
+			margin: 0;
+			display: flex;
+			justify-content: space-evenly;
+			align-items: center;
+		}
+		menu ul li {
+			margin: 0;
+			padding: 0;
+		}
+	`);
+});
+
+app.get('/', (req, res) => {
+    res.send(`
+			<menu>
+				<ul>
+					<li><a href="/">Home</a></li>
+					<li><a href="/about">About</a></li>
+					<li><a href="/things">Things</a></li>
+					<li><a href="/stuff">Stuff</a></li>
+				</ul>
+			</menu>	
+		`);
+});
+
+app.listen(6102, () => {
+    console.log(`menu podlet server running at http://localhost:6102`);
+});
diff --git a/example/streaming/server.js b/example/streaming/server.js
new file mode 100644
index 00000000..0894a6b0
--- /dev/null
+++ b/example/streaming/server.js
@@ -0,0 +1,169 @@
+import express from 'express';
+import Layout from '../../lib/layout.js';
+import { template } from './views/template.js';
+
+const layout = new Layout({
+    pathname: '/foo',
+    logger: console,
+    name: 'demo',
+});
+
+// use our custom streaming template
+layout.view(template);
+
+const content = layout.client.register({
+    name: 'content',
+    uri: 'http://localhost:6103/manifest.json',
+});
+
+const header = layout.client.register({
+    name: 'header',
+    uri: 'http://localhost:6101/manifest.json',
+});
+
+const menu = layout.client.register({
+    name: 'menu',
+    uri: 'http://localhost:6102/manifest.json',
+});
+
+const footer = layout.client.register({
+    name: 'footer',
+    uri: 'http://localhost:6104/manifest.json',
+});
+
+layout.css({ value: '/css' });
+
+const app = express();
+
+app.use(layout.pathname(), layout.middleware());
+
+app.get('/foo/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+        @keyframes pulse {
+            0% {
+                background-color: #e0e0e0;
+            }
+            50% {
+                background-color: #f0f0f0;
+            }
+            100% {
+                background-color: #e0e0e0;
+            }
+        }
+        .skeleton {
+            width: 100%;
+            background-color: #e0e0e0;
+            border-radius: 5px;
+            animation: pulse 1.5s infinite ease-in-out;
+            margin: 0;
+			margin-bottom: 20px;
+			box-sizing: border-box;
+        }
+        .skeleton.header {
+            height:79px;
+        }
+        .skeleton.menu {
+            height:40px;
+        }
+        .skeleton.content {
+            height:60px;
+        }
+        .skeleton.footer {
+            height:60px;
+        }
+	`);
+});
+
+app.get(layout.pathname(), async (req, res) => {
+    const incoming = res.locals.podium;
+
+    incoming.view = {
+        title: 'Example streaming application',
+    };
+
+    const headerFetch = header.fetch(incoming);
+    const menuFetch = menu.fetch(incoming);
+    const contentFetch = content.fetch(incoming);
+    const footerFetch = footer.fetch(incoming);
+
+    incoming.hints.on('complete', async ({ js, css }) => {
+        // set the assets on httpincoming so that they are available in the document template
+        incoming.js = [...incoming.js, ...js];
+        incoming.css = [...incoming.css, ...css];
+
+        // set up the stream which will send the document template head
+        const stream = res.podiumStream();
+
+        // stream in the document body with slot placeholders for podlets
+        stream.send(`
+            <template shadowrootmode="open">
+                <link href="/foo/css" type="text/css" rel="stylesheet">
+                <div class="container">
+                    <div>
+                        <div>
+                            <slot name="header"><div class="skeleton header"></div></slot>
+                        </div>
+                    </div>
+                    <div>
+                        <div>
+                            <slot name="menu"><div class="skeleton menu"></div></slot>
+                        </div>
+                        <div>
+                            <slot name="content"><div class="skeleton content"></div></slot>
+                        </div>
+                    </div>
+                    <div>
+                        <div>
+                            <slot name="footer"><div class="skeleton footer"></div></slot>
+                        </div>
+                    </div>
+                </div>
+            </template>
+        `);
+
+        // fake 1 second delay
+        await new Promise((res) => setTimeout(res, 1000));
+
+        // stream in podlet content when available...
+        headerFetch.then((content) => {
+            stream.send(`<div slot="header">${content}</div>`);
+        });
+
+        await new Promise((res) => setTimeout(res, 1000));
+
+        menuFetch.then((content) => {
+            stream.send(`<div slot="menu">${content}</div>`);
+        });
+
+        await new Promise((res) => setTimeout(res, 1000));
+
+        contentFetch.then((content) => {
+            stream.send(`<div slot="content">${content}</div>`);
+        });
+
+        await new Promise((res) => setTimeout(res, 1000));
+
+        footerFetch.then((content) => {
+            stream.send(`<div slot="footer">${content}</div>`);
+        });
+
+        // close out the dom and the stream
+        await Promise.all([headerFetch, menuFetch, contentFetch, footerFetch]);
+        stream.done();
+    });
+});
+
+app.use(`${layout.pathname()}/assets`, express.static('assets'));
+
+// eslint-disable-next-line no-unused-vars
+app.use((error, req, res, next) => {
+    console.error(error);
+    res.status(500).send(
+        '<html><body><h1>Internal server error</h1></body></html>',
+    );
+});
+
+app.listen(6123, () => {
+    console.log(`layout server running at http://localhost:6123`);
+});
diff --git a/example/streaming/views/template.js b/example/streaming/views/template.js
new file mode 100644
index 00000000..6236b227
--- /dev/null
+++ b/example/streaming/views/template.js
@@ -0,0 +1,86 @@
+import * as utils from '@podium/utils';
+import { ResponseStream } from '../../../lib/response-stream.js';
+
+/**
+ * @param {import('@podium/utils').PodiumHttpIncoming} incoming Typically res.local.podium
+ * @param {string | import('./response-stream.js')} [body=''] HTML content for <body> or a writeable stream to write the template to
+ * @param {string} [head=''] HTML content for <head>
+ * @returns {string | undefined} HTML document as a string
+ */
+export const template = (incoming, body = '', head = '') => {
+    let scripts = incoming.js;
+    let styles = incoming.css;
+    const lang =
+        incoming.view.locale ||
+        incoming.context['podium-locale'] ||
+        incoming.context.locale ||
+        incoming.params?.locale ||
+        'en-US';
+
+    // backwards compatibility for scripts and styles
+    if (typeof incoming.js === 'string')
+        scripts = [{ type: 'default', value: incoming.js }];
+    if (typeof incoming.css === 'string')
+        styles = [{ type: 'text/css', value: incoming.css, rel: 'stylesheet' }];
+
+    const documentHeaders = /* html */ `<!doctype html>
+    <html lang="${lang}">
+        <head>
+            <meta charset="${
+                incoming.view.encoding ? incoming.view.encoding : 'utf-8'
+            }">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <meta http-equiv="X-UA-Compatible" content="IE=Edge">
+            ${styles.map(utils.buildLinkElement).join('\n        ')}
+            ${scripts
+                .filter(
+                    (script) =>
+                        typeof script !== 'string' &&
+                        script.strategy === 'beforeInteractive',
+                )
+                .map(utils.buildScriptElement)
+                .join('\n        ')}
+            <title>${incoming.view.title ? incoming.view.title : ''}</title>
+            ${head}
+        </head>
+        <body>`;
+
+    const documentTrailers = `${scripts
+        .filter(
+            (script) =>
+                typeof script === 'string' ||
+                script.strategy === 'afterInteractive' ||
+                !script.strategy,
+        )
+        .map(utils.buildScriptElement)
+        .join('\n        ')}
+    ${scripts
+        .filter(
+            (script) =>
+                typeof script !== 'string' && script.strategy === 'lazy',
+        )
+        .map(
+            (script) =>
+                `<script type="module">import("${
+                    typeof script !== 'string' ? script.value : script
+                }")</script>`,
+        )
+        .join('\n        ')}
+</body>
+</html>`;
+
+    // If body is a string, template behaves basically as before
+    if (!(body instanceof ResponseStream)) {
+        return `${documentHeaders}${body}${documentTrailers}`;
+    }
+
+    // If body is a response stream, template does streaming
+    // first wait for assets to be ready and then send the document head
+    body.send(documentHeaders);
+
+    // Once the developer hands back control to Podium, we send the document closing html
+    body.on('done', () => {
+        body.send(documentTrailers);
+        body.end();
+    });
+};
diff --git a/lib/layout.js b/lib/layout.js
index 761aea0d..02da3a7f 100644
--- a/lib/layout.js
+++ b/lib/layout.js
@@ -17,6 +17,7 @@ import Proxy from '@podium/proxy';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import fs from 'fs';
+import { ResponseStream } from './response-stream.js';
 
 // Re-export these types from @podium/client so folks can avoid
 // installing it just for types (and then getting out of sync
@@ -615,6 +616,20 @@ export default class PodiumLayout {
                 res.podiumSend = (data, ...args) =>
                     res.send(this.render(incoming, data, ...args));
 
+                // we add a new podiumStream method that sets up streaming and returns the stream
+                // object for the developer to work with
+                res.podiumStream = (...args) => {
+                    const responseStream = new ResponseStream();
+                    // pipe the readable response stream into the express writeable res stream
+                    // to set up streaming
+                    responseStream.pipe(res);
+                    // html template changed to accept body as either a string as before
+                    // or as in this case, a response stream object.
+                    this.#view(incoming, responseStream, ...args);
+                    // return the stream for the developer to work with
+                    return responseStream;
+                };
+
                 next();
             } catch (error) {
                 next(error);
diff --git a/lib/response-stream.js b/lib/response-stream.js
new file mode 100644
index 00000000..1d45638b
--- /dev/null
+++ b/lib/response-stream.js
@@ -0,0 +1,37 @@
+import { Readable } from 'node:stream';
+
+export class ResponseStream extends Readable {
+    constructor(options) {
+        super(options);
+        this.buffer = [];
+        this.isReading = false;
+    }
+
+    // Method to add data to the internal buffer
+    // This method simply adds data; the stream will request it when needed
+    send(data) {
+        this.buffer.push(data);
+        if (this.isReading) {
+            this.isReading = false;
+            this._read();
+        }
+    }
+
+    // _read method, automatically called by the stream when it wants more data
+    _read() {
+        if (this.buffer.length > 0) {
+            const chunk = this.buffer.shift(); // Get the next chunk from the buffer
+            this.push(chunk); // Push the chunk into the stream
+        } else {
+            this.isReading = true;
+        }
+    }
+
+    done() {
+        this.emit('done');
+    }
+
+    end() {
+        setTimeout(() => this.push(null), 0);
+    }
+}
diff --git a/lib/template.js b/lib/template.js
new file mode 100644
index 00000000..73e66841
--- /dev/null
+++ b/lib/template.js
@@ -0,0 +1,86 @@
+import * as utils from '@podium/utils';
+import { ResponseStream } from './response-stream.js';
+
+/**
+ * @param {import('@podium/utils').PodiumHttpIncoming} incoming Typically res.local.podium
+ * @param {string | import('./response-stream.js')} [body=''] HTML content for <body> or a writeable stream to write the template to
+ * @param {string} [head=''] HTML content for <head>
+ * @returns {string | undefined} HTML document as a string
+ */
+export const document = (incoming, body = '', head = '') => {
+    let scripts = incoming.js;
+    let styles = incoming.css;
+    const lang =
+        incoming.view.locale ||
+        incoming.context['podium-locale'] ||
+        incoming.context.locale ||
+        incoming.params?.locale ||
+        'en-US';
+
+    // backwards compatibility for scripts and styles
+    if (typeof incoming.js === 'string')
+        scripts = [{ type: 'default', value: incoming.js }];
+    if (typeof incoming.css === 'string')
+        styles = [{ type: 'text/css', value: incoming.css, rel: 'stylesheet' }];
+
+    const documentHeaders = /* html */ `<!doctype html>
+    <html lang="${lang}">
+        <head>
+            <meta charset="${
+                incoming.view.encoding ? incoming.view.encoding : 'utf-8'
+            }">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <meta http-equiv="X-UA-Compatible" content="IE=Edge">
+            ${styles.map(utils.buildLinkElement).join('\n        ')}
+            ${scripts
+                .filter(
+                    (script) =>
+                        typeof script !== 'string' &&
+                        script.strategy === 'beforeInteractive',
+                )
+                .map(utils.buildScriptElement)
+                .join('\n        ')}
+            <title>${incoming.view.title ? incoming.view.title : ''}</title>
+            ${head}
+        </head>
+        <body>`;
+
+    const documentTrailers = `${scripts
+        .filter(
+            (script) =>
+                typeof script === 'string' ||
+                script.strategy === 'afterInteractive' ||
+                !script.strategy,
+        )
+        .map(utils.buildScriptElement)
+        .join('\n        ')}
+    ${scripts
+        .filter(
+            (script) =>
+                typeof script !== 'string' && script.strategy === 'lazy',
+        )
+        .map(
+            (script) =>
+                `<script type="module">import("${
+                    typeof script !== 'string' ? script.value : script
+                }")</script>`,
+        )
+        .join('\n        ')}
+</body>
+</html>`;
+
+    // If body is a string, template behaves basically as before
+    if (!(body instanceof ResponseStream)) {
+        return `${documentHeaders}${body}${documentTrailers}`;
+    }
+
+    // If body is a response stream, template does streaming
+    // first wait for assets to be ready and then send the document head
+    body.send(documentHeaders);
+
+    // Once the developer hands back control to Podium, we send the document closing html
+    body.on('done', () => {
+        body.send(documentTrailers);
+        body.end();
+    });
+};
diff --git a/package.json b/package.json
index 56a07d4c..bc6f20ff 100644
--- a/package.json
+++ b/package.json
@@ -41,18 +41,18 @@
   },
   "dependencies": {
     "@metrics/client": "2.5.3",
-    "@podium/client": "5.2.0-next.2",
+    "@podium/client": "5.2.0-next.4",
     "@podium/context": "5.0.27",
     "@podium/proxy": "5.0.26",
     "@podium/schemas": "5.0.6",
-    "@podium/utils": "5.2.0",
+    "@podium/utils": "5.3.1",
     "abslog": "2.4.4",
     "ajv": "8.17.1",
     "lodash.merge": "4.6.2",
     "objobj": "1.0.0"
   },
   "devDependencies": {
-    "@podium/podlet": "5.2.0-next.3",
+    "@podium/podlet": "5.2.0-next.4",
     "@podium/test-utils": "3.0.9",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/commit-analyzer": "11.1.0",

From 2c2b292539bd27bb31df1ed4eb0746afd43e2f1e Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Wed, 25 Sep 2024 16:50:16 +1200
Subject: [PATCH 02/15] refactor: remove the need to rewrite html templates

---
 example/streaming/server.js         |  4 --
 example/streaming/views/template.js | 86 -----------------------------
 lib/layout.js                       | 18 +++++-
 lib/template.js                     | 86 -----------------------------
 4 files changed, 17 insertions(+), 177 deletions(-)
 delete mode 100644 example/streaming/views/template.js
 delete mode 100644 lib/template.js

diff --git a/example/streaming/server.js b/example/streaming/server.js
index 0894a6b0..f10843bf 100644
--- a/example/streaming/server.js
+++ b/example/streaming/server.js
@@ -1,6 +1,5 @@
 import express from 'express';
 import Layout from '../../lib/layout.js';
-import { template } from './views/template.js';
 
 const layout = new Layout({
     pathname: '/foo',
@@ -8,9 +7,6 @@ const layout = new Layout({
     name: 'demo',
 });
 
-// use our custom streaming template
-layout.view(template);
-
 const content = layout.client.register({
     name: 'content',
     uri: 'http://localhost:6103/manifest.json',
diff --git a/example/streaming/views/template.js b/example/streaming/views/template.js
deleted file mode 100644
index 6236b227..00000000
--- a/example/streaming/views/template.js
+++ /dev/null
@@ -1,86 +0,0 @@
-import * as utils from '@podium/utils';
-import { ResponseStream } from '../../../lib/response-stream.js';
-
-/**
- * @param {import('@podium/utils').PodiumHttpIncoming} incoming Typically res.local.podium
- * @param {string | import('./response-stream.js')} [body=''] HTML content for <body> or a writeable stream to write the template to
- * @param {string} [head=''] HTML content for <head>
- * @returns {string | undefined} HTML document as a string
- */
-export const template = (incoming, body = '', head = '') => {
-    let scripts = incoming.js;
-    let styles = incoming.css;
-    const lang =
-        incoming.view.locale ||
-        incoming.context['podium-locale'] ||
-        incoming.context.locale ||
-        incoming.params?.locale ||
-        'en-US';
-
-    // backwards compatibility for scripts and styles
-    if (typeof incoming.js === 'string')
-        scripts = [{ type: 'default', value: incoming.js }];
-    if (typeof incoming.css === 'string')
-        styles = [{ type: 'text/css', value: incoming.css, rel: 'stylesheet' }];
-
-    const documentHeaders = /* html */ `<!doctype html>
-    <html lang="${lang}">
-        <head>
-            <meta charset="${
-                incoming.view.encoding ? incoming.view.encoding : 'utf-8'
-            }">
-            <meta name="viewport" content="width=device-width, initial-scale=1">
-            <meta http-equiv="X-UA-Compatible" content="IE=Edge">
-            ${styles.map(utils.buildLinkElement).join('\n        ')}
-            ${scripts
-                .filter(
-                    (script) =>
-                        typeof script !== 'string' &&
-                        script.strategy === 'beforeInteractive',
-                )
-                .map(utils.buildScriptElement)
-                .join('\n        ')}
-            <title>${incoming.view.title ? incoming.view.title : ''}</title>
-            ${head}
-        </head>
-        <body>`;
-
-    const documentTrailers = `${scripts
-        .filter(
-            (script) =>
-                typeof script === 'string' ||
-                script.strategy === 'afterInteractive' ||
-                !script.strategy,
-        )
-        .map(utils.buildScriptElement)
-        .join('\n        ')}
-    ${scripts
-        .filter(
-            (script) =>
-                typeof script !== 'string' && script.strategy === 'lazy',
-        )
-        .map(
-            (script) =>
-                `<script type="module">import("${
-                    typeof script !== 'string' ? script.value : script
-                }")</script>`,
-        )
-        .join('\n        ')}
-</body>
-</html>`;
-
-    // If body is a string, template behaves basically as before
-    if (!(body instanceof ResponseStream)) {
-        return `${documentHeaders}${body}${documentTrailers}`;
-    }
-
-    // If body is a response stream, template does streaming
-    // first wait for assets to be ready and then send the document head
-    body.send(documentHeaders);
-
-    // Once the developer hands back control to Podium, we send the document closing html
-    body.on('done', () => {
-        body.send(documentTrailers);
-        body.end();
-    });
-};
diff --git a/lib/layout.js b/lib/layout.js
index 02da3a7f..04f32a5b 100644
--- a/lib/layout.js
+++ b/lib/layout.js
@@ -625,7 +625,23 @@ export default class PodiumLayout {
                     responseStream.pipe(res);
                     // html template changed to accept body as either a string as before
                     // or as in this case, a response stream object.
-                    this.#view(incoming, responseStream, ...args);
+                    const splitToken = `<!--split-token-->`;
+                    const html = this.#view(incoming, splitToken, ...args);
+                    const templatePieces = html.split(splitToken);
+                    const header = templatePieces[0];
+                    const footer = templatePieces[1];
+
+                    console.log(header);
+                    console.log(footer);
+
+
+                    responseStream.send(header);
+
+                    // Once the developer hands back control to Podium, we send the document closing html
+                    responseStream.on('done', () => {
+                        responseStream.send(footer);
+                        responseStream.end();
+                    });
                     // return the stream for the developer to work with
                     return responseStream;
                 };
diff --git a/lib/template.js b/lib/template.js
deleted file mode 100644
index 73e66841..00000000
--- a/lib/template.js
+++ /dev/null
@@ -1,86 +0,0 @@
-import * as utils from '@podium/utils';
-import { ResponseStream } from './response-stream.js';
-
-/**
- * @param {import('@podium/utils').PodiumHttpIncoming} incoming Typically res.local.podium
- * @param {string | import('./response-stream.js')} [body=''] HTML content for <body> or a writeable stream to write the template to
- * @param {string} [head=''] HTML content for <head>
- * @returns {string | undefined} HTML document as a string
- */
-export const document = (incoming, body = '', head = '') => {
-    let scripts = incoming.js;
-    let styles = incoming.css;
-    const lang =
-        incoming.view.locale ||
-        incoming.context['podium-locale'] ||
-        incoming.context.locale ||
-        incoming.params?.locale ||
-        'en-US';
-
-    // backwards compatibility for scripts and styles
-    if (typeof incoming.js === 'string')
-        scripts = [{ type: 'default', value: incoming.js }];
-    if (typeof incoming.css === 'string')
-        styles = [{ type: 'text/css', value: incoming.css, rel: 'stylesheet' }];
-
-    const documentHeaders = /* html */ `<!doctype html>
-    <html lang="${lang}">
-        <head>
-            <meta charset="${
-                incoming.view.encoding ? incoming.view.encoding : 'utf-8'
-            }">
-            <meta name="viewport" content="width=device-width, initial-scale=1">
-            <meta http-equiv="X-UA-Compatible" content="IE=Edge">
-            ${styles.map(utils.buildLinkElement).join('\n        ')}
-            ${scripts
-                .filter(
-                    (script) =>
-                        typeof script !== 'string' &&
-                        script.strategy === 'beforeInteractive',
-                )
-                .map(utils.buildScriptElement)
-                .join('\n        ')}
-            <title>${incoming.view.title ? incoming.view.title : ''}</title>
-            ${head}
-        </head>
-        <body>`;
-
-    const documentTrailers = `${scripts
-        .filter(
-            (script) =>
-                typeof script === 'string' ||
-                script.strategy === 'afterInteractive' ||
-                !script.strategy,
-        )
-        .map(utils.buildScriptElement)
-        .join('\n        ')}
-    ${scripts
-        .filter(
-            (script) =>
-                typeof script !== 'string' && script.strategy === 'lazy',
-        )
-        .map(
-            (script) =>
-                `<script type="module">import("${
-                    typeof script !== 'string' ? script.value : script
-                }")</script>`,
-        )
-        .join('\n        ')}
-</body>
-</html>`;
-
-    // If body is a string, template behaves basically as before
-    if (!(body instanceof ResponseStream)) {
-        return `${documentHeaders}${body}${documentTrailers}`;
-    }
-
-    // If body is a response stream, template does streaming
-    // first wait for assets to be ready and then send the document head
-    body.send(documentHeaders);
-
-    // Once the developer hands back control to Podium, we send the document closing html
-    body.on('done', () => {
-        body.send(documentTrailers);
-        body.end();
-    });
-};

From fa708b2d526ae0a5dcd5131dc9ccd6672b1a6b02 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Wed, 25 Sep 2024 16:53:16 +1200
Subject: [PATCH 03/15] chore: remove console logs and add comments

---
 lib/layout.js | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/lib/layout.js b/lib/layout.js
index 04f32a5b..4391adf6 100644
--- a/lib/layout.js
+++ b/lib/layout.js
@@ -623,18 +623,16 @@ export default class PodiumLayout {
                     // pipe the readable response stream into the express writeable res stream
                     // to set up streaming
                     responseStream.pipe(res);
-                    // html template changed to accept body as either a string as before
-                    // or as in this case, a response stream object.
+
+                    // call our document template, injecting a token we can use to split the template
+                    // into header and footer
                     const splitToken = `<!--split-token-->`;
                     const html = this.#view(incoming, splitToken, ...args);
                     const templatePieces = html.split(splitToken);
                     const header = templatePieces[0];
                     const footer = templatePieces[1];
 
-                    console.log(header);
-                    console.log(footer);
-
-
+                    // send the header right away
                     responseStream.send(header);
 
                     // Once the developer hands back control to Podium, we send the document closing html

From 5b91cb7f379a30f75702d818408d48f222436b93 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Wed, 25 Sep 2024 17:14:52 +1200
Subject: [PATCH 04/15] chore: add simple server example

---
 .../{server.js => server-advanced.js}         |  0
 example/streaming/server-simple.js            | 91 +++++++++++++++++++
 2 files changed, 91 insertions(+)
 rename example/streaming/{server.js => server-advanced.js} (100%)
 create mode 100644 example/streaming/server-simple.js

diff --git a/example/streaming/server.js b/example/streaming/server-advanced.js
similarity index 100%
rename from example/streaming/server.js
rename to example/streaming/server-advanced.js
diff --git a/example/streaming/server-simple.js b/example/streaming/server-simple.js
new file mode 100644
index 00000000..32a3af03
--- /dev/null
+++ b/example/streaming/server-simple.js
@@ -0,0 +1,91 @@
+import express from 'express';
+import Layout from '../../lib/layout.js';
+
+const layout = new Layout({
+    pathname: '/foo',
+    logger: console,
+    name: 'demo',
+});
+
+const content = layout.client.register({
+    name: 'content',
+    uri: 'http://localhost:6103/manifest.json',
+});
+
+const header = layout.client.register({
+    name: 'header',
+    uri: 'http://localhost:6101/manifest.json',
+});
+
+const menu = layout.client.register({
+    name: 'menu',
+    uri: 'http://localhost:6102/manifest.json',
+});
+
+const footer = layout.client.register({
+    name: 'footer',
+    uri: 'http://localhost:6104/manifest.json',
+});
+
+layout.css({ value: '/css' });
+
+const app = express();
+
+app.use(layout.pathname(), layout.middleware());
+
+app.get(layout.pathname(), async (req, res) => {
+    const incoming = res.locals.podium;
+
+    incoming.view = {
+        title: 'Example streaming application',
+    };
+
+    const headerFetch = header.fetch(incoming);
+    const menuFetch = menu.fetch(incoming);
+    const contentFetch = content.fetch(incoming);
+    const footerFetch = footer.fetch(incoming);
+
+    incoming.hints.on('complete', async ({ js, css }) => {
+        // set the assets on httpincoming so that they are available in the document template
+        incoming.js = js;
+        incoming.css = css;
+
+        // set up the stream which will send the document template head
+        const stream = res.podiumStream();
+
+        // pretend the podlets are slow to load
+        await new Promise((res) => setTimeout(res, 3000));
+
+        const [header, menu, content, footer] = await Promise.all([
+            headerFetch,
+            menuFetch,
+            contentFetch,
+            footerFetch,
+        ]);
+
+        // stream in the document body with slot placeholders for podlets
+        stream.send(`
+            <div class="container">
+                <div>${header}</div>
+                <div>
+                    <div>${menu}</div>
+                    <div>${content}</div>
+                </div>
+                <div>${footer}</div>
+            </div>
+        `);
+        stream.done();
+    });
+});
+
+// eslint-disable-next-line no-unused-vars
+app.use((error, req, res, next) => {
+    console.error(error);
+    res.status(500).send(
+        '<html><body><h1>Internal server error</h1></body></html>',
+    );
+});
+
+app.listen(6123, () => {
+    console.log(`layout server running at http://localhost:6123`);
+});

From 4618d552867ddbc867eb7952840ec8fbd9dee573 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Wed, 25 Sep 2024 17:18:51 +1200
Subject: [PATCH 05/15] test: fix test snapshot

---
 tap-snapshots/tests/layout.test.js.test.cjs | 28 ++++++++++-----------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/tap-snapshots/tests/layout.test.js.test.cjs b/tap-snapshots/tests/layout.test.js.test.cjs
index c57230aa..b6a95f6e 100644
--- a/tap-snapshots/tests/layout.test.js.test.cjs
+++ b/tap-snapshots/tests/layout.test.js.test.cjs
@@ -7,21 +7,19 @@
 'use strict'
 exports[`tests/layout.test.js > TAP > Layout() - rendering using a string - with assets > must match snapshot 1`] = `
 <!doctype html>
-<html lang="en-US">
-    <head>
-        <meta charset="utf-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1">
-        <meta http-equiv="X-UA-Compatible" content="IE=Edge">
-        <link href="http://url.com/some/css" type="text/css" rel="stylesheet">
-        
-        <title>awesome page</title>
-        extra head stuff
-    </head>
-    <body>
-        <div>should be wrapped in a doc</div>
-        <script src="http://url.com/some/js"></script>
-        
-    </body>
+    <html lang="en-US">
+        <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <meta http-equiv="X-UA-Compatible" content="IE=Edge">
+            <link href="http://url.com/some/css" type="text/css" rel="stylesheet">
+            
+            <title>awesome page</title>
+            extra head stuff
+        </head>
+        <body><div>should be wrapped in a doc</div><script src="http://url.com/some/js"></script>
+    
+</body>
 </html>
 `
 

From 5a575a851a3f0af27f582f0ba8f3a091a9f56856 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Wed, 25 Sep 2024 17:24:37 +1200
Subject: [PATCH 06/15] test: set snapshot back again

---
 tap-snapshots/tests/layout.test.js.test.cjs | 28 +++++++++++----------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/tap-snapshots/tests/layout.test.js.test.cjs b/tap-snapshots/tests/layout.test.js.test.cjs
index b6a95f6e..c57230aa 100644
--- a/tap-snapshots/tests/layout.test.js.test.cjs
+++ b/tap-snapshots/tests/layout.test.js.test.cjs
@@ -7,19 +7,21 @@
 'use strict'
 exports[`tests/layout.test.js > TAP > Layout() - rendering using a string - with assets > must match snapshot 1`] = `
 <!doctype html>
-    <html lang="en-US">
-        <head>
-            <meta charset="utf-8">
-            <meta name="viewport" content="width=device-width, initial-scale=1">
-            <meta http-equiv="X-UA-Compatible" content="IE=Edge">
-            <link href="http://url.com/some/css" type="text/css" rel="stylesheet">
-            
-            <title>awesome page</title>
-            extra head stuff
-        </head>
-        <body><div>should be wrapped in a doc</div><script src="http://url.com/some/js"></script>
-    
-</body>
+<html lang="en-US">
+    <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta http-equiv="X-UA-Compatible" content="IE=Edge">
+        <link href="http://url.com/some/css" type="text/css" rel="stylesheet">
+        
+        <title>awesome page</title>
+        extra head stuff
+    </head>
+    <body>
+        <div>should be wrapped in a doc</div>
+        <script src="http://url.com/some/js"></script>
+        
+    </body>
 </html>
 `
 

From 858a50f5ec531479bc5286f0d5da77f51997ba74 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Wed, 25 Sep 2024 17:26:22 +1200
Subject: [PATCH 07/15] chore: ignore type errors

---
 lib/layout.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lib/layout.js b/lib/layout.js
index 4391adf6..8b469017 100644
--- a/lib/layout.js
+++ b/lib/layout.js
@@ -575,7 +575,9 @@ export default class PodiumLayout {
         incoming.css = [...this.cssRoute];
         incoming.js = [...this.jsRoute];
 
+        // @ts-ignore
         if (context) await this.context.process(incoming);
+        // @ts-ignore
         if (proxy) await this.httpProxy.process(incoming);
 
         return incoming;

From ada68129e0fa2fe97182de9403ef1013b569f786 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Thu, 26 Sep 2024 18:28:35 +1200
Subject: [PATCH 08/15] docs: update docs and add tests

---
 README.md            |  38 +++++++++++++
 fixup.js             |   2 +
 tests/layout.test.js | 130 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 170 insertions(+)

diff --git a/README.md b/README.md
index 260e9a05..b8fa120c 100644
--- a/README.md
+++ b/README.md
@@ -613,6 +613,44 @@ app.get(layout.pathname(), (req, res) => {
 });
 ```
 
+### res.podiumStream(...templateArguments)
+
+Method on the `http.ServerResponse` object for streaming HTML to the browser. This function returns a `ResponseStream` object that can then be used to push out HTML to the browser in chunks using its .send() function. Once streaming is finished, the .done() function must be called to close the stream.
+
+```js
+const stream = res.podiumStream();
+stream.send(`<div>HTML chunk 1</div>`);
+stream.send(`<div>HTML chunk 2</div>`);
+stream.done();
+```
+
+The Podium document template will still be used. When you call res.podiumStream(), the document head will be sent to the browser immediately. Once the .done() function is called, the closing part of the template will be sent before the stream is closed out.
+
+Note that any arguments passed to .podiumStream(...args) will be passed on to the layout's document template.
+
+**Working with assets**
+
+When working with assets, its important to wait for podlets to have sent their assets to the layout via 103 early hints. Use the incoming.hints `complete` event for this. Wait for assets to be ready, set assets on the incoming object and then call res.podiumStream.
+
+```js
+const incoming = res.locals.podium;
+const headerFetch = p1Client.fetch(incoming);
+const footerFetch = p2Client.fetch(incoming);
+
+incoming.hints.on('complete', async ({ js, css }) => {
+    incoming.js = js;
+    incoming.css = css;
+
+    const stream = res.podiumStream();
+    const [header, footer] = await Promise.all([
+        headerFetch,
+        footerFetch,
+    ]);
+    stream.send(`<header>${header}</header>...<footer>${footer}</footer>`);
+    stream.done();
+});
+```
+
 ### .client
 
 A property that exposes an instance of the [@podium/client] for fetching content
diff --git a/fixup.js b/fixup.js
index 581e41fe..0bd1c290 100755
--- a/fixup.js
+++ b/fixup.js
@@ -6,10 +6,12 @@ let module = path.join(process.cwd(), 'types', 'layout.d.ts');
 fs.writeFileSync(
     module,
     /* ts */ `
+import { ResponseStream } from './lib/response-stream.js';
 declare global {
   namespace Express {
     export interface Response {
       podiumSend(fragment: string, ...args: unknown[]): Response;
+      podiumStream(...args: unknown[]): ResponseStream;
     }
   }
 }
diff --git a/tests/layout.test.js b/tests/layout.test.js
index cd1fa3fe..4bd7b29f 100644
--- a/tests/layout.test.js
+++ b/tests/layout.test.js
@@ -731,3 +731,133 @@ tap.test('Proxy - builds correct proxy url', async (t) => {
     s1.stop();
     s2.stop();
 });
+
+const podlet = (name, port, assets) => {
+    const app = express();
+    const podlet = new Podlet({
+        name,
+        version: '1.0.0',
+        pathname: '/',
+    });
+    if (assets && assets.js) {
+        podlet.js({ value: assets.js, type: 'module' });
+    }
+    if (assets && assets.css) {
+        podlet.css({ value: assets.css, rel: 'stylesheet', type: 'text/css' });
+    }
+    app.use(podlet.middleware());
+    app.get('/manifest.json', (req, res) => res.send(podlet));
+    app.get(podlet.content(), (req, res) => res.send(`<div>${name}</div>`));
+    return stoppable(app.listen(port), 0);
+};
+
+tap.test('HTTP Streaming', async (t) => {
+    const p1 = podlet('podlet-registered-name-1', 5053);
+    const p2 = podlet('podlet-registered-name-2', 5054);
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5053/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5054/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+
+        const stream = res.podiumStream();
+
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5064), 0);
+
+    const result = await fetch('http://0.0.0.0:5064');
+    const html = await result.text();
+    t.match(html, /<html lang="en-US">/);
+    t.match(html, /<\/html>/);
+    t.match(
+        html,
+        /<div><div>podlet-registered-name-1<\/div><\/div><div><div>podlet-registered-name-2<\/div><\/div>/,
+        '',
+    );
+
+    p1.stop();
+    p2.stop();
+    l1.stop();
+});
+
+tap.test('HTTP Streaming - with assets', async (t) => {
+    const p1 = podlet('podlet-registered-name-1', 5073, {
+        js: '/podlet-registered-name-1.js',
+        css: '/podlet-registered-name-1.css',
+    });
+    const p2 = podlet('podlet-registered-name-2', 5074, {
+        js: '/podlet-registered-name-2.js',
+        css: '/podlet-registered-name-2.css',
+    });
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5073/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5074/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+
+        incoming.hints.on('complete', async ({ js, css }) => {
+            incoming.js = js;
+            incoming.css = css;
+            const stream = res.podiumStream();
+            const [p1Content, p2Content] = await Promise.all([
+                p1fetch,
+                p2fetch,
+            ]);
+            stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+            stream.done();
+        });
+    });
+    const l1 = stoppable(app.listen(5075), 0);
+
+    const result = await fetch('http://0.0.0.0:5075');
+    const html = await result.text();
+
+    t.match(html, /<html lang="en-US">/);
+    t.match(
+        html,
+        /<link href="\/podlet-registered-name-1.css" type="text\/css" rel="stylesheet">/,
+    );
+    t.match(
+        html,
+        /<link href="\/podlet-registered-name-2.css" type="text\/css" rel="stylesheet">/,
+    );
+    t.match(
+        html,
+        /<div><div>podlet-registered-name-1<\/div><\/div><div><div>podlet-registered-name-2<\/div><\/div>/,
+        '',
+    );
+    t.match(html, /<script src="\/podlet-registered-name-1.js" type="module">/);
+    t.match(html, /<script src="\/podlet-registered-name-2.js" type="module">/);
+    t.match(html, /<\/html>/);
+
+    p1.stop();
+    p2.stop();
+    l1.stop();
+});

From b75d0d48dd7f590d52efa5c98fc2681669136fd7 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Thu, 26 Sep 2024 18:47:24 +1200
Subject: [PATCH 09/15] chore: update @podium/test-utils

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index bc6f20ff..49b479d5 100644
--- a/package.json
+++ b/package.json
@@ -53,7 +53,7 @@
   },
   "devDependencies": {
     "@podium/podlet": "5.2.0-next.4",
-    "@podium/test-utils": "3.0.9",
+    "@podium/test-utils": "3.0.10",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/commit-analyzer": "11.1.0",
     "@semantic-release/git": "10.0.1",

From 651eee0aec392e49dcbe07976edc629ff2cdc15e Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Mon, 11 Nov 2024 15:16:03 +1300
Subject: [PATCH 10/15] refactor: drop early hints, use link header assets

---
 tests/layout.test.js | 49 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 37 insertions(+), 12 deletions(-)

diff --git a/tests/layout.test.js b/tests/layout.test.js
index 4bd7b29f..a8eedbcf 100644
--- a/tests/layout.test.js
+++ b/tests/layout.test.js
@@ -819,20 +819,45 @@ tap.test('HTTP Streaming - with assets', async (t) => {
     app.use(layout.middleware());
     app.get(layout.pathname(), async (req, res) => {
         const incoming = res.locals.podium;
-        const p1fetch = p1Client.fetch(incoming);
-        const p2fetch = p2Client.fetch(incoming);
+        const p1fetch = p1Client.stream(incoming);
+        const p2fetch = p2Client.stream(incoming);
 
-        incoming.hints.on('complete', async ({ js, css }) => {
-            incoming.js = js;
-            incoming.css = css;
-            const stream = res.podiumStream();
-            const [p1Content, p2Content] = await Promise.all([
-                p1fetch,
-                p2fetch,
-            ]);
-            stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
-            stream.done();
+        p1fetch.once('beforeStream', ({ js, css }) => {
+            incoming.js.push(...js);
+            incoming.css.push(...css);
+        });
+        p2fetch.once('beforeStream', ({ js, css }) => {
+            incoming.js.push(...js);
+            incoming.css.push(...css);
         });
+
+        await new Promise((resolve) => {
+            function checkForAssets() {
+                if (incoming.js.length === 2 || incoming.css.length === 2) {
+                    resolve(true);
+                } else {
+                    setTimeout(checkForAssets, 100);
+                }
+            }
+            checkForAssets();
+        });
+
+        const stream = res.podiumStream();
+
+        const chunks1 = [];
+        for await (const chunk of p1fetch) {
+            chunks1.push(chunk);
+        }
+        const p1Content = Buffer.concat(chunks1).toString();
+
+        const chunks2 = [];
+        for await (const chunk of p2fetch) {
+            chunks2.push(chunk);
+        }
+        const p2Content = Buffer.concat(chunks2).toString();
+
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+        stream.done();
     });
     const l1 = stoppable(app.listen(5075), 0);
 

From 7a9a1648a2a5c33e2867970c025fc029c8f86ac7 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Mon, 11 Nov 2024 16:36:20 +1300
Subject: [PATCH 11/15] refactor(examples): rework examples to match latest
 podium

---
 example/streaming/podlets/content.js |   9 +-
 example/streaming/podlets/footer.js  |   9 +-
 example/streaming/podlets/header.js  |   9 +-
 example/streaming/podlets/menu.js    |  10 +-
 example/streaming/server-advanced.js | 133 +++++++++++++++------------
 5 files changed, 104 insertions(+), 66 deletions(-)

diff --git a/example/streaming/podlets/content.js b/example/streaming/podlets/content.js
index 5ebc8418..9c70c136 100644
--- a/example/streaming/podlets/content.js
+++ b/example/streaming/podlets/content.js
@@ -32,8 +32,13 @@ app.get('/css', (req, res) => {
 	`);
 });
 
-app.get('/', (req, res) => {
-    res.send(`
+app.get('/', async (req, res) => {
+    // send headers
+    res.sendHeaders();
+
+    await new Promise((res) => setTimeout(res, 2200));
+
+    res.podiumSend(`
 			<section class="content">
 				main content goes here
 			</section>	
diff --git a/example/streaming/podlets/footer.js b/example/streaming/podlets/footer.js
index f556e1db..d239460e 100644
--- a/example/streaming/podlets/footer.js
+++ b/example/streaming/podlets/footer.js
@@ -32,8 +32,13 @@ app.get('/css', (req, res) => {
 	`);
 });
 
-app.get('/', (req, res) => {
-    res.send(`
+app.get('/', async (req, res) => {
+    // send headers
+    res.sendHeaders();
+
+    await new Promise((res) => setTimeout(res, 1250));
+
+    res.podiumSend(`
 			<footer>
 				footer content
 			</footer>	
diff --git a/example/streaming/podlets/header.js b/example/streaming/podlets/header.js
index b2c98eb9..b7fec50c 100644
--- a/example/streaming/podlets/header.js
+++ b/example/streaming/podlets/header.js
@@ -37,8 +37,13 @@ app.get('/css', (req, res) => {
 	`);
 });
 
-app.get('/', (req, res) => {
-    res.send(`
+app.get('/', async (req, res) => {
+    // send headers
+    res.sendHeaders();
+
+    await new Promise((res) => setTimeout(res, 3500));
+
+    res.podiumSend(`
 			<header>
 				<h1>Header</h1>
 			</header>	
diff --git a/example/streaming/podlets/menu.js b/example/streaming/podlets/menu.js
index d86db66e..fcb25b89 100644
--- a/example/streaming/podlets/menu.js
+++ b/example/streaming/podlets/menu.js
@@ -44,8 +44,14 @@ app.get('/css', (req, res) => {
 	`);
 });
 
-app.get('/', (req, res) => {
-    res.send(`
+app.get('/', async (req, res) => {
+    // send headers
+    res.sendHeaders();
+
+		// imagine this is your slow database call
+    await new Promise((res) => setTimeout(res, 1000));
+
+    res.podiumSend(`
 			<menu>
 				<ul>
 					<li><a href="/">Home</a></li>
diff --git a/example/streaming/server-advanced.js b/example/streaming/server-advanced.js
index f10843bf..220b056e 100644
--- a/example/streaming/server-advanced.js
+++ b/example/streaming/server-advanced.js
@@ -1,10 +1,14 @@
 import express from 'express';
 import Layout from '../../lib/layout.js';
+import { timeout } from 'tap';
 
 const layout = new Layout({
     pathname: '/foo',
     logger: console,
     name: 'demo',
+    client: {
+        timeout: 5000,
+    }
 });
 
 const content = layout.client.register({
@@ -78,76 +82,89 @@ app.get(layout.pathname(), async (req, res) => {
         title: 'Example streaming application',
     };
 
-    const headerFetch = header.fetch(incoming);
-    const menuFetch = menu.fetch(incoming);
-    const contentFetch = content.fetch(incoming);
-    const footerFetch = footer.fetch(incoming);
-
-    incoming.hints.on('complete', async ({ js, css }) => {
-        // set the assets on httpincoming so that they are available in the document template
-        incoming.js = [...incoming.js, ...js];
-        incoming.css = [...incoming.css, ...css];
+    // we start a stream for each podlet (instead of a fetch)
+    // this allows us to receive podlet meta including assets before the podlet body
+    const headerFetch = header.stream(incoming);
+    const menuFetch = menu.stream(incoming);
+    const contentFetch = content.stream(incoming);
+    const footerFetch = footer.stream(incoming);
+
+    // we set up listeners to get notified with podlet metadata is ready
+    // this will occur before the podlet body content is sent.
+    headerFetch.once('beforeStream', ({ js, css }) => {
+        incoming.css.push(...css);
+    });
+    menuFetch.once('beforeStream', ({ js, css }) => {
+        incoming.css.push(...css);
+    });
+    contentFetch.once('beforeStream', ({ js, css }) => {
+        incoming.css.push(...css);
+    });
+    footerFetch.once('beforeStream', ({ js, css }) => {
+        incoming.css.push(...css);
+    });
 
-        // set up the stream which will send the document template head
-        const stream = res.podiumStream();
+    // we use an awkward wait function to ensure that all the assets are loaded
+    // before we start the stream (and flush the document head)
+    await new Promise((resolve) => {
+        function checkForAssets() {
+            if (incoming.css.length >= 5) {
+                resolve(true);
+            } else {
+                setTimeout(checkForAssets, 100);
+            }
+        }
+        checkForAssets();
+    });
 
-        // stream in the document body with slot placeholders for podlets
-        stream.send(`
-            <template shadowrootmode="open">
-                <link href="/foo/css" type="text/css" rel="stylesheet">
-                <div class="container">
+    // we kick off the stream, this automatically sends the document opening html including everything in the <head>
+    // as well as the openning <body> tag.
+    const stream = res.podiumStream();
+
+    // stream in the document body with slot skeleton screen placeholders for podlets
+    // these will be replaced once the podlets are loaded
+    stream.send(`
+        <template shadowrootmode="open">
+            <link href="/foo/css" type="text/css" rel="stylesheet">
+            <div class="container">
+                <div>
                     <div>
-                        <div>
-                            <slot name="header"><div class="skeleton header"></div></slot>
-                        </div>
+                        <slot name="header"><div class="skeleton header"></div></slot>
                     </div>
+                </div>
+                <div>
                     <div>
-                        <div>
-                            <slot name="menu"><div class="skeleton menu"></div></slot>
-                        </div>
-                        <div>
-                            <slot name="content"><div class="skeleton content"></div></slot>
-                        </div>
+                        <slot name="menu"><div class="skeleton menu"></div></slot>
                     </div>
                     <div>
-                        <div>
-                            <slot name="footer"><div class="skeleton footer"></div></slot>
-                        </div>
+                        <slot name="content"><div class="skeleton content"></div></slot>
                     </div>
                 </div>
-            </template>
-        `);
-
-        // fake 1 second delay
-        await new Promise((res) => setTimeout(res, 1000));
-
-        // stream in podlet content when available...
-        headerFetch.then((content) => {
-            stream.send(`<div slot="header">${content}</div>`);
-        });
-
-        await new Promise((res) => setTimeout(res, 1000));
-
-        menuFetch.then((content) => {
-            stream.send(`<div slot="menu">${content}</div>`);
-        });
-
-        await new Promise((res) => setTimeout(res, 1000));
-
-        contentFetch.then((content) => {
-            stream.send(`<div slot="content">${content}</div>`);
-        });
+                <div>
+                    <div>
+                        <slot name="footer"><div class="skeleton footer"></div></slot>
+                    </div>
+                </div>
+            </div>
+        </template>
+    `);
 
-        await new Promise((res) => setTimeout(res, 1000));
+    const prom1 = headerFetch.toArray().then((data) => {
+        stream.send(`<div slot="header">${Buffer.concat(data).toString()}</div>`);
+    });
+    const prom2 = menuFetch.toArray().then((data) => {
+        stream.send(`<div slot="menu">${Buffer.concat(data).toString()}</div>`);
+    });
+    const prom3 = contentFetch.toArray().then((data) => {
+        stream.send(`<div slot="content">${Buffer.concat(data).toString()}</div>`);
+    });
+    const prom4 = footerFetch.toArray().then((data) => {
+        stream.send(`<div slot="footer">${Buffer.concat(data).toString()}</div>`);
+    });
 
-        footerFetch.then((content) => {
-            stream.send(`<div slot="footer">${content}</div>`);
-        });
+    await Promise.all([prom1, prom2, prom3, prom4]);
 
-        // close out the dom and the stream
-        await Promise.all([headerFetch, menuFetch, contentFetch, footerFetch]);
-        stream.done();
-    });
+    stream.done();
 });
 
 app.use(`${layout.pathname()}/assets`, express.static('assets'));

From d954732be77e25827b06450dbb2ec84f68d692b7 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Thu, 14 Nov 2024 16:14:00 +1300
Subject: [PATCH 12/15] feat: wait for assets inside podiumStream

---
 lib/layout.js | 6 +++++-
 package.json  | 4 ++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/lib/layout.js b/lib/layout.js
index 8bef3b9c..d679b4ab 100644
--- a/lib/layout.js
+++ b/lib/layout.js
@@ -620,7 +620,11 @@ export default class PodiumLayout {
 
                 // we add a new podiumStream method that sets up streaming and returns the stream
                 // object for the developer to work with
-                res.podiumStream = (...args) => {
+                res.podiumStream = async (...args) => {
+                    const { js, css } = await incoming.waitForAssets();
+                    incoming.js = js;
+                    incoming.css = css;
+
                     const responseStream = new ResponseStream();
                     // pipe the readable response stream into the express writeable res stream
                     // to set up streaming
diff --git a/package.json b/package.json
index fd561dad..af537748 100644
--- a/package.json
+++ b/package.json
@@ -41,11 +41,11 @@
   },
   "dependencies": {
     "@metrics/client": "2.5.3",
-    "@podium/client": "5.2.0",
+    "@podium/client": "5.3.0-next.1",
     "@podium/context": "5.1.1",
     "@podium/proxy": "5.0.30",
     "@podium/schemas": "5.1.0",
-    "@podium/utils": "5.3.2",
+    "@podium/utils": "5.4.0",
     "abslog": "2.4.4",
     "ajv": "8.17.1",
     "lodash.merge": "4.6.2",

From fa559f98f406c6f22ba7fc055dcba8146d825a84 Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Thu, 14 Nov 2024 16:14:27 +1300
Subject: [PATCH 13/15] chore: update examples

---
 example/streaming/podlets/content.js   |  35 ++--
 example/streaming/podlets/footer.js    |  59 +++++--
 example/streaming/podlets/header.js    |  78 +++++++--
 example/streaming/podlets/menu.js      |  70 ++++----
 example/streaming/podlets/sidebar.js   |  76 ++++++++
 example/streaming/server-advanced-2.js | 231 +++++++++++++++++++++++++
 example/streaming/server-advanced.js   | 217 ++++++++++++++---------
 example/streaming/server-simple.js     |  95 ++++++----
 8 files changed, 673 insertions(+), 188 deletions(-)
 create mode 100644 example/streaming/podlets/sidebar.js
 create mode 100644 example/streaming/server-advanced-2.js

diff --git a/example/streaming/podlets/content.js b/example/streaming/podlets/content.js
index 9c70c136..d07e32cd 100644
--- a/example/streaming/podlets/content.js
+++ b/example/streaming/podlets/content.js
@@ -2,12 +2,13 @@ import Podlet from '@podium/podlet';
 import express from 'express';
 
 const podlet = new Podlet({
-    name: 'content',
+    name: 'content-podlet',
     version: Date.now().toString(),
     pathname: '/',
+    useShadowDOM: true,
 });
 
-podlet.css({ value: 'http://localhost:6103/css' });
+podlet.css({ value: 'http://localhost:6103/css', strategy: 'shadow-dom' });
 
 const app = express();
 
@@ -20,15 +21,23 @@ app.get('/manifest.json', (req, res) => {
 app.get('/css', (req, res) => {
     res.set('Content-Type', 'text/css');
     res.send(`
-		.content {
-			border: 1px solid black;
-			border-radius: 5px;
-			width: 100%;
-			padding: 20px;
-			margin: 0;
-			margin-bottom: 20px;
-			box-sizing: border-box;
-		}
+			* {
+				box-sizing: border-box;
+				margin: 0;
+				padding: 0;
+			}
+			.content {
+				width: 100%;
+				display: flex;
+				flex-direction: column;
+				gap: 1em;
+				font-family: Verdana, serif;
+				font-weight: 400;
+				font-style: normal;
+			}
+			h1 {
+				color: #136C72;
+			}
 	`);
 });
 
@@ -40,7 +49,9 @@ app.get('/', async (req, res) => {
 
     res.podiumSend(`
 			<section class="content">
-				main content goes here
+				<h1>Podlets fetched and composed, on demand, just for you</h1>
+				<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>
+				<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>
 			</section>	
 		`);
 });
diff --git a/example/streaming/podlets/footer.js b/example/streaming/podlets/footer.js
index d239460e..80f73f29 100644
--- a/example/streaming/podlets/footer.js
+++ b/example/streaming/podlets/footer.js
@@ -2,12 +2,13 @@ import Podlet from '@podium/podlet';
 import express from 'express';
 
 const podlet = new Podlet({
-    name: 'footer',
+    name: 'footer-podlet',
     version: Date.now().toString(),
     pathname: '/',
+    useShadowDOM: true,
 });
 
-podlet.css({ value: 'http://localhost:6104/css' });
+podlet.css({ value: 'http://localhost:6104/css', strategy: 'shadow-dom' });
 
 const app = express();
 
@@ -20,15 +21,39 @@ app.get('/manifest.json', (req, res) => {
 app.get('/css', (req, res) => {
     res.set('Content-Type', 'text/css');
     res.send(`
-		footer {
-			border: 1px solid black;
-			border-radius: 5px;
-			width: 100%;
-			padding: 20px;
-			margin: 0;
-			margin-bottom: 20px;
-			box-sizing: border-box;
-		}
+			* {
+				margin: 0;
+				padding: 0;
+				box-sizing: border-box;
+			}
+			footer {
+				width: 100%;
+				background-color: #23424A;
+				color: white;
+				padding: 1em 0 6em 0;
+				font-family: Verdana, serif;
+				font-weight: 400;
+				font-style: normal;
+			}
+			.container {
+				width: 75%;
+				max-width: 1000px;
+				margin: 0 auto;
+			}
+			ul {
+				list-style: none;
+				display: flex;
+				justify-content: space-evenly;
+				align-items: center;
+			}
+			a {
+				text-transform: upper-case;
+				color: white;
+				text-decoration: none;
+			}
+			a:hover, a:active {
+				text-decoration: underline;
+			}
 	`);
 });
 
@@ -36,11 +61,19 @@ app.get('/', async (req, res) => {
     // send headers
     res.sendHeaders();
 
-    await new Promise((res) => setTimeout(res, 1250));
+    await new Promise((res) => setTimeout(res, 100));
 
     res.podiumSend(`
 			<footer>
-				footer content
+				<div class="container">
+					<ul>
+					<li><a href="#">Home</a></li>
+					<li><a href="#">About</a></li>
+					<li><a href="#">Contact</a></li>
+					<li><a href="#">Sign in</a></li>
+					<li><a href="#">Sign up</a></li>
+				</ul>
+				</div>
 			</footer>	
 		`);
 });
diff --git a/example/streaming/podlets/header.js b/example/streaming/podlets/header.js
index b7fec50c..25a0a8df 100644
--- a/example/streaming/podlets/header.js
+++ b/example/streaming/podlets/header.js
@@ -2,12 +2,13 @@ import Podlet from '@podium/podlet';
 import express from 'express';
 
 const podlet = new Podlet({
-    name: 'header',
+    name: 'header-podlet',
     version: Date.now().toString(),
     pathname: '/',
+    useShadowDOM: true,
 });
 
-podlet.css({ value: 'http://localhost:6101/css' });
+podlet.css({ value: 'http://localhost:6101/css', strategy: 'shadow-dom' });
 
 const app = express();
 
@@ -20,20 +21,55 @@ app.get('/manifest.json', (req, res) => {
 app.get('/css', (req, res) => {
     res.set('Content-Type', 'text/css');
     res.send(`
-		header {
-			border: 1px solid black;
-			border-radius: 5px;
-			width: 100%;
-			padding: 20px;
-			margin: 0;
-			margin-bottom: 20px;
-			box-sizing: border-box;
-		}
-		header h1 {
-			text-align: center;
-			margin: 0;
-			padding: 0;
-		}
+			* {
+				margin: 0;
+				padding: 0;
+				box-sizing: border-box;
+			}
+			header {
+				width: 100%;
+				padding: 6em 0;
+				background-color: #23424A;
+				font-size: 1.5rem;
+				font-family: "Verdana", sans-serif;
+				font-weight: 400;
+				font-style: normal;
+				color: white;
+			}
+			h1 {
+				font-size: 3rem;
+				color: white;
+				font-family: "Verdana", sans-serif;
+				font-weight: 900;
+				font-style: normal;
+			}
+			.container {
+				width: 75%;
+				max-width: 1000px;
+				margin: 0 auto;
+			}
+			.inner-container {
+				display: flex;
+				flex-direction: column;
+				gap: 1em;
+			}
+			.button {
+				color: black;
+				background-color: #38CFD9;
+				padding: 0.5em 1.25em;
+				border-radius: 1em;
+				text-decoration: none;
+				width: fit-content;
+			}
+			.button:hover, .button:active {
+				text-decoration: underline;
+				width: fit-content;
+			}
+			@media (min-width: 800px) {
+				.inner-container {
+					width: 70%;
+				}
+			}
 	`);
 });
 
@@ -41,11 +77,17 @@ app.get('/', async (req, res) => {
     // send headers
     res.sendHeaders();
 
-    await new Promise((res) => setTimeout(res, 3500));
+    await new Promise((res) => setTimeout(res, 100));
 
     res.podiumSend(`
 			<header>
-				<h1>Header</h1>
+				<div class="container">
+					<div class="inner-container">
+						<h1>Podium layouts can be composed using streaming</h1>
+						<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>
+						<a href="#" class="button">I want to learn</a>
+					</div>
+				</div>
 			</header>	
 		`);
 });
diff --git a/example/streaming/podlets/menu.js b/example/streaming/podlets/menu.js
index fcb25b89..ff2c7df0 100644
--- a/example/streaming/podlets/menu.js
+++ b/example/streaming/podlets/menu.js
@@ -2,12 +2,13 @@ import Podlet from '@podium/podlet';
 import express from 'express';
 
 const podlet = new Podlet({
-    name: 'menu',
+    name: 'menu-podlet',
     version: Date.now().toString(),
     pathname: '/',
+    useShadowDOM: true,
 });
 
-podlet.css({ value: 'http://localhost:6102/css' });
+podlet.css({ value: 'http://localhost:6102/css', strategy: 'shadow-dom' });
 
 const app = express();
 
@@ -20,27 +21,33 @@ app.get('/manifest.json', (req, res) => {
 app.get('/css', (req, res) => {
     res.set('Content-Type', 'text/css');
     res.send(`
-		menu {
-			border: 1px solid black;
-			border-radius: 5px;
-			width: 100%;
-			padding: 10px;
-			margin: 0;
-			margin-bottom: 20px;
-			box-sizing: border-box;
-		}
-		menu ul {
-			list-style: none;
-			padding: 0;
-			margin: 0;
-			display: flex;
-			justify-content: space-evenly;
-			align-items: center;
-		}
-		menu ul li {
-			margin: 0;
-			padding: 0;
-		}
+			* {
+				margin: 0;
+				padding: 0;
+				box-sizing: border-box;
+			}
+			.menu {
+				width: 100%;
+				background-color: #136C72;
+				padding: 1em 0;
+				font-family: Verdana, serif;
+				font-weight: 400;
+				font-style: normal;
+			}
+			.menu ul {
+				list-style: none;
+				display: flex;
+				justify-content: space-evenly;
+				align-items: center;
+			}
+			a {
+				text-transform: upper-case;
+				color: white;
+				text-decoration: none;
+			}
+			a:hover, a:active {
+				text-decoration: underline;
+			}
 	`);
 });
 
@@ -48,18 +55,19 @@ app.get('/', async (req, res) => {
     // send headers
     res.sendHeaders();
 
-		// imagine this is your slow database call
-    await new Promise((res) => setTimeout(res, 1000));
+    // imagine this is your slow database call
+    await new Promise((res) => setTimeout(res, 100));
 
     res.podiumSend(`
-			<menu>
+			<nav class="menu">
 				<ul>
-					<li><a href="/">Home</a></li>
-					<li><a href="/about">About</a></li>
-					<li><a href="/things">Things</a></li>
-					<li><a href="/stuff">Stuff</a></li>
+					<li><a href="#">Home</a></li>
+					<li><a href="#">About</a></li>
+					<li><a href="#">Contact</a></li>
+					<li><a href="#">Sign in</a></li>
+					<li><a href="#">Sign up</a></li>
 				</ul>
-			</menu>	
+			</nav>	
 		`);
 });
 
diff --git a/example/streaming/podlets/sidebar.js b/example/streaming/podlets/sidebar.js
new file mode 100644
index 00000000..bc36d2a3
--- /dev/null
+++ b/example/streaming/podlets/sidebar.js
@@ -0,0 +1,76 @@
+import Podlet from '@podium/podlet';
+import express from 'express';
+
+const podlet = new Podlet({
+    name: 'sidebar-podlet',
+    version: Date.now().toString(),
+    pathname: '/',
+    useShadowDOM: true,
+});
+
+podlet.css({ value: 'http://localhost:6105/css', strategy: 'shadow-dom' });
+
+const app = express();
+
+app.use(podlet.middleware());
+
+app.get('/manifest.json', (req, res) => {
+    res.send(podlet);
+});
+
+app.get('/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+		 	* {
+		  	border-sizing: border-box;
+				margin: 0;
+				padding: 0;	
+			}
+			.sidebar {
+				background-color: #136C72;
+				color: white;
+				width: 100%;
+				padding: 2.5em 1em;
+				text-align: center;
+				display: flex;
+				flex-direction: column;
+				gap: 2.5em;
+				font-family: Verdana, serif;
+				font-weight: 400;
+				font-style: normal;
+			}
+			.info-block {
+				display: flex;
+				flex-direction: column;
+				gap: 1em;
+			}
+	`);
+});
+
+app.get('/', async (req, res) => {
+    // send headers
+    res.sendHeaders();
+
+    await new Promise((res) => setTimeout(res, 3200));
+
+    res.podiumSend(`
+			<section class="sidebar">
+				<div class="info-block">
+					<h2>Cheap</h2>
+					<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>
+				</div>
+				<div class="info-block">
+					<h2>Quick</h2>
+					<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>
+				</div>
+				<div class="info-block">
+					<h2>Quality</h2>
+					<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam.</p>
+				</div>
+			</section>	
+		`);
+});
+
+app.listen(6105, () => {
+    console.log(`content podlet server running at http://localhost:6105`);
+});
diff --git a/example/streaming/server-advanced-2.js b/example/streaming/server-advanced-2.js
new file mode 100644
index 00000000..188a3422
--- /dev/null
+++ b/example/streaming/server-advanced-2.js
@@ -0,0 +1,231 @@
+import express from 'express';
+import Layout from '../../lib/layout.js';
+
+const layout = new Layout({
+    pathname: '/foo',
+    logger: console,
+    name: 'demo',
+    client: {
+        timeout: 5000,
+    },
+});
+
+const header = layout.client.register({
+    name: 'header',
+    uri: 'http://localhost:6101/manifest.json',
+});
+
+const menu = layout.client.register({
+    name: 'menu',
+    uri: 'http://localhost:6102/manifest.json',
+});
+
+const content = layout.client.register({
+    name: 'content',
+    uri: 'http://localhost:6103/manifest.json',
+});
+
+const footer = layout.client.register({
+    name: 'footer',
+    uri: 'http://localhost:6104/manifest.json',
+});
+
+const sidebar = layout.client.register({
+    name: 'sidebar',
+    uri: 'http://localhost:6105/manifest.json',
+});
+
+layout.css({ value: '/css' });
+
+const app = express();
+
+app.use(layout.pathname(), layout.middleware());
+
+app.get('/foo/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+        * {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
+        @keyframes pulse {
+            0% {
+                background-color: #e0e0e0;
+            }
+            50% {
+                background-color: #f0f0f0;
+            }
+            100% {
+                background-color: #e0e0e0;
+            }
+        }
+        .skeleton {
+            width: 100%;
+            background-color: #e0e0e0;
+            border-radius: 5px;
+            animation: pulse 1.5s infinite ease-in-out;
+            margin: 0;
+			box-sizing: border-box;
+        }
+        .skeleton--header {
+            height:79px;
+        }
+        .skeleton--menu {
+            height:40px;
+        }
+        .skeleton--content {
+            height:300px;
+        }
+        .skeleton--sidebar {
+            height:500px;
+        }
+        .skeleton--footer {
+            padding: 1em 0 6em 0;
+        }
+        .wrapper {
+            font-family: Verdana, serif;
+            font-weight: 400;
+            font-style: normal;
+            width: 100%;
+            display: flex;
+            flex-direction: column;
+            gap: 2em;
+        }
+        .container {
+            width: 75%;
+            max-width: 1000px;
+            margin: 0 auto;
+        }
+        .main {
+            display: flex;
+            gap: 1em;
+            flex-direction: column;
+            @media (min-width: 800px) {
+                flex-direction: row;
+            }
+        }
+        .content {
+            flex-grow: 2;
+        }
+        .sidebar {
+            flex-grow: 1;
+        }
+        
+	`);
+});
+
+app.get(layout.pathname(), async (req, res) => {
+    const incoming = res.locals.podium;
+
+    // --------------------------------------------------------
+    // Define any template variables such as the document title
+    // --------------------------------------------------------
+
+    incoming.view = {
+        title: 'Example streaming application',
+    };
+
+    const headerFetch = header.fetch(incoming);
+    const menuFetch = menu.fetch(incoming);
+    const contentFetch = content.fetch(incoming);
+    const footerFetch = footer.fetch(incoming);
+    const sidebarFetch = sidebar.fetch(incoming);
+
+    // -----------------------------------------------------------
+    // Start the stream and flush the document head to the browser
+    // -----------------------------------------------------------
+
+    // we kick off the stream, this automatically sends the document opening html including everything in the <head>
+    // as well as the openning <body> tag.
+    const stream = await res.podiumStream();
+
+    const [headerContent, menuContent] = await Promise.all([
+        headerFetch,
+        menuFetch,
+    ]);
+
+    // -----------------------------------------------------------------------
+    // Immediately send the document structure and placeholders to the browser
+    // -----------------------------------------------------------------------
+
+    // stream in the document body with slot skeleton screen placeholders for podlets
+    // these will be replaced once the podlets are loaded
+    stream.send(`
+        <template shadowrootmode="open">
+            <link href="/foo/css" type="text/css" rel="stylesheet">
+            <div class="wrapper">
+                <section>
+                    <section class="">${menuContent}</section>
+                    <header>${headerContent}</header>
+                </section>
+                <main class="main container">
+                    <div class="content">
+                        <slot name="content"><div class="skeleton skeleton--content"></div></slot>
+                    </div>
+                    <aside class="sidebar">
+                        <slot name="sidebar"><div class="skeleton skeleton--sidebar"></div></slot>
+                    </aside>
+                </main>
+                <footer class="footer">
+                    <slot name="footer"><div class="skeleton skeleton--footer"></div></slot>
+                </footer>
+            </div>
+        </template>
+    `);
+
+    // ---------------------------------------------------------
+    // Option 1. Load podlets one at a time as they are fetched
+    // ---------------------------------------------------------
+
+    const [contentData, footerData, sidebarData] = await Promise.all([
+        contentFetch,
+        footerFetch,
+        sidebarFetch,
+    ]);
+
+    stream.send(`
+        <div slot="content">${contentData}</div>
+        <div slot="footer">${footerData}</div>
+        <div slot="sidebar">${sidebarData}</div>
+    `);
+
+    // ---------------------------------------------------------------------
+    // Option 2. Load all podlets at once after everything has been fetched
+    // ---------------------------------------------------------------------
+
+    // const prom1 = headerFetch.then((data) => {
+    //     stream.send(`<div slot="header">${data}</div>`);
+    // });
+    // const prom2 = menuFetch.then((data) => {
+    //     stream.send(`<div slot="menu">${data}</div>`);
+    // });
+    // const prom3 = contentFetch.then((data) => {
+    //     stream.send(`<div slot="content">${data}</div>`);
+    // });
+    // const prom4 = footerFetch.then((data) => {
+    //     stream.send(`<div slot="footer">${data}</div>`);
+    // });
+
+    // await Promise.all([prom1, prom2, prom3, prom4]);
+
+    // --------------------------
+    // Close the stream when done
+    // --------------------------
+
+    stream.done();
+});
+
+app.use(`${layout.pathname()}/assets`, express.static('assets'));
+
+// eslint-disable-next-line no-unused-vars
+app.use((error, req, res, next) => {
+    console.error(error);
+    res.status(500).send(
+        '<html><body><h1>Internal server error</h1></body></html>',
+    );
+});
+
+app.listen(6123, () => {
+    console.log(`layout server running at http://localhost:6123`);
+});
diff --git a/example/streaming/server-advanced.js b/example/streaming/server-advanced.js
index 220b056e..5006d207 100644
--- a/example/streaming/server-advanced.js
+++ b/example/streaming/server-advanced.js
@@ -1,6 +1,5 @@
 import express from 'express';
 import Layout from '../../lib/layout.js';
-import { timeout } from 'tap';
 
 const layout = new Layout({
     pathname: '/foo',
@@ -8,12 +7,7 @@ const layout = new Layout({
     name: 'demo',
     client: {
         timeout: 5000,
-    }
-});
-
-const content = layout.client.register({
-    name: 'content',
-    uri: 'http://localhost:6103/manifest.json',
+    },
 });
 
 const header = layout.client.register({
@@ -26,11 +20,21 @@ const menu = layout.client.register({
     uri: 'http://localhost:6102/manifest.json',
 });
 
+const content = layout.client.register({
+    name: 'content',
+    uri: 'http://localhost:6103/manifest.json',
+});
+
 const footer = layout.client.register({
     name: 'footer',
     uri: 'http://localhost:6104/manifest.json',
 });
 
+const sidebar = layout.client.register({
+    name: 'sidebar',
+    uri: 'http://localhost:6105/manifest.json',
+});
+
 layout.css({ value: '/css' });
 
 const app = express();
@@ -40,6 +44,11 @@ app.use(layout.pathname(), layout.middleware());
 app.get('/foo/css', (req, res) => {
     res.set('Content-Type', 'text/css');
     res.send(`
+        * {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
         @keyframes pulse {
             0% {
                 background-color: #e0e0e0;
@@ -57,112 +66,156 @@ app.get('/foo/css', (req, res) => {
             border-radius: 5px;
             animation: pulse 1.5s infinite ease-in-out;
             margin: 0;
-			margin-bottom: 20px;
 			box-sizing: border-box;
         }
-        .skeleton.header {
-            height:79px;
+        .skeleton--header {
+            height:600px;
         }
-        .skeleton.menu {
+        .skeleton--menu {
             height:40px;
         }
-        .skeleton.content {
-            height:60px;
+        .skeleton--content {
+            height:300px;
+        }
+        .skeleton--sidebar {
+            height:500px;
+        }
+        .skeleton--footer {
+            padding: 1em 0 6em 0;
+        }
+        .wrapper {
+            font-family: Verdana, serif;
+            font-weight: 400;
+            font-style: normal;
+            width: 100%;
+            display: flex;
+            flex-direction: column;
+            gap: 2em;
         }
-        .skeleton.footer {
-            height:60px;
+        .container {
+            width: 75%;
+            max-width: 1000px;
+            margin: 0 auto;
         }
+        .main {
+            display: flex;
+            gap: 1em;
+            flex-direction: column;
+            @media (min-width: 800px) {
+                flex-direction: row;
+            }
+        }
+        .content {
+            flex-grow: 2;
+        }
+        .sidebar {
+            flex-grow: 1;
+        }
+        
 	`);
 });
 
 app.get(layout.pathname(), async (req, res) => {
     const incoming = res.locals.podium;
 
+    // --------------------------------------------------------
+    // Define any template variables such as the document title
+    // --------------------------------------------------------
+
     incoming.view = {
         title: 'Example streaming application',
     };
 
-    // we start a stream for each podlet (instead of a fetch)
-    // this allows us to receive podlet meta including assets before the podlet body
-    const headerFetch = header.stream(incoming);
-    const menuFetch = menu.stream(incoming);
-    const contentFetch = content.stream(incoming);
-    const footerFetch = footer.stream(incoming);
-
-    // we set up listeners to get notified with podlet metadata is ready
-    // this will occur before the podlet body content is sent.
-    headerFetch.once('beforeStream', ({ js, css }) => {
-        incoming.css.push(...css);
-    });
-    menuFetch.once('beforeStream', ({ js, css }) => {
-        incoming.css.push(...css);
-    });
-    contentFetch.once('beforeStream', ({ js, css }) => {
-        incoming.css.push(...css);
-    });
-    footerFetch.once('beforeStream', ({ js, css }) => {
-        incoming.css.push(...css);
-    });
-
-    // we use an awkward wait function to ensure that all the assets are loaded
-    // before we start the stream (and flush the document head)
-    await new Promise((resolve) => {
-        function checkForAssets() {
-            if (incoming.css.length >= 5) {
-                resolve(true);
-            } else {
-                setTimeout(checkForAssets, 100);
-            }
-        }
-        checkForAssets();
-    });
+    const headerFetch = header.fetch(incoming);
+    const menuFetch = menu.fetch(incoming);
+    const contentFetch = content.fetch(incoming);
+    const footerFetch = footer.fetch(incoming);
+    const sidebarFetch = sidebar.fetch(incoming);
+
+    // -----------------------------------------------------------
+    // Start the stream and flush the document head to the browser
+    // -----------------------------------------------------------
 
     // we kick off the stream, this automatically sends the document opening html including everything in the <head>
     // as well as the openning <body> tag.
-    const stream = res.podiumStream();
+    const stream = await res.podiumStream();
+
+    // -----------------------------------------------------------------------
+    // Immediately send the document structure and placeholders to the browser
+    // -----------------------------------------------------------------------
 
     // stream in the document body with slot skeleton screen placeholders for podlets
     // these will be replaced once the podlets are loaded
     stream.send(`
         <template shadowrootmode="open">
             <link href="/foo/css" type="text/css" rel="stylesheet">
-            <div class="container">
-                <div>
-                    <div>
-                        <slot name="header"><div class="skeleton header"></div></slot>
+            <div class="wrapper">
+                <section>
+                    <section>
+                        <slot name="menu"><div class="skeleton skeleton--menu"></div></slot>
+                    </section>
+                    <header>
+                        <slot name="header"><div class="skeleton skeleton--header"></div></slot>
+                    </header>
+                </section>
+                <main class="main container">
+                    <div class="content">
+                        <slot name="content"><div class="skeleton skeleton--content"></div></slot>
                     </div>
-                </div>
-                <div>
-                    <div>
-                        <slot name="menu"><div class="skeleton menu"></div></slot>
-                    </div>
-                    <div>
-                        <slot name="content"><div class="skeleton content"></div></slot>
-                    </div>
-                </div>
-                <div>
-                    <div>
-                        <slot name="footer"><div class="skeleton footer"></div></slot>
-                    </div>
-                </div>
+                    <aside class="sidebar">
+                        <slot name="sidebar"><div class="skeleton skeleton--sidebar"></div></slot>
+                    </aside>
+                </main>
+                <footer class="footer">
+                    <slot name="footer"><div class="skeleton skeleton--footer"></div></slot>
+                </footer>
             </div>
         </template>
     `);
 
-    const prom1 = headerFetch.toArray().then((data) => {
-        stream.send(`<div slot="header">${Buffer.concat(data).toString()}</div>`);
-    });
-    const prom2 = menuFetch.toArray().then((data) => {
-        stream.send(`<div slot="menu">${Buffer.concat(data).toString()}</div>`);
-    });
-    const prom3 = contentFetch.toArray().then((data) => {
-        stream.send(`<div slot="content">${Buffer.concat(data).toString()}</div>`);
-    });
-    const prom4 = footerFetch.toArray().then((data) => {
-        stream.send(`<div slot="footer">${Buffer.concat(data).toString()}</div>`);
-    });
-
-    await Promise.all([prom1, prom2, prom3, prom4]);
+    // ---------------------------------------------------------
+    // Option 1. Load podlets one at a time as they are fetched
+    // ---------------------------------------------------------
+
+    const [headerData, menuData, contentData, footerData, sidebarData] =
+        await Promise.all([
+            headerFetch,
+            menuFetch,
+            contentFetch,
+            footerFetch,
+            sidebarFetch,
+        ]);
+
+    stream.send(`
+        <div slot="header">${headerData}</div>
+        <div slot="menu">${menuData}</div>
+        <div slot="content">${contentData}</div>
+        <div slot="footer">${footerData}</div>
+        <div slot="sidebar">${sidebarData}</div>
+    `);
+
+    // ---------------------------------------------------------------------
+    // Option 2. Load all podlets at once after everything has been fetched
+    // ---------------------------------------------------------------------
+
+    // const prom1 = headerFetch.then((data) => {
+    //     stream.send(`<div slot="header">${data}</div>`);
+    // });
+    // const prom2 = menuFetch.then((data) => {
+    //     stream.send(`<div slot="menu">${data}</div>`);
+    // });
+    // const prom3 = contentFetch.then((data) => {
+    //     stream.send(`<div slot="content">${data}</div>`);
+    // });
+    // const prom4 = footerFetch.then((data) => {
+    //     stream.send(`<div slot="footer">${data}</div>`);
+    // });
+
+    // await Promise.all([prom1, prom2, prom3, prom4]);
+
+    // --------------------------
+    // Close the stream when done
+    // --------------------------
 
     stream.done();
 });
diff --git a/example/streaming/server-simple.js b/example/streaming/server-simple.js
index 32a3af03..03ae42ae 100644
--- a/example/streaming/server-simple.js
+++ b/example/streaming/server-simple.js
@@ -27,12 +27,41 @@ const footer = layout.client.register({
     uri: 'http://localhost:6104/manifest.json',
 });
 
-layout.css({ value: '/css' });
+const sidebar = layout.client.register({
+    name: 'sidebar',
+    uri: 'http://localhost:6105/manifest.json',
+});
+
+layout.css({ value: '/foo/css', strategy: 'shadow-dom' });
 
 const app = express();
 
 app.use(layout.pathname(), layout.middleware());
 
+app.get('/foo/css', (req, res) => {
+    res.set('Content-Type', 'text/css');
+    res.send(`
+        * {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
+        .layout {
+            width: 100%;
+            display: flex;
+            flex-direction: column;
+            gap: 2em;
+        }
+        .content-area {
+            width: 75%;
+            max-width: 1000px;
+            margin: 0 auto;
+            display: flex;
+            gap: 1em;
+        }
+	`);
+});
+
 app.get(layout.pathname(), async (req, res) => {
     const incoming = res.locals.podium;
 
@@ -44,38 +73,40 @@ app.get(layout.pathname(), async (req, res) => {
     const menuFetch = menu.fetch(incoming);
     const contentFetch = content.fetch(incoming);
     const footerFetch = footer.fetch(incoming);
-
-    incoming.hints.on('complete', async ({ js, css }) => {
-        // set the assets on httpincoming so that they are available in the document template
-        incoming.js = js;
-        incoming.css = css;
-
-        // set up the stream which will send the document template head
-        const stream = res.podiumStream();
-
-        // pretend the podlets are slow to load
-        await new Promise((res) => setTimeout(res, 3000));
-
-        const [header, menu, content, footer] = await Promise.all([
-            headerFetch,
-            menuFetch,
-            contentFetch,
-            footerFetch,
-        ]);
-
-        // stream in the document body with slot placeholders for podlets
-        stream.send(`
-            <div class="container">
-                <div>${header}</div>
-                <div>
-                    <div>${menu}</div>
-                    <div>${content}</div>
-                </div>
-                <div>${footer}</div>
+    const sidebarFetch = sidebar.fetch(incoming);
+
+    const stream = await res.podiumStream();
+
+    const [
+        headerResult,
+        menuResult,
+        contentResult,
+        footerResult,
+        sidebarResult,
+    ] = await Promise.all([
+        headerFetch,
+        menuFetch,
+        contentFetch,
+        footerFetch,
+        sidebarFetch,
+    ]);
+
+    // stream in the document body with slot placeholders for podlets
+    stream.send(`
+        <div class="layout">
+            <link href="/foo/css" type="text/css" rel="stylesheet">
+            <div class="top-area">
+                <div>${menuResult}</div>
+                <div>${headerResult}</div>
+            </div>
+            <div class="content-area">
+                ${contentResult}
+                ${sidebarResult}
             </div>
-        `);
-        stream.done();
-    });
+            <div>${footerResult}</div>
+        </div>
+    `);
+    stream.done();
 });
 
 // eslint-disable-next-line no-unused-vars

From 9d69703e234a543996f2d2966b1ec7553548222f Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Thu, 14 Nov 2024 16:55:59 +1300
Subject: [PATCH 14/15] chore: set content type

---
 example/streaming/podlets/content.js | 2 +-
 example/streaming/podlets/footer.js  | 2 +-
 example/streaming/podlets/header.js  | 2 +-
 example/streaming/podlets/menu.js    | 2 +-
 example/streaming/podlets/sidebar.js | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/example/streaming/podlets/content.js b/example/streaming/podlets/content.js
index d07e32cd..c54d2a76 100644
--- a/example/streaming/podlets/content.js
+++ b/example/streaming/podlets/content.js
@@ -42,7 +42,7 @@ app.get('/css', (req, res) => {
 });
 
 app.get('/', async (req, res) => {
-    // send headers
+    res.set('Content-Type', 'text/html');
     res.sendHeaders();
 
     await new Promise((res) => setTimeout(res, 2200));
diff --git a/example/streaming/podlets/footer.js b/example/streaming/podlets/footer.js
index 80f73f29..3a9698e1 100644
--- a/example/streaming/podlets/footer.js
+++ b/example/streaming/podlets/footer.js
@@ -58,7 +58,7 @@ app.get('/css', (req, res) => {
 });
 
 app.get('/', async (req, res) => {
-    // send headers
+    res.set('Content-Type', 'text/html');
     res.sendHeaders();
 
     await new Promise((res) => setTimeout(res, 100));
diff --git a/example/streaming/podlets/header.js b/example/streaming/podlets/header.js
index 25a0a8df..ba14ac3e 100644
--- a/example/streaming/podlets/header.js
+++ b/example/streaming/podlets/header.js
@@ -74,7 +74,7 @@ app.get('/css', (req, res) => {
 });
 
 app.get('/', async (req, res) => {
-    // send headers
+    res.set('Content-Type', 'text/html');
     res.sendHeaders();
 
     await new Promise((res) => setTimeout(res, 100));
diff --git a/example/streaming/podlets/menu.js b/example/streaming/podlets/menu.js
index ff2c7df0..70488556 100644
--- a/example/streaming/podlets/menu.js
+++ b/example/streaming/podlets/menu.js
@@ -52,7 +52,7 @@ app.get('/css', (req, res) => {
 });
 
 app.get('/', async (req, res) => {
-    // send headers
+    res.set('Content-Type', 'text/html');
     res.sendHeaders();
 
     // imagine this is your slow database call
diff --git a/example/streaming/podlets/sidebar.js b/example/streaming/podlets/sidebar.js
index bc36d2a3..568afbb8 100644
--- a/example/streaming/podlets/sidebar.js
+++ b/example/streaming/podlets/sidebar.js
@@ -48,7 +48,7 @@ app.get('/css', (req, res) => {
 });
 
 app.get('/', async (req, res) => {
-    // send headers
+    res.set('Content-Type', 'text/html');
     res.sendHeaders();
 
     await new Promise((res) => setTimeout(res, 3200));

From 4a7b87f3237f79d0d31b19890d9b2464c403545a Mon Sep 17 00:00:00 2001
From: Richard Walker <digitalsadhu@gmail.com>
Date: Mon, 18 Nov 2024 14:58:51 +1300
Subject: [PATCH 15/15] test: refactor and expand streaming tests

---
 tests/layout.test.js    | 155 ---------------
 tests/streaming.test.js | 424 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 424 insertions(+), 155 deletions(-)
 create mode 100644 tests/streaming.test.js

diff --git a/tests/layout.test.js b/tests/layout.test.js
index a8eedbcf..cd1fa3fe 100644
--- a/tests/layout.test.js
+++ b/tests/layout.test.js
@@ -731,158 +731,3 @@ tap.test('Proxy - builds correct proxy url', async (t) => {
     s1.stop();
     s2.stop();
 });
-
-const podlet = (name, port, assets) => {
-    const app = express();
-    const podlet = new Podlet({
-        name,
-        version: '1.0.0',
-        pathname: '/',
-    });
-    if (assets && assets.js) {
-        podlet.js({ value: assets.js, type: 'module' });
-    }
-    if (assets && assets.css) {
-        podlet.css({ value: assets.css, rel: 'stylesheet', type: 'text/css' });
-    }
-    app.use(podlet.middleware());
-    app.get('/manifest.json', (req, res) => res.send(podlet));
-    app.get(podlet.content(), (req, res) => res.send(`<div>${name}</div>`));
-    return stoppable(app.listen(port), 0);
-};
-
-tap.test('HTTP Streaming', async (t) => {
-    const p1 = podlet('podlet-registered-name-1', 5053);
-    const p2 = podlet('podlet-registered-name-2', 5054);
-
-    const app = express();
-    const layout = new Layout({ name: 'my-layout', pathname: '/' });
-    const p1Client = layout.client.register({
-        name: 'podlet-registered-name-1',
-        uri: 'http://0.0.0.0:5053/manifest.json',
-    });
-    const p2Client = layout.client.register({
-        name: 'podlet-registered-name-2',
-        uri: 'http://0.0.0.0:5054/manifest.json',
-    });
-    app.use(layout.middleware());
-    app.get(layout.pathname(), async (req, res) => {
-        const incoming = res.locals.podium;
-        const p1fetch = p1Client.fetch(incoming);
-        const p2fetch = p2Client.fetch(incoming);
-
-        const stream = res.podiumStream();
-
-        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
-
-        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
-
-        stream.done();
-    });
-    const l1 = stoppable(app.listen(5064), 0);
-
-    const result = await fetch('http://0.0.0.0:5064');
-    const html = await result.text();
-    t.match(html, /<html lang="en-US">/);
-    t.match(html, /<\/html>/);
-    t.match(
-        html,
-        /<div><div>podlet-registered-name-1<\/div><\/div><div><div>podlet-registered-name-2<\/div><\/div>/,
-        '',
-    );
-
-    p1.stop();
-    p2.stop();
-    l1.stop();
-});
-
-tap.test('HTTP Streaming - with assets', async (t) => {
-    const p1 = podlet('podlet-registered-name-1', 5073, {
-        js: '/podlet-registered-name-1.js',
-        css: '/podlet-registered-name-1.css',
-    });
-    const p2 = podlet('podlet-registered-name-2', 5074, {
-        js: '/podlet-registered-name-2.js',
-        css: '/podlet-registered-name-2.css',
-    });
-
-    const app = express();
-    const layout = new Layout({ name: 'my-layout', pathname: '/' });
-    const p1Client = layout.client.register({
-        name: 'podlet-registered-name-1',
-        uri: 'http://0.0.0.0:5073/manifest.json',
-    });
-    const p2Client = layout.client.register({
-        name: 'podlet-registered-name-2',
-        uri: 'http://0.0.0.0:5074/manifest.json',
-    });
-    app.use(layout.middleware());
-    app.get(layout.pathname(), async (req, res) => {
-        const incoming = res.locals.podium;
-        const p1fetch = p1Client.stream(incoming);
-        const p2fetch = p2Client.stream(incoming);
-
-        p1fetch.once('beforeStream', ({ js, css }) => {
-            incoming.js.push(...js);
-            incoming.css.push(...css);
-        });
-        p2fetch.once('beforeStream', ({ js, css }) => {
-            incoming.js.push(...js);
-            incoming.css.push(...css);
-        });
-
-        await new Promise((resolve) => {
-            function checkForAssets() {
-                if (incoming.js.length === 2 || incoming.css.length === 2) {
-                    resolve(true);
-                } else {
-                    setTimeout(checkForAssets, 100);
-                }
-            }
-            checkForAssets();
-        });
-
-        const stream = res.podiumStream();
-
-        const chunks1 = [];
-        for await (const chunk of p1fetch) {
-            chunks1.push(chunk);
-        }
-        const p1Content = Buffer.concat(chunks1).toString();
-
-        const chunks2 = [];
-        for await (const chunk of p2fetch) {
-            chunks2.push(chunk);
-        }
-        const p2Content = Buffer.concat(chunks2).toString();
-
-        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
-        stream.done();
-    });
-    const l1 = stoppable(app.listen(5075), 0);
-
-    const result = await fetch('http://0.0.0.0:5075');
-    const html = await result.text();
-
-    t.match(html, /<html lang="en-US">/);
-    t.match(
-        html,
-        /<link href="\/podlet-registered-name-1.css" type="text\/css" rel="stylesheet">/,
-    );
-    t.match(
-        html,
-        /<link href="\/podlet-registered-name-2.css" type="text\/css" rel="stylesheet">/,
-    );
-    t.match(
-        html,
-        /<div><div>podlet-registered-name-1<\/div><\/div><div><div>podlet-registered-name-2<\/div><\/div>/,
-        '',
-    );
-    t.match(html, /<script src="\/podlet-registered-name-1.js" type="module">/);
-    t.match(html, /<script src="\/podlet-registered-name-2.js" type="module">/);
-    t.match(html, /<\/html>/);
-
-    p1.stop();
-    p2.stop();
-    l1.stop();
-});
diff --git a/tests/streaming.test.js b/tests/streaming.test.js
new file mode 100644
index 00000000..a97f5c57
--- /dev/null
+++ b/tests/streaming.test.js
@@ -0,0 +1,424 @@
+import tap from 'tap';
+import stoppable from 'stoppable';
+import express from 'express';
+import Podlet from '@podium/podlet';
+import Layout from '../lib/layout.js';
+
+const podlet = (name, port, assets, options = {}) => {
+    const app = express();
+    const podlet = new Podlet({
+        name,
+        version: '1.0.0',
+        pathname: '/',
+    });
+    if (assets && assets.js) {
+        podlet.js({ value: assets.js, type: 'module' });
+    }
+    if (assets && assets.css) {
+        podlet.css({ value: assets.css, rel: 'stylesheet', type: 'text/css' });
+    }
+    app.use(podlet.middleware());
+    app.get('/manifest.json', (req, res) => res.send(podlet));
+    app.get(podlet.content(), async (req, res) => {
+        if (options.failing) {
+            res.sendStatus(500);
+            return;
+        }
+        if (options.slow) {
+            await new Promise((resolve) => setTimeout(resolve, 4000));
+        }
+        res.send(`<div>${name}</div>`);
+    });
+    return stoppable(app.listen(port), 0);
+};
+
+tap.test('HTTP Streaming - basic case', async (t) => {
+    const p1 = podlet('podlet-registered-name-1', 5153);
+    const p2 = podlet('podlet-registered-name-2', 5154);
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5153/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5154/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+
+        const stream = await res.podiumStream();
+
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5164), 0);
+
+    const result = await fetch('http://0.0.0.0:5164');
+    const html = await result.text();
+    t.match(html, /<html lang="en-US">/);
+    t.match(html, /<\/html>/);
+    t.match(
+        html,
+        /<div><div>podlet-registered-name-1<\/div><\/div><div><div>podlet-registered-name-2<\/div><\/div>/,
+        '',
+    );
+
+    p1.stop();
+    p2.stop();
+    l1.stop();
+});
+
+tap.test('HTTP Streaming - with assets', async (t) => {
+    const p1 = podlet('podlet-registered-name-1', 5173, {
+        js: '/podlet-registered-name-1.js',
+        css: '/podlet-registered-name-1.css',
+    });
+    const p2 = podlet('podlet-registered-name-2', 5174, {
+        js: '/podlet-registered-name-2.js',
+        css: '/podlet-registered-name-2.css',
+    });
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5173/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5174/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+        const stream = await res.podiumStream();
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5175), 0);
+
+    const result = await fetch('http://0.0.0.0:5175');
+    const html = await result.text();
+
+    t.match(html, /<html lang="en-US">/);
+    t.match(
+        html,
+        /<link href="\/podlet-registered-name-1.css" type="text\/css" rel="stylesheet">/,
+    );
+    t.match(
+        html,
+        /<link href="\/podlet-registered-name-2.css" type="text\/css" rel="stylesheet">/,
+    );
+    t.match(
+        html,
+        /<div><div>podlet-registered-name-1<\/div><\/div><div><div>podlet-registered-name-2<\/div><\/div>/,
+        '',
+    );
+    t.match(html, /<script src="\/podlet-registered-name-1.js" type="module">/);
+    t.match(html, /<script src="\/podlet-registered-name-2.js" type="module">/);
+    t.match(html, /<\/html>/);
+
+    p1.stop();
+    p2.stop();
+    l1.stop();
+});
+
+tap.test('HTTP Streaming - one podlet does not exist', async (t) => {
+    const p1 = podlet('podlet-registered-name-1', 5180, {
+        js: '/podlet-registered-name-1.js',
+        css: '/podlet-registered-name-1.css',
+    });
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5180/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5181/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+        const stream = await res.podiumStream();
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5183), 0);
+
+    const result = await fetch('http://0.0.0.0:5183');
+    const html = await result.text();
+
+    t.match(
+        html,
+        /<div><div>podlet-registered-name-1<\/div><\/div><div><\/div>/,
+        'podlet content should be an empty string',
+    );
+
+    p1.stop();
+    l1.stop();
+});
+
+tap.test('HTTP Streaming - one podlet down', async (t) => {
+    const p1 = podlet('podlet-registered-name-1', 5187, {
+        js: '/podlet-registered-name-1.js',
+        css: '/podlet-registered-name-1.css',
+    });
+    const p2 = podlet(
+        'podlet-registered-name-2',
+        5188,
+        {
+            js: '/podlet-registered-name-2.js',
+            css: '/podlet-registered-name-2.css',
+        },
+        { failing: true },
+    );
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5187/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5188/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+        const stream = await res.podiumStream();
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5189), 0);
+
+    const result = await fetch('http://0.0.0.0:5189');
+    const html = await result.text();
+
+    t.match(
+        html,
+        /<div><div>podlet-registered-name-1<\/div><\/div><div><\/div>/,
+        '',
+    );
+
+    p1.stop();
+    p2.stop();
+    l1.stop();
+});
+
+tap.test('HTTP Streaming - no podlets exist', async (t) => {
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5184/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5185/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+        const stream = await res.podiumStream();
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5186), 0);
+
+    const result = await fetch('http://0.0.0.0:5186');
+    const html = await result.text();
+
+    t.match(
+        html,
+        /<div><\/div><div><\/div>/,
+        'podlet content should be empty strings',
+    );
+    l1.stop();
+});
+
+tap.test('HTTP Streaming - all podlets down', async (t) => {
+    const p1 = podlet(
+        'podlet-registered-name-1',
+        5190,
+        {
+            js: '/podlet-registered-name-1.js',
+            css: '/podlet-registered-name-1.css',
+        },
+        { failing: true },
+    );
+    const p2 = podlet(
+        'podlet-registered-name-2',
+        5191,
+        {
+            js: '/podlet-registered-name-2.js',
+            css: '/podlet-registered-name-2.css',
+        },
+        { failing: true },
+    );
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5190/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5191/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+        const stream = await res.podiumStream();
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5192), 0);
+
+    const result = await fetch('http://0.0.0.0:5192');
+    const html = await result.text();
+
+    t.match(html, /<div><\/div><div><\/div>/, '');
+
+    p1.stop();
+    p2.stop();
+    l1.stop();
+});
+
+tap.test('HTTP Streaming - one slow podlet times out', async (t) => {
+    const p1 = podlet('podlet-registered-name-1', 5194, {
+        js: '/podlet-registered-name-1.js',
+        css: '/podlet-registered-name-1.css',
+    });
+    const p2 = podlet(
+        'podlet-registered-name-2',
+        5195,
+        {
+            js: '/podlet-registered-name-2.js',
+            css: '/podlet-registered-name-2.css',
+        },
+        { slow: true },
+    );
+
+    const app = express();
+    const layout = new Layout({ name: 'my-layout', pathname: '/' });
+    const p1Client = layout.client.register({
+        name: 'podlet-registered-name-1',
+        uri: 'http://0.0.0.0:5194/manifest.json',
+    });
+    const p2Client = layout.client.register({
+        name: 'podlet-registered-name-2',
+        uri: 'http://0.0.0.0:5195/manifest.json',
+    });
+    app.use(layout.middleware());
+    app.get(layout.pathname(), async (req, res) => {
+        const incoming = res.locals.podium;
+        const p1fetch = p1Client.fetch(incoming);
+        const p2fetch = p2Client.fetch(incoming);
+        const stream = await res.podiumStream();
+        const [p1Content, p2Content] = await Promise.all([p1fetch, p2fetch]);
+        stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+        stream.done();
+    });
+    const l1 = stoppable(app.listen(5196), 0);
+
+    const result = await fetch('http://0.0.0.0:5196');
+    const html = await result.text();
+
+    t.match(
+        html,
+        /<div><div>podlet-registered-name-1<\/div><\/div><div><\/div>/,
+        '',
+    );
+
+    p1.stop();
+    p2.stop();
+    l1.stop();
+});
+
+tap.test(
+    'HTTP Streaming - failing podlet - begin streaming before podlets return content',
+    async (t) => {
+        const p1 = podlet('podlet-registered-name-1', 5197, {
+            js: '/podlet-registered-name-1.js',
+            css: '/podlet-registered-name-1.css',
+        });
+        const p2 = podlet(
+            'podlet-registered-name-2',
+            5198,
+            {
+                js: '/podlet-registered-name-2.js',
+                css: '/podlet-registered-name-2.css',
+            },
+            { failing: true },
+        );
+
+        const app = express();
+        const layout = new Layout({ name: 'my-layout', pathname: '/' });
+        const p1Client = layout.client.register({
+            name: 'podlet-registered-name-1',
+            uri: 'http://0.0.0.0:5197/manifest.json',
+        });
+        const p2Client = layout.client.register({
+            name: 'podlet-registered-name-2',
+            uri: 'http://0.0.0.0:5198/manifest.json',
+        });
+        app.use(layout.middleware());
+        app.get(layout.pathname(), async (req, res) => {
+            const incoming = res.locals.podium;
+            const p1fetch = p1Client.fetch(incoming);
+            const p2fetch = p2Client.fetch(incoming);
+            const stream = await res.podiumStream();
+            stream.send(`<div>Send initial HTML</div>`);
+            const [p1Content, p2Content] = await Promise.all([
+                p1fetch,
+                p2fetch,
+            ]);
+            stream.send(`<div>${p1Content}</div><div>${p2Content}</div>`);
+            stream.done();
+        });
+        const l1 = stoppable(app.listen(5199), 0);
+
+        const result = await fetch('http://0.0.0.0:5199');
+        const html = await result.text();
+
+        t.match(html, /<div>Send initial HTML<\/div>/, '');
+        t.match(
+            html,
+            /<div><div>podlet-registered-name-1<\/div><\/div><div><\/div>/,
+            '',
+        );
+
+        p1.stop();
+        p2.stop();
+        l1.stop();
+    },
+);