mancha 0.24.2 → 0.25.1

package/docs/05_css.md

@@ -655,6 +655,25 @@ Two limitations:
 - **ESM only**: `scanAndInject` is exported from the module build, not from the global bundle loaded via a `<script>` tag.
 - **No shadow DOM**: `querySelectorAll` does not pierce a shadow root, so scanning a host element finds nothing inside it. Scanning the shadow root itself does inject rules, but they land in the main document's stylesheet, where shadow-boundary scoping stops them from applying. Style shadow content with its own stylesheet instead.
 
+## Getting the Rules as Text
+
+`injectCss` appends the stylesheets to `document.head`, which is the right thing almost always. When you need the CSS itself rather than a style tag in the head, each stylesheet is also exported as a function returning its text:
+
+```js
+import { basicCssRules, minimalCssRules, utilsCssRules } from "mancha/browser";
+
+minimalCssRules(); // Same rules as injectCss(["minimal"]).
+basicCssRules(); // The reset half of injectCss(["utils"]).
+utilsCssRules(); // The utility-class half of injectCss(["utils"]).
+```
+
+They take no arguments, touch no DOM, and return the same text on every call, so they can also run at build time or on the server. The two cases that need them:
+
+- **Shadow DOM**: rules in `document.head` do not cross a shadow boundary, so give the shadow root its own stylesheet built from these.
+- **Serving the CSS yourself**: write the text to a file at build time and link it, rather than shipping the rules inside the JavaScript bundle.
+
+Note that these are the full stylesheets. Rules for custom values like `w-[200px]` are injected on demand as Mancha renders them and are not part of this text.
+
 --- 
 
 *Generated automatically from `src/css_gen_utils.ts`*

package/docs/06_ssr.md

@@ -58,7 +58,7 @@ For a more complete example, see [examples/express](../examples/express).
 For servers hosted as worker runtimes, such as `Cloudflare Workers`, you will need to import a stripped down version of `mancha` that does not have the ability to read local files.
 
 ```js
-import { Renderer } from "mancha/dist/worker.js";
+import { Renderer } from "mancha/worker";
 import htmlIndex from "./index.html";
 import vars from "./vars.json";
 

package/docs/07_typescript.md

@@ -28,6 +28,30 @@ renderer.$.user = { name: "Alice", email: "alice@example.com" };
 
 The `$` proxy provides typed access to store values. Without a type parameter, the store accepts any properties.
 
+## The Shared Renderer Type
+
+Each entry point exports its own `Renderer`: `mancha` parses with jsdom, `mancha/browser` with the DOM, and `mancha/worker` with htmlparser2. All three extend `IRenderer`, which every entry point exports alongside them. It is the type to reach for when code has to work against whichever renderer it is handed — typically logic shared between the server and the client:
+
+```typescript
+import type { IRenderer } from "mancha";
+
+// Accepts the jsdom, browser and worker renderers alike.
+async function renderPage(renderer: IRenderer, html: string): Promise<string> {
+	const fragment = renderer.parseHTML(html);
+	return renderer.serializeHTML(await renderer.renderNode(fragment));
+}
+```
+
+`IRenderer` is also the `this` type of `RendererPlugin`, so it is needed to annotate a plugin written as a standalone function:
+
+```typescript
+import type { IRenderer, RendererPlugin } from "mancha";
+
+const logNodes: RendererPlugin = function (this: IRenderer, node) {
+	console.log(this.impl, node.nodeName);
+};
+```
+
 ## Type Checking (Experimental)
 
 **⚠️ This feature is experimental and may change in future versions.**

package/docs/10_security.md

@@ -88,15 +88,14 @@ value of `<img src=x onerror="...">`:
 subrenderer, so directives inside it execute, and in the browser a `<script>` element in that string
 runs when it is inserted.
 
-`:text` escapes markup, but it has one edge worth knowing: the text it writes **during mount** is
-still visited by the text-node plugin afterwards, so a value that itself contains `{{ ... }}` is
-evaluated as an expression. Values written by `:text` after mount are not rescanned, and neither is
-the result of a `{{ ... }}` substitution. Prefer `{{ ... }}` for values whose content you do not
-control. This is a bug rather than intended behavior, tracked as
-[#104](https://github.com/fresho-dev/mancha/issues/104); this paragraph goes away when it is fixed.
+`:text` escapes markup, and the text it writes is data: the renderer does not visit it again, so a
+value that itself contains `{{ ... }}` renders those braces verbatim instead of being evaluated. The
+same holds for the result of a `{{ ... }}` substitution. What `:text` does evaluate is its
+**attribute** — `:text="expr"` is an expression like every other directive — so the template still
+has to be one you trust; only the value flowing through it is data.
 
-So a value is safe in `{{ ... }}` and, with that caveat, in `:text`; it is unsafe everywhere else.
-This matters most for the values you do not choose yourself:
+So a value is safe in `{{ ... }}` and in `:text`; it is unsafe everywhere else. This matters most
+for the values you do not choose yourself:
 
 ```html
 <!-- Safe: URL query parameters, form input and API responses are escaped here,
@@ -110,9 +109,8 @@ This matters most for the values you do not choose yourself:
 <a :attr:href="$$next">Continue</a>
 ```
 
-The rule of thumb: untrusted values may only reach `{{ ... }}`, and `:text` subject to the note
-above. If you need untrusted markup, see
-[Isolating Untrusted Content](#isolating-untrusted-content).
+The rule of thumb: untrusted values may only reach `{{ ... }}` or `:text`. If you need untrusted
+markup, see [Isolating Untrusted Content](#isolating-untrusted-content).
 
 ## Whatever You Mount Is A Template
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mancha",
-	"version": "0.24.2",
+	"version": "0.25.1",
 	"description": "Javscript HTML rendering engine",
 	"main": "dist/index.js",
 	"type": "module",
@@ -15,10 +15,11 @@
 			"types": "./dist/browser.d.ts",
 			"default": "./dist/browser.js"
 		},
-		"./dist/*.js": {
-			"types": "./dist/*.d.ts",
-			"default": "./dist/*.js"
-		}
+		"./worker": {
+			"types": "./dist/worker.d.ts",
+			"default": "./dist/worker.js"
+		},
+		"./package.json": "./package.json"
 	},
 	"files": [
 		"dist",