@chilts/weave 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,303 @@
+# Changelog
+
+All notable changes to `@chilts/weave` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the version is below `1.0.0`, breaking changes may land in minor releases.
+
+## [Unreleased]
+
+## [0.8.0] - 2026-10-22
+
+### Added
+
+- **`unless`.** `unless cond` renders its block when `cond` is falsy,
+  compiling to the same ternary as `if !(cond)`. It is a guard only: an
+  `else` or `else if` after it is a compile error asking for an `if` with the
+  branches swapped. Previously `unless` was a compile error pointing at
+  `if !(cond)`.
+
+- **Class arrays/objects and style objects.** `class=` accepts an array
+  (nested, with `null`/`undefined`/`false`/`""` dropped) or an object whose
+  truthy keys are kept, also when merged with shorthand classes:
+  `li.item(class=({ active: isActive }))` renders `class="item active"`.
+  `style=` accepts an object: `div(style=({ marginTop: 0 }))` renders
+  `style="margin-top:0"`. Previously these rendered `class="a,b"` or
+  `[object Object]`. The `Attrs` type now types `class` and `style` with the
+  new exported `ClassValue` and `StyleValue` types, and `mergeClass()` accepts
+  any `ClassValue`.
+
+- **htmx example and docs.** A new `examples/htmx/` shows a page and the
+  fragment endpoints that reuse its mixin, and the README describes using
+  Weave for server-rendered apps.
+
+- **`for ... else`.** An `else` after a `for` renders when the collection is
+  empty.
+
+- **Mixin call-site content.** A bare `block` inside a mixin renders the
+  content indented under the call (`+card("Hi")` followed by indented lines),
+  with indented lines under `block` as its default. The mixin gains a
+  `block?: () => unknown` parameter after `attrs`; a call with content passes
+  `{}` for `attrs` when it has none. One line of content can also go on the
+  call's own line, as for an element: `+btn("save") Save` or
+  `+btn("save")(class="wide")= label`. A call can't have both inline and
+  indented content (a `ParserError`). Previously text after a mixin call was
+  dropped without a word, so the button rendered empty.
+
+- **Type errors mapped back to `.weave`.** `mapDiagnostic()` takes a
+  diagnostic reported by `tsc` against a compiled `.ts` file and uses the
+  `.ts.map` written beside it to translate it to the `.weave` file, line and
+  column; `formatDiagnostic()` prints it like a `LexerError`, with a code
+  frame. An error inside a TS expression points at the exact token: in
+  `h1= user.nmae` it lands on `nmae`, not `h1`. This covers buffered code,
+  `#{}` interpolations, attribute values, `if`/`else if` conditions, `for`
+  headers, `template`/`mixin` params, and mixin call and `extends` args,
+  including every line of a multi-line param list. An error in code weave
+  generated around them points at the start of the node.
+  `decodeMappings()`, `originalPosition()` and
+  `formatCodeFrame()` are exported too. The API takes plain
+  `{ file, line, col, message }` objects, so it does not depend on the
+  `typescript` package.
+
+- **`weave check`.** `weave check views/ lib/views/` compiles the templates,
+  type-checks the whole project against its `tsconfig.json` (or
+  `--project <path>`), and prints every error — those in a compiled view at
+  their `.weave` file, line and column with a code frame, the rest as-is —
+  followed by `Found N errors.` It exits 1 on any compile or type error, so it
+  can stand in for `tsc --noEmit` in CI. It loads the project's own
+  `typescript`, now an optional peer dependency. `--watch` is not supported
+  yet.
+
+### Changed
+
+- **Layouts declare their own `<Name>Blocks` type.** The compiler now emits
+  an exported `<Name>Blocks` interface (one optional `() => unknown` member
+  per `block`) above each template with slots, instead of splicing the name
+  into the first `import type` and requiring you to write the interface.
+  This works with no type import and with several layouts in one file.
+  **Breaking:** delete any hand-written `<Name>Blocks` interface, or `tsc`
+  reports a duplicate identifier.
+
+- `for` loops now compile to the new `each()` runtime helper instead of
+  `.map()`, so compiled templates import `each` from `@chilts/weave`.
+
+- Text with `#{}` interpolation now compiles to the new `interpolate` tagged
+  template (``h("h1", {}, interpolate`Hello ${name}`)``), so compiled
+  templates import `interpolate` from `@chilts/weave`. An interpolated `null`
+  or `undefined` now renders nothing, the same as `p= value`, where it used
+  to print `null` or `undefined`.
+
+### Fixed
+
+- `raw()` and mixin output inside `#{}` were escaped: `p Hi #{raw(html)}`
+  rendered `Hi &lt;b&gt;...` and `p By #{userLink(author, {})}` showed the
+  link's markup as text. Interpolated values now render exactly as element
+  children do, so both come out as HTML.
+- A bare `block` inside a mixin compiled to invalid TypeScript
+  (`blocks.?.()`) and content indented under a mixin call was silently
+  dropped. A bare `block` outside a mixin, or a named block inside one, is now
+  a `CodegenError`.
+- `for` over a non-array iterable (`xs.entries()`, `Set`, `Map`, a generator)
+  rendered `[object Iterator Helper]` or failed to type-check; any iterable
+  now works.
+- The `Attrs` type now accepts `null`, so `a(href=x)` with `x: string | null`
+  type-checks; the runtime already omitted `null` attributes.
+- Templates return `SafeHtml`, not a string, despite 0.4.0's note that they
+  return strings directly: only doctype-led templates ever did, by accident,
+  and 0.5.0 ended that. `SafeHtml` is now the documented contract for templates
+  and mixins alike, so nested output is never escaped twice; call `String()` on
+  it for the HTML. The README's Express example passed the result straight to
+  `res.send()`, which sends it as JSON; it now calls `String()` first.
+- A mixin that never uses `attrs` compiled to an unused `attrs` parameter,
+  failing `tsc` under `noUnusedParameters`; it is now named `_attrs`. The
+  parameter stays, so call sites may still pass extra attributes.
+- A template with a single root element indented that element's children one
+  level too deep in the compiled `.ts`. Cosmetic only; the output is unchanged.
+- Pug syntax that Weave doesn't support no longer mis-parses silently; each
+  form is now a `LexerError` that names the Weave alternative. `p!= x` used to
+  drop `x`; block expansion (`li: a Home`) and anything else run onto an
+  element (`a(href="/")Home`, `br/`) dropped the rest of the line; `p.` emitted
+  `class=""` and turned its text into elements; `- const x = 1` became a `-`
+  element; and `case`, `when`, `default`, `each`, `while`, `unless`, `append`
+  and `prepend` became elements of those names. Tag interpolation
+  (`p Hello #[strong world]`) and unescaped interpolation (`p Hi !{html}`)
+  rendered their markup characters as text; `!{html}` now points at
+  `#{raw(html)}`. Empty `.` / `#` shorthands and tag names that don't start
+  with a letter are rejected too.
+- `block` took the rest of its line as the slot name, so Pug's
+  `block append scripts` compiled to invalid TypeScript
+  (`blocks.append scripts?.()`). A block name must now be a single identifier,
+  or it is a `LexerError`; `block append` / `block prepend` (and bare
+  `append` / `prepend`) point at adding a second, empty slot to the layout
+  (`block pageScripts` after `block scripts`) and filling that instead.
+
+## [0.7.0] - 2026-10-20
+
+### Added
+
+- **Escaped dots in class and id shorthand.** `.gap-1\.5` is the single class
+  `gap-1.5`, so Tailwind's fractional spacing classes work as shorthand.
+- **Multi-line parameter lists.** The parentheses after `template`, `mixin`,
+  `extends`, `for` and a mixin call may now wrap over several lines, staying
+  open until they balance, so a long destructured signature can be written
+  the way TypeScript is normally wrapped. Continuation lines must be indented
+  under the opening line (a closing line such as `}: Props)` may sit level with
+  it). A string inside must close on its own line, and `//` comments are
+  dropped from the output. The compiled code keeps the wrapped layout, adding
+  `attrs`/`blocks` on a line of their own when the `)` was on its own line.
+- **Emacs mode understands context.** `weave-mode` now follows multi-line
+  attribute and parameter lists and raw (`tag!`) blocks when highlighting and
+  indenting, highlights attribute names, aligns `else` with its `if`, and
+  cycles outwards on repeated TAB. An apostrophe in text no longer opens a
+  string, `//` in a URL is no longer a comment, and `.`/`#` are only coloured
+  as a class or id where they really are one.
+
+### Fixed
+
+- A dotted class such as `.gap-1.5` was silently split into `gap-1` plus a
+  stray class `5`. A shorthand class that is a bare number is now a
+  `LexerError` that names the split and suggests escaping the dot.
+- `include ./partials` imported a binding named after the file (`partials`)
+  instead of the mixins the template calls, so a file defining several
+  mixins, or one not named after its file, compiled to code that failed in
+  `tsc`. The compiler now reads the included file and imports only the mixins
+  called (`import { badge, chip } from './partials.js'`). Calling a mixin that
+  no include or local definition provides is a `CodegenError`. For API users,
+  `compile()`, `compileWithSourceMap()` and `generate()` take an optional
+  `resolveInclude`. Without it, a lone include provides every called mixin
+  that isn't defined locally, and several includes are an error.
+- Shorthand classes combined with a non-literal `class=` value leaked the
+  value's string form: `div.pt-4(class=undefined)` rendered
+  `class="pt-4 undefined"`, as did the usual conditional-class pattern
+  `class=(on ? "x" : undefined)` whenever it was off. Non-literal values are
+  now merged at render time by a new `mergeClass()` runtime helper, which
+  drops `undefined`, `null`, `false` and `""`. An attribute whose value is
+  `null` is now omitted instead of rendering as `"null"`.
+- A template literal with a `${...}` interpolation inside a mixin call's
+  arguments, or a `template`/`mixin` parameter list, failed with
+  "Unterminated parentheses". A string containing a brace inside the
+  interpolation is also handled.
+- Error locations and source maps now point at the start of a token rather
+  than just past its end — for example, a mixin call is located at its `+`
+  instead of its argument list.
+- In watch mode, changing an included file now recompiles the templates that
+  include it, so a newly added mixin is picked up without touching each page.
+  The start-up reconcile likewise recompiles a template whose include is
+  newer than its output.
+- Rebuilding with `--no-sourcemap` now removes a `.ts.map` left over from an
+  earlier build instead of leaving a map that no longer matches its `.ts`.
+
+## [0.6.0] - 2026-10-19
+
+### Added
+
+- **Multi-line attribute lists.** End a line with the opening `(` to spread an
+  element's attributes over several lines — one attribute per line, indented
+  under the element, closed by a `)` on a line of its own. Works for mixin call
+  attributes too. Anything after the closing `)` is read as trailing content.
+  Attribute values follow exactly the same rules as the inline form.
+
+### Changed
+
+- **Breaking: every attribute must have a value.** The Pug-style valueless
+  boolean shorthand has been removed — `input(disabled)` no longer compiles.
+  Boolean attributes are now written with an explicit boolean value:
+  `disabled=true`, `disabled=false`, or an expression `disabled=isActive`
+  (the runtime renders a bare attribute for `true` and omits it for `false`
+  or `undefined`). Do not use a quoted `disabled="false"` — in HTML any
+  attribute that is present counts as true.
+- A bare (unquoted) attribute value must be a single token. Multi-token
+  expressions such as a ternary or string concatenation must be wrapped in
+  parentheses (`class=(wide ? "a" : "b")`) or backticks
+  (``class=`${wide ? "a" : "b"}` ``), because a space separates one
+  attribute from the next.
+
+### Fixed
+
+- The lexer no longer hangs and aborts the process (SIGABRT) on a multi-token
+  bare attribute value; it now raises a clear `LexerError` with line and
+  column, pointing you to wrap the expression.
+- `main(class=a b)` is rejected with a message offering both readings
+  (`class="a b"` as one value, or `class=a b="..."` as two attributes)
+  instead of silently parsing as `class="a"` plus a boolean `b`.
+- An attribute list that ran off the end of its line was accepted as if it had
+  been closed, so the following lines were lexed as child elements — attribute
+  names became tags and their values rendered as visible text, and the stray
+  `)` could leak into the generated TypeScript. It is now a `LexerError`
+  anchored on the opening `(`.
+- Watch mode reconciles the output tree on start so edits made while the
+  watcher was down are not missed.
+- Watch mode on Linux stopped seeing a template after the first time an editor
+  saved it atomically (write a temp file, rename it over the original), so
+  later edits were never recompiled. Each directory now has its own watcher,
+  which survives atomic saves, and subdirectories created while watching are
+  picked up — including any templates already written into them.
+- Deleting a `.weave` template now removes its compiled `.ts` from the output
+  directory (in one-shot builds and in watch mode). The output directory is
+  treated as owned by Weave: any `.ts` with no matching `.weave` is removed.
+- A mixin, or a block's default content, with more than one root element
+  referenced `Fragment` without importing it, so the compiled file failed to
+  type-check. `Fragment` is now imported whenever it is used.
+
+### Removed
+
+- Source maps are no longer included in the published npm bundle.
+
+## [0.5.0] - 2026-06-11
+
+### Fixed
+
+- Multi-level `extends` and `doctype` now generate type-safe output.
+
+## [0.4.0] - 2026-04-05
+
+### Changed
+
+- Compiled templates return strings directly instead of arrays, simplifying
+  the generated output and how templates compose.
+
+## [0.3.0] - 2026-04-05
+
+### Added
+
+- Raw block syntax (`tag!`) for passing literal, unescaped content through to
+  the output (inline CSS, JavaScript, etc.).
+- Emacs major mode with syntax highlighting, indentation, and comment support.
+
+### Documentation
+
+- Added guidance on special characters and the single-pass escaping model to
+  the README.
+
+## [0.2.0] - 2026-04-05
+
+### Added
+
+- A bare `|` (pipe) on its own line emits a single space, for adding
+  whitespace between sibling elements.
+
+## [0.1.0] - 2026-04-05
+
+Initial release — the Weave compiler and runtime.
+
+### Added
+
+- Template syntax compiling `.weave` files to typed TypeScript functions:
+  templates, mixins, `extends`/`block` layouts, conditionals, iteration,
+  includes, interpolation, buffered expressions, and silent/pass-through
+  comments.
+- Runtime helpers: `h`, `doctype`, `Fragment`, `raw`, and single-pass escaping.
+- CLI `compile` command and a `--watch` mode for automatic recompilation.
+- Error messages with source code frames.
+- Source map generation.
+
+[Unreleased]: https://codeberg.org/chilts/weave/compare/v0.8.0...HEAD
+[0.8.0]: https://codeberg.org/chilts/weave/compare/v0.7.0...v0.8.0
+[0.7.0]: https://codeberg.org/chilts/weave/compare/v0.6.0...v0.7.0
+[0.6.0]: https://codeberg.org/chilts/weave/compare/v0.5.0...v0.6.0
+[0.5.0]: https://codeberg.org/chilts/weave/compare/v0.4.0...v0.5.0
+[0.4.0]: https://codeberg.org/chilts/weave/compare/v0.3.0...v0.4.0
+[0.3.0]: https://codeberg.org/chilts/weave/compare/v0.2.0...v0.3.0
+[0.2.0]: https://codeberg.org/chilts/weave/compare/v0.1.0...v0.2.0
+[0.1.0]: https://codeberg.org/chilts/weave/src/tag/v0.1.0

package/ReadMe.md

@@ -12,7 +12,7 @@ Pug is great. Weave takes the same indentation-based syntax and makes it TypeScr
 
 - **Type-safe templates** — template parameters are real TypeScript types
 - **Type-safe mixins** — positional args with TS type annotations
-- **Tailwind-friendly** — class names with colons (`.md:flex`, `.hover:bg-blue-500`) just work
+- **Tailwind-friendly** — class names with colons (`.md:flex`, `.hover:bg-blue-500`) just work, and dots escape (`.gap-1\.5`)
 - **Single-pass escaping** — values are escaped once at render time, never pre-escaped
 - **No runtime template engine** — compiled output is plain TypeScript
 
@@ -66,9 +66,40 @@ export function simple({ title, content }: SimpleProps) {
 
 Now `tsc` catches type errors, your IDE gives you autocomplete, and calling `simple({ title: "Hello", content: "World" })` returns HTML.
 
+### Type-checking templates
+
+`tsc` reports errors against the compiled `.ts`, which you never edit.
+`weave check` compiles the templates, type-checks your whole project with your
+`tsconfig.json`, and reports each error in a view at its `.weave` line:
+
+```
+$ npx weave check views/ lib/views/
+weave: views/page.weave:3:5: Property 'nmae' does not exist on type '{ name: string; }'. TS2339
+ 3 |     h1= user.nmae
+   |     ^
+
+Found 1 error.
+```
+
+It exits 1 on any error, so it can replace `tsc --noEmit` in CI, and the
+`file:line:col:` format works with Emacs `compile`. It uses your project's
+`typescript` package (install it as a dev dependency) and the nearest
+`tsconfig.json`, or the one given with `--project <path>`. Errors point at the
+exact token inside an expression, attribute value, condition, parameter or
+argument, and at the start of the node for code Weave generated around them.
+
+To map diagnostics yourself (from another tool or build step), use
+`mapDiagnostic({ file, line, col, message })`, which translates a position in a
+compiled `.ts` file to its `.weave` source via the `.ts.map` beside it, and
+`formatDiagnostic()`, which prints the result with a code frame. Neither
+depends on the `typescript` package.
+
 ## Usage
 
-Templates are just functions that return strings, so they work with any framework:
+Templates are just functions that return HTML, so they work with any framework.
+Every template and mixin returns a `SafeHtml`, so its output isn't escaped
+again when nested in another template. Call `String()` on it to get the HTML
+string:
 
 ```typescript
 import express from 'express'
@@ -77,12 +108,56 @@ import { simple } from './lib/views/simple.js'
 const app = express()
 
 app.get('/', (req, res) => {
-    res.send(simple({ title: "Hello", content: "World" }))
+    res.send(String(simple({ title: "Hello", content: "World" })))
 })
 
 app.listen(3000)
 ```
 
+### Server-rendered apps and htmx
+
+Weave is a good fit for apps that render HTML on the server and swap pieces of
+it into the page — [htmx](https://htmx.org), Turbo, Unpoly, or plain `fetch`.
+
+- **Every template and mixin is an exported function.** Rendering a fragment
+  for a swap is just calling the mixin; there is no partial-rendering API.
+- **The page and its fragments share one definition.** The page loops over
+  `+todoItem(todo)`, and the endpoint returns `todoItem(todo)`, so the markup
+  can't drift apart.
+- **No runtime engine, zero dependencies.** The runtime is a few small helpers
+  with no Node-specific imports, so compiled views run on Node, Deno, Bun and
+  Cloudflare Workers alike.
+
+A mixin for one row:
+
+```
+mixin todoItem(todo: Todo)
+  li.todo(id=`todo-${todo.id}` ...attrs)
+    input(
+      type="checkbox"
+      checked=todo.done
+      hx-post=`/todos/${todo.id}/toggle`
+      hx-target=`#todo-${todo.id}`
+      hx-swap="outerHTML"
+    )
+    span= todo.text
+```
+
+The page uses it in a loop, and the toggle endpoint returns just that row:
+
+```typescript
+import { todoItem } from './lib/views/components/todo.js'
+
+// POST /todos/:id/toggle
+todo.done = !todo.done
+return new Response(String(todoItem(todo)), {
+    headers: { 'content-type': 'text/html; charset=utf-8' },
+})
+```
+
+See [`examples/htmx/`](examples/htmx/) for the full page, the mixin, and a
+web-standard `fetch` handler serving both.
+
 ## Syntax
 
 Weave's syntax will be familiar if you've used Pug.
@@ -97,6 +172,14 @@ p.intro This is a paragraph with a class
 a(href="/about" class="nav-link") About
 ```
 
+A `.` always starts a new class, so a class name that contains a dot — like Tailwind's `gap-1.5` — must escape it with a backslash:
+
+```pug
+.flex.gap-1\.5.px-2\.5
+```
+
+An unescaped `.gap-1.5` would split into `gap-1` and a stray `5`, so a class that is a bare number is rejected with an error pointing at the fix.
+
 ### Attributes
 
 Attributes live inside parentheses and are separated by spaces. **Every attribute must have a value** — there is no valueless shorthand:
@@ -115,7 +198,7 @@ button(class=`btn-${variant}`)= label
 
 #### Boolean attributes
 
-Write the boolean explicitly. The runtime renders `true` as a bare attribute and omits the attribute entirely when the value is `false` or `undefined`:
+Write the boolean explicitly. The runtime renders `true` as a bare attribute and omits the attribute entirely when the value is `false`, `undefined` or `null`:
 
 ```
 input(type="checkbox" checked=true)      →  <input type="checkbox" checked>
@@ -125,6 +208,34 @@ input(type="checkbox" checked=isActive)  →  omitted when isActive is false
 
 Avoid a quoted `checked="false"` — in HTML any attribute that is present counts as true, so that renders as checked.
 
+#### Combining shorthand classes with `class=`
+
+Shorthand classes and a `class=` value are merged into one attribute. The shorthand classes are always kept; a value of `undefined`, `null`, `false` or `""` just adds nothing:
+
+```
+div.pt-4(class="mt-2")                         →  <div class="pt-4 mt-2">
+div.pt-4(class=undefined)                      →  <div class="pt-4">
+div.btn(class=(active ? "active" : undefined)) →  <div class="btn"> when active is false
+```
+
+#### Class arrays and objects, style objects
+
+`class=` also takes an array or an object, which suits conditional Tailwind classes. Arrays may nest and drop `null`, `undefined`, `false` and `""`; an object keeps each key whose value is truthy. Both merge with shorthand classes:
+
+```
+div(class=(["a", "b"]))                        →  <div class="a b">
+li.item(class=({ active: isActive }))          →  <li class="item active"> when isActive is true
+a(class=(["link", { "md:flex": wide }]))       →  <a class="link md:flex"> when wide is true
+```
+
+`style=` takes an object of properties. camelCase keys become kebab-case, `--custom` properties are kept as written, and `null`, `undefined`, `false` and `""` values are dropped:
+
+```
+div(style=({ marginTop: 0, "--gap": gap }))    →  <div style="margin-top:0;--gap:1rem">
+```
+
+An array or object that yields nothing omits the attribute entirely. Numbers are not given units, so write `"4px"` rather than `4` where CSS needs one.
+
 #### Multi-token values must be wrapped
 
 Because a space separates one attribute from the next, a bare (unquoted) value has to be a single token. Wrap anything longer in parentheses or backticks:
@@ -188,14 +299,28 @@ else
   p Welcome, visitor
 ```
 
+`unless cond` is a guard: its block renders when `cond` is falsy, the same as
+`if !(cond)`. It takes no `else` or `else if` — `unless … else` is a double
+negative, so write an `if` with the branches swapped instead:
+
+```
+unless user.verified
+  p Please confirm your email address.
+```
+
 ### Iteration
 
 ```
 for ( const post of posts )
   h2= post.title
   p= post.content
+else
+  p No posts yet.
 ```
 
+The optional `else` renders when the collection is empty. Any iterable works —
+arrays, `Set`, `Map`, generators, or `xs.entries()` — and it is consumed once.
+
 ### Mixins
 
 Mixins use positional args. An implicit `attrs` parameter captures any extra attributes passed at the call site.
@@ -215,6 +340,42 @@ Usage:
 +button("Delete", "secondary")(class="ml-4" data-confirm="true")
 ```
 
+#### Call-site content
+
+A bare `block` inside a mixin renders whatever is indented under the call,
+so one mixin can wrap different content each time. Lines indented under
+`block` are the default when the call has none, and `if block` tests for it:
+
+```
+mixin card(title: string)
+  .card(...attrs)
+    h2= title
+    block
+      p.muted Nothing to show.
+```
+
+```
++card("Profile")(class="wide")
+  p= user.name
+  p= user.email
++card("Recent activity")
+```
+
+The content is passed as a callback after `attrs`, so the call above compiles
+to `card("Profile", { class: "wide" }, () => ...)`. Named blocks (`block
+content`) are layout slots and are not allowed inside a mixin. See
+[`examples/mixin-block/`](examples/mixin-block/).
+
+One line of content can go on the call's own line instead, just as an
+element takes inline text or `= expr`:
+
+```
++btn("save") Save
++btn("save")(class="wide")= label
+```
+
+A call takes its content inline or indented, not both.
+
 ### Layouts with extends and blocks
 
 A layout defines named blocks as content slots:
@@ -232,6 +393,17 @@ template layout({ title }: LayoutProps)
         p © 2024
 ```
 
+The compiled layout takes its slots as a second `blocks` argument, typed by an
+interface the compiler generates from the `block` names — you don't write it:
+
+```ts
+export interface LayoutBlocks {
+    content?: () => unknown
+}
+
+export function layout({ title }: LayoutProps, blocks: LayoutBlocks = {}) {
+```
+
 A page extends the layout, filling in the blocks. Data is passed explicitly — nothing is implicitly inherited:
 
 ```
@@ -244,6 +416,32 @@ template home({ title, welcomeMessage }: HomeProps)
 
 Blocks can have default content in the layout. If a page doesn't override a block, the default renders.
 
+### Long parameter lists
+
+The parentheses after `template`, `mixin`, `extends`, `for` and a mixin call hold
+TypeScript, which Weave copies through untouched. They can wrap over several lines
+however TypeScript usually wraps: the group simply stays open until its parentheses
+balance.
+
+```
+template dashboard({
+    title,
+    user,
+}: DashboardProps)
+  h1= title
+
++card(
+    post.title,
+    post.summary,
+)(class="mt-4")
+```
+
+Unlike a long attribute list there is no required shape, but continuation lines must
+be indented under the line that opens the group. The closing line may sit level with
+it if it starts with a closing bracket, as `}: DashboardProps)` does. So a forgotten
+`)` is reported where the indentation drops back. A string must close on the line it
+starts on, and `//` comments are allowed but left out of the compiled output.
+
 ### Includes
 
 Include another `.weave` file to use its mixins:
@@ -258,6 +456,12 @@ template actionsPage({ title }: ActionsPageProps)
       +button("Save", "primary")
 ```
 
+An included file can define any number of mixins. Weave reads it and imports
+only the ones the template calls, so `include ./partials` followed by
+`+badge(...)` and `+chip(...)` compiles to
+`import { badge, chip } from './partials.js'`. Calling a mixin that is neither
+defined in the file nor provided by an include is a compile error.
+
 ### Text content
 
 Use `|` (pipe) to add literal text as a child of an element:
@@ -280,7 +484,7 @@ This renders as: `Hello <strong>user@example.com</strong>.` — with a space bet
 
 ### Inline elements
 
-Weave does not support inline element syntax (e.g. Pug's `#[strong bold]` tag interpolation). To mix elements within text, place each element on its own indented line and use `|` for spacing and text fragments.
+Weave does not support inline element syntax (e.g. Pug's `#[strong bold]` tag interpolation), and `#[` in text is a compile error. To mix elements within text, place each element on its own indented line and use `|` for spacing and text fragments. To show a literal `#[` (or `!{`), use a string expression: `p= "Use #[0] for the first item"`.
 
 ### Raw blocks
 
@@ -319,17 +523,65 @@ Standard TypeScript imports pass through to the compiled output:
 import type { BlogPost } from '../types/models.js'
 ```
 
+## Coming from Pug
+
+Most Pug templates read the same in Weave, but some Pug features are left out
+on purpose. Each one below is a compile error that names the Weave way to
+write it, rather than being silently mis-rendered.
+
+| Pug | Weave |
+|---|---|
+| `- const x = 1` (unbuffered code) | Templates hold no statements. Compute values in TypeScript before rendering, or use `tag= expr` |
+| `case` / `when` / `default` | `if` / `else if` / `else` |
+| `each x in xs`, `while` | `for ( const x of xs )`; for keys and values, `for ( const [k, v] of Object.entries(obj) )` |
+| `p!= html` | `p= raw(html)` |
+| `p Hi !{html}` | `p Hi #{raw(html)}` |
+| `a(href!=url)` | Attribute values are always escaped |
+| `p.` (block text) | `p!` for raw text, or `\|` lines for escaped text |
+| `li: a Home` (block expansion) | Put the child on its own indented line |
+| `#[strong bold]` (tag interpolation) | Put each element on its own line; see [Inline elements](#inline-elements) |
+| `foo/` (explicit self-closing) | Void elements like `br` and `img` close themselves |
+| `div&attributes(obj)` | `div(...obj)` |
+| `input(disabled)` | `input(disabled=true)`; see [Boolean attributes](#boolean-attributes) |
+| `extends ./layout` | `extends layout({ data })` calls the layout's template function and passes its data |
+
+**Filters** (`:markdown-it`, `include:markdown ./post.md`) are not supported
+and are not planned. Render the content in TypeScript and pass it in as a
+`raw()` value.
+
+**`block append` / `block prepend`** are not supported. A page replaces a
+layout's block completely. When pages need to add to what the layout already
+renders, give the layout a second, empty slot:
+
+```
+head
+  block scripts
+    script(src="/app.js")
+  block pageScripts
+```
+
+**Dynamic mixin calls** (`+#{name}()`) are not supported. Mixins are ordinary
+functions, so you can choose one at runtime with a buffered expression and
+pass `{}` for its `attrs`: `div= mixins[kind](item, {})`.
+
+**Implicit scope.** In Pug, included and extended templates can see their
+caller's variables. In Weave, data only travels explicitly: through template
+params, `extends layout({ ... })` and mixin args.
+
 ## Development
 
 ```bash
 npm run build       # compile TypeScript to dist/
-npm test            # run tests (vitest)
-npm run lint        # type-check without emitting (tsc --noEmit)
+npm test            # lint, then type-check, then run tests (vitest)
+npm run lint        # lint with ESLint
+npm run typecheck   # type-check without emitting (tsc --noEmit)
 ```
 
 ## Status
 
-Weave is in early design. The `examples/` directory contains paired `.weave` and `.ts` files that define the target syntax and expected compiler output. The compiler is under active development.
+Weave is usable today: the compiler, the `weave` CLI (with watch mode and source maps) and the runtime helpers are published on npm. It is still pre-1.0, so the syntax may change in a minor release — breaking changes are called out in [CHANGELOG.md](CHANGELOG.md).
+
+The `examples/` directory pairs each `.weave` template with its compiled `.ts`. Every example is compiled in the test suite and compared byte-for-byte against that file, so they double as a reference for what the compiler emits.
 
 ## Editor Support
 
@@ -341,6 +593,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the full details of each release.
 
 | Version | Date       | Highlights |
 |---------|------------|------------|
+| 0.7.0   | 2026-10-20 | Multi-line parameter lists; escaped dots in class shorthand; `include` imports the mixins it provides; context-aware Emacs mode |
 | 0.6.0   | 2026-10-19 | Multi-line attribute lists; every attribute requires a value (breaking); watch-mode fixes |
 | 0.5.0   | 2026-06-11 | Type-safe multi-level `extends` and `doctype` |
 | 0.4.0   | 2026-04-05 | Templates return strings directly |