jealouscloud · jealouscloud · Nov 10, 2025 · Sep 27, 2025 · Sep 27, 2025 · Oct 11, 2025
diff --git a/README.md b/README.md
@@ -177,10 +177,12 @@ a([tab]
   ```
 
 * 🎭 Type hints for the editor generated from WhatWG spec
-* ⚡ Live Reload server for rapid development  
+
+## Live Reload server for rapid development  
   Run your Python webserver (i.e. Flask, FastAPI, anything!) with live-reload superpowers powered by [livereload-js](https://www.npmjs.com/package/livereload-js). See browser updates in real-time!
 
-  Note: This feature requires optional dependencies. `pip install html-compose[live-reload]` or `pip install html-compose[full]`. The feature also fetches livereload-js from a CDN.
+  Note: This feature requires optional dependencies. `pip install html-compose[live-reload]` or `pip install html-compose[full]`. 
+  The feature also loads livereload-js from a CDN.
 
   `livereload.py`
   ```python

diff --git a/changelog.txt b/changelog.txt
@@ -1,3 +1,25 @@
+# 0.11.0
+* Add html_compose.resource module which includes 
+  js_import, css_import, and font_import helpers
+* html_compose.document: Add streaming document generators which will produce
+  head element before other content.
+* Add js/css/font composition along with other changes to html_compose.document
+* [breaking] Change HTML5Document into a class with a .render and .stream function
+  which wrap other functionality in the module. 
+  The signature is now different which may require updates.
+* HTML converter improvements: Survive round trip for more text. 
+  Output single elements when we identify an attribute could be a list
+* Documentation improvements
+  * Migrate element/attr docstrings to Google style.  
+    Pyright on Zed seems to tolerate this better.
+  * Fix a weird pylance bug on WatchCond
+* Live reload now accepts daemon host/port/timeout and can wait to send browser
+  reload until after the server responds
+* py.typed improvements to module exports
+* Child elements passed uninstantiated will be instantiated at render time
+  * This means you can `p['line 1', br, 'line 2']` where previously you had to `br()`
+* notebook.render accepts _HasHtml which includes documents and elements
+
 # 0.10.1
 * Style parameter: when input is a dict[str, str], assume the user wants simple f"{key}: {value}" css statements
 * Type hints: Cleanup type hints to all be 3.10 style

diff --git a/doc/ideas/03_code_generator.md b/doc/ideas/03_code_generator.md
@@ -1,20 +1,30 @@
 # Code Generator
+
 Idea: What if your editor had built-in hinting around HTML properties?
 
 ## Implementation
+
 We take information from the HTML spec living document and MDN.
 
 We place generated code in a separated directory, keeping magic out of the code.
 
 the `tools` directory contains:
- * The spec generator `spec_generator.py`
-   * Pull, parse, and dump json we think is interesting
- * The attribute code generator `generate_attributes.py`
-   * Put that interesting information in generated class attributes using our formula defined in previous specs. If an attribute is a keyword or restricted by Python, append `_` to the end of the name so autocomplete works. Dump those in `src/html_compose/attributes`
 
-* `tools/generated/*_attrs.py` is the intermediate directory so runs do not write to source control directory, but you can see when a new change has happened.
+- The spec generator `spec_generator.py`
+  - Pull, parse, and dump json we think is interesting
+- The attribute code generator `generate_attributes.py`
+  - Put that interesting information in generated class attributes using our
+    formula defined in previous specs. If an attribute is a keyword or
+    restricted by Python, append `_` to the end of the name so autocomplete
+    works. Dump those in `src/html_compose/attributes`
+- The element code generator `generate_elements.py`
+
+  - Same deal as for attributes. Dump in src/html_compose/elements.
+
+- `tools/generated/*.py` is the intermediate directory so runs do not write to
+  the source control directory, but you can see when a new change has happened.
 
 <!-- ## Extension of this idea:
 TBD
 
-caniuse data can be used to generate warnings based on browser targets -->
+caniuse data can be used to generate warnings based on browser targets -->
diff --git a/doc/ideas/04_attrs.md b/doc/ideas/04_attrs.md
@@ -105,7 +105,7 @@ div.hint.style({
 The implementation is the simplest `<key>: <value>. 
 User is therefore responsible for quoting.
 
-## `attrs=` parameter syntax
+## attrs= parameter syntax
 
 In the constructor for any element, you can specify the `attrs` parameter.
 
@@ -184,7 +184,7 @@ a(href="https://google.com", tabindex=1)
 Under the hood, it's all translated to the `BaseAttribute` class, and the value is
 escaped before rendering.
 
-# Breakdown
+## Breakdown
 
 There are a number of options for declaring an attribute value, which are shown above. 
 The basic idea is 
@@ -225,7 +225,7 @@ class htmx:
     '''
 
     @staticmethod
-    def hx_get(value: str) -> BaseAttribute:
+    def get(value: str) -> BaseAttribute:
         '''
         htmx attribute: hx-get
             The hx-get attribute will cause an element to issue a
@@ -244,7 +244,7 @@ Where we can write
 
 ```python
 button(
-    [htmx.hx_get("/api/data")], 
+    [htmx.get("/api/data")], 
     class_="btn primary"
 )["Click me!"]
 ```
diff --git a/doc/ideas/05_livereload.md b/doc/ideas/05_livereload.md
@@ -127,7 +127,7 @@ If you're using nginx, you would include something like this in your server bloc
     }
 ```
 
-Since you're serving your websocket over SSL, you can now specify when calling `live.server(`:
+Since you're serving your websocket over SSL, you can now specify when calling `live.server`:
 * `proxy_host`: host to reach for the livereload websocket. used in browser instead of `host` parameter.
 
     Example: `my-sweet-website.com`

diff --git a/doc/ideas/06_resource_imports.md b/doc/ideas/06_resource_imports.md
@@ -0,0 +1,263 @@
+# Resource imports (js / css / fonts)
+
+There are now many standards in the web platform for correctly importing
+your remote resources.
+
+We no longer need to use nodejs and bundling to use module import semantics.
+
+We can preload js and assign it a module name for importing.
+
+We give helpers for managing css/js imports and the many attributes needed
+to successfully preload and validate resource integrity.
+
+We also give two font helpers, one for fonts resolved in css and one for
+manually setting up .woff/etc font imports.
+
+## Browser tech overview
+
+- https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap
+- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
+- https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/modulepreload
+- https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/preload
+
+## How our library makes resource setup better
+
+By providing small helpers, we reduce the amount of redundant html to write.
+
+```python
+import html_compose.elements as el
+from html_compose.resource import css_import, js_import, to_elements
+from html_compose.document import document_generator
+
+def get_css():
+    return [
+        css_import("./static/admin.css", cache_bust=False),
+        css_import(
+            "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
+            hash=(
+                "sha384-9ndCyUaIbzAi2FUVXJi0CjmCapS"
+                "mO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM"
+            ),
+            crossorigin="anonymous",
+            preload=True,
+        ),
+    ]
+
+def get_js():
+    return [
+        js_import("./static/admin.js", name="admin", cache_bust=True),
+        js_import(
+            "https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm",
+            name="alpinejs",
+            preload=True,
+            hash=(
+                "sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/"
+                "9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p"
+            ),
+            crossorigin="anonymous",
+        ),
+    ]
+
+
+def get_fonts():
+    return [
+        font_import_manual(
+            "./static/fonts/MyFont.woff2",
+            family="MyFont",
+            weight="normal",
+            style="normal",
+            display="swap",
+            cache_bust=False,
+        ),
+        font_import_provider(
+            href="https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,100..900;1,100..900&display=swap",
+            preconnect=[
+                "https://fonts.googleapis.com",
+                "https://fonts.gstatic.com",
+            ],
+            preconnect_crossorigin="anonymous",
+        ),
+    ]
+
+
+
+def test_importer():
+    css = get_css()
+    js = get_js()
+    elements = to_elements(js, css)
+    print(el.head()[elements].render())
+
+
+def test_document_generator():
+    css = get_css()
+    js = get_js()
+    print(document_generator(
+        title="demo",
+        lang="en",
+        js=js,
+        css=css,
+        body_content=[el.h1("Hello world")])
+
+```
+
+**test_importer:**
+
+```html
+<head>
+  <link
+    href="https://fonts.googleapis.com"
+    crossorigin="anonymous"
+    rel="preconnect"
+  />
+  <link
+    href="https://fonts.gstatic.com"
+    crossorigin="anonymous"
+    rel="preconnect"
+  />
+  <link
+    href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
+    integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM"
+    crossorigin="anonymous"
+    as="style"
+    rel="preload"
+  />
+  <link
+    href="https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm"
+    integrity="sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p"
+    crossorigin="anonymous"
+    rel="modulepreload"
+  />
+  <link
+    href="./static/fonts/MyFont.woff2"
+    type="font/woff2"
+    as="font"
+    rel="preload"
+  />
+  <link href="./static/admin.css" rel="stylesheet" />
+  <link
+    href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
+    integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM"
+    crossorigin="anonymous"
+    rel="stylesheet"
+  />
+  <link
+    href="https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,100..900;1,100..900&amp;display=swap"
+    rel="stylesheet"
+  />
+  <style>
+    @font-face {
+      font-family: "MyFont";
+      src: url("./static/fonts/MyFont.woff2");
+      font-style: normal;
+      font-display: swap;
+      font-weight: normal;
+    }
+  </style>
+  <script type="importmap">
+    {
+      "imports": {
+        "admin": "./static/admin.js?ts=1760157623",
+        "alpinejs": "https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm"
+      }
+    }
+  </script>
+  <script src="./static/admin.js?ts=1760157623" type="module"></script>
+  <script
+    src="https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm"
+    type="module"
+    integrity="sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p"
+    crossorigin="anonymous"
+  ></script>
+</head>
+```
+
+**test_document**
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta content="width=device-width, initial-scale=1.0" name="viewport" />
+    <title>demo</title>
+    <link
+      href="https://fonts.googleapis.com"
+      crossorigin="anonymous"
+      rel="preconnect"
+    />
+    <link
+      href="https://fonts.gstatic.com"
+      crossorigin="anonymous"
+      rel="preconnect"
+    />
+    <link
+      href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
+      integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM"
+      crossorigin="anonymous"
+      as="style"
+      rel="preload"
+    />
+    <link
+      href="https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm"
+      integrity="sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p"
+      crossorigin="anonymous"
+      rel="modulepreload"
+    />
+    <link
+      href="./static/fonts/MyFont.woff2"
+      type="font/woff2"
+      as="font"
+      rel="preload"
+    />
+    <link href="./static/admin.css" rel="stylesheet" />
+    <link
+      href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
+      integrity="sha384-9ndCyUaIbzAi2FUVXJi0CjmCapSmO7SnpJef0486qhLnuZ2cdeRhO02iuK6FUUVM"
+      crossorigin="anonymous"
+      rel="stylesheet"
+    />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,100..900;1,100..900&amp;display=swap"
+      rel="stylesheet"
+    />
+    <style>
+      @font-face {
+        font-family: "MyFont";
+        src: url("./static/fonts/MyFont.woff2");
+        font-style: normal;
+        font-display: swap;
+        font-weight: normal;
+      }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "admin": "./static/admin.js?ts=1760157623",
+          "alpinejs": "https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm"
+        }
+      }
+    </script>
+    <script src="./static/admin.js?ts=1760157623" type="module"></script>
+    <script
+      src="https://cdn.jsdelivr.net/npm/alpinejs@3.15.0/+esm"
+      type="module"
+      integrity="sha384-Yf57wlxlrA1+0X6Ye9NOBxQ1tpmiwI/9mFpv9tT/Rh2UAajwwAlTWHnvTGYhgv7p"
+      crossorigin="anonymous"
+    ></script>
+  </head>
+
+  <body>
+    <h1>Hello world</h1>
+  </body>
+</html>
+```
+
+## Where to go from here
+
+We've informed the browser how to optimally and in parallel load our resources.
+
+Now we are free to develop without bundling javascript if we so desire.
+
+Heck, you could even map a package.json used in your development environment
+into a `js_import` generator.
+
+The sky is the limit.
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "html-compose"
-version = "0.10.1"
+version = "0.11.0"
 description = "Composable HTML generation in python"
 authors = [
     { name = "jealouscloud", email = "github@noaha.org" }