feat(binding): add for component with each + item + #empty

AGENTS.md

@@ -881,3 +881,19 @@ After each change, ask:
 - [ ] Does AGENTS.md reflect the current architecture?
 - [ ] Are all public APIs documented in Package Exports Reference?
 - [ ] Are the docs pages accurate and up-to-date?
+
+### Binding structural components
+
+Renderer-specific `plugins/binding` entry points export `For` alongside `Binding` and `If`.
+`For` repeats default AST children for an array, with `item` and optional `index` aliases,
+optional item-property `key`, and an `#empty` slot. Core helpers `resolveForIterations`,
+`selectForBranch`, and `renderFor` live in `packages/comark/src/plugins/binding.ts`.
+`NodeRenderData.scope` preserves lexical loop aliases through descendant component props;
+attribute resolution exposes those aliases under `props`. Vue/React keyed fragments and
+Svelte keyed each blocks preserve iteration identity; Angular currently rebuilds descendants.
+Cross-renderer iteration cases live in `test/fixtures/for.ts`.
+
+Structural framework components use a generic `__comarkRender` hook returning
+`NodeRenderGroup[]` (key, AST children, render context, optional wrapper). Keep binding
+imports in optional adapters; base renderers consume this hook without importing binding
+helpers. `test/binding-bundle.test.ts` in each framework package verifies the exclusion.

docs/content/4.plugins/1.built-in/binding.md

@@ -1,6 +1,6 @@
 ---
 title: Binding
-description: "Interpolate data with `{{ path || default }}` and conditionally render content with `::if`."
+description: "Interpolate data with `{{ path || default }}` and conditionally render content with `::if`, and repeat content with `::for`."
 navigation:
   icon: i-lucide-replace
 seo:
@@ -18,7 +18,7 @@ links:
     variant: soft
 ---
 
-The `comark/plugins/binding` module lets you interpolate values with `{{ path || default }}` and conditionally render content with `::if`. Values can come from frontmatter, the renderer's `data` prop, the tree's `meta`, or a parent component's `props`.
+The `comark/plugins/binding` module lets you interpolate values with `{{ path || default }}` and conditionally render content with `::if`, and repeat content with `::for`. Values can come from frontmatter, the renderer's `data` prop, the tree's `meta`, or a parent component's `props`.
 
 The `binding()` parser plugin emits a `binding` component node whose `:value` attribute points at a dot-path. The [data binding](/syntax/components#data-binding) layer resolves that path against the ambient render context, so bindings work across HTML, ANSI, Vue, React, Svelte, Angular, and Nuxt, and round-trip back to their source form via `renderMarkdown`.
 
@@ -252,6 +252,81 @@ I am NOT fine and NOT happy.
 
 Each `#else` belongs to its enclosing component. Only the selected branch renders, and `as` wraps whichever branch is selected. Without an else slot, a failed condition produces no output. This works with all renderer-specific `If` exports.
 
+## Repeating content
+
+Register `For` alongside `Binding` to render Markdown once per array item:
+
+```typescript [render.ts]
+import { renderHtml } from '@comark/html'
+import binding, { Binding, For } from '@comark/html/plugins/binding'
+
+const markdown = `
+::for{:each="data.posts" item="post" key="id"}
+### {{ props.post.title }}
+
+{{ props.post.description }}
+#empty
+No posts published yet.
+::
+`
+
+const html = await renderHtml(markdown, {
+  plugins: [binding()],
+  components: { Binding, For },
+  data: {
+    posts: [{ id: 'hello', title: 'Hello', description: 'Our first post.' }],
+  },
+})
+```
+
+Iteration and comparison logic lives in the optional binding entry points. The base framework renderers retain a generic scoped-child hook, but do not import the `If` or `For` implementation.
+
+Import from your renderer's binding entry point (`html`, `ansi`, `vue`, `react`, `svelte`, `angular`, or `nuxt`). Register `For` directly in the component map. Like `If`, the block syntax uses the default component parser; `binding()` is only needed for `{{ … }}` interpolation.
+
+### Item and index aliases
+
+`item` names the current value in `props`; its default name is `item`. Add an `index` alias to expose the zero-based array position:
+
+```mdc
+::for{:each="data.posts" item="post" index="position" key="id"}
+{{ props.position }}: {{ props.post.title }}
+::
+```
+
+Arrays can contain objects or primitive values. Loop aliases remain available inside headings, attributed elements, and nested components. An inner loop can reference outer aliases; reusing an alias shadows it only within the inner loop. Aliases take precedence over component props of the same name and do not leak into following siblings.
+
+```mdc
+::for{:each="data.posts" item="post" key="id"}
+:::for{:each="props.post.tags" item="tag"}
+{{ props.post.title }}: {{ props.tag }}
+:::
+::
+```
+
+Register `If` too when combining loops with conditional content:
+
+```mdc
+::for{:each="data.posts" item="post" key="id"}
+:::if{:value="props.post.published"}
+{{ props.post.title }}
+#else
+Draft: {{ props.post.title }}
+:::
+::
+```
+
+### Empty lists
+
+`#empty` renders once when `each` is an empty array, `null`, or `undefined`. Without it, an empty list produces no output. Other non-array values are invalid. The default branch is not evaluated for an empty list, and the empty branch is not evaluated for a populated list. An explicit `#default` slot is also supported.
+
+### Stable keys
+
+`key="id"` reads each item's `id` property; nested paths such as `key="metadata.id"` work too. Values must be unique strings or finite numbers. Missing, invalid, or duplicate keys throw an error. Without `key`, iterations use their array positions.
+
+Vue, React, and Svelte use these keys to preserve an item's rendered components and uncontrolled input state when the array is reordered. Nuxt uses the Vue implementation. HTML and ANSI have no persistent DOM state. Angular currently rebuilds rendered descendants when its inputs change, so keys do not preserve component state there.
+
+`For` adds no wrapper element. Put wrapper elements inside its default slot when needed.
+
 ## Markdown round-trip
 
 When you re-serialize the AST with `renderMarkdown`, you can pass the core `Binding` handler to preserve the original `{{ … }}` shorthand:
@@ -382,6 +457,27 @@ import {
 } from 'comark/plugins/binding'
 ```
 
+### `For`
+
+Every renderer-specific binding entry point exports `For`. Register it with `components: { Binding, For }` when using interpolation inside loops.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `each` | `unknown[]`, `null`, or `undefined` | `undefined` | Array to iterate; nullish values select `#empty` |
+| `item` | `string` | `"item"` | Alias for the current item under `props` |
+| `index` | `string` | — | Optional alias for the zero-based array position |
+| `key` | `string` | — | Item property path used for stable identity |
+
+`item` and `index` must be distinct, non-empty names without dots or prototype keys. Slots: default content repeats per item; `#empty` renders once for an empty collection. See [Repeating content](#repeating-content) for Markdown examples and renderer-specific key behavior.
+
+The core binding entry point exports `ForProps`, `ForIteration`, `resolveForIterations(props, renderData)`, `selectForBranch(children, empty)`, and `renderFor(context)` for renderer adapters. Each iteration contains a key and a render context with lexical aliases in `scope`; attribute resolution makes those aliases available under `props`.
+
+### Structural renderer hooks
+
+Framework components can supply a `__comarkRender` hook that returns keyed groups of AST children. The renderer renders each group in its supplied context, optionally inside a wrapper element. The binding adapters attach their behavior to this hook so applications that do not import them exclude that behavior from their bundles.
+
+The hook uses the `NodeRenderContext`, `NodeRenderGroup`, and `NodeRenderHook` types exported by `comark`. Its context contains resolved `props`, unrendered `children`, and `renderData`; each returned group contains a `key`, `children`, `renderData`, and optional `wrapper`. Vue and React adapters receive an internal `__render` callback, which they invoke when rendering so inactive branches stay unevaluated.
+
 ## Use cases
 
 1. **Personalized content**: greet users by name from frontmatter or runtime data:

docs/content/8.examples/3.plugins/vue-vite-binding.md

@@ -1,6 +1,6 @@
 ---
-title: Binding (frontmatter + data)
-description: Example showing how to interpolate frontmatter and runtime data into Markdown using the Comark `binding` plugin in Vue and Vite.
+title: Binding, conditions, and loops
+description: Try live Markdown bindings, If branches, and For loops with editable posts in Vue and Vite.
 navigation:
   icon: i-lucide-replace
 ---
@@ -23,12 +23,26 @@ This example demonstrates the Comark `binding` plugin in a Vue + Vite app:
 - **Parent props** — nested components can reference their enclosing component's resolved attributes via `props.`.
 - **Typed values** — bindings come through as real JS values (strings, numbers, objects) thanks to the shared data-binding layer.
 
+## Try repeated content
+
+Run `pnpm dev:binding` from the repository root. In **Posts**, edit titles and descriptions, toggle **Published**, add or remove posts, or use **Reverse order**. **Clear posts** selects the `#empty` slot. **Reset** restores the initial posts. The highlighted **Source** view includes the `For` block and its nested `If`.
+
+```mdc
+::for{:each="data.posts" item="post" index="position" key="id"}
+### {{ props.post.title }}
+
+{{ props.post.description }}
+#empty
+No posts published yet.
+::
+```
+
 ## Usage
 
 1. Import the plugin and its matching Vue component:
 
    ```ts
-   import binding, { Binding } from '@comark/vue/plugins/binding'
+   import binding, { Binding, For, If } from '@comark/vue/plugins/binding'
    ```
 
 2. Wire them into `<Markdown>`:
@@ -37,7 +51,7 @@ This example demonstrates the Comark `binding` plugin in a Vue + Vite app:
    <Markdown
      :value="markdown"
      :plugins="[binding()]"
-     :components="{ Binding }"
+     :components="{ Binding, For, If }"
      :data="data"
    />
    ```

examples/3.plugins/vue-vite-binding/README.md

@@ -1,6 +1,6 @@
 ---
-title: Binding and conditional content
-description: Update Markdown bindings and If branches with live form controls using Vue and Vite.
+title: Binding, conditions, and loops
+description: Try live Markdown bindings, If branches, and For loops with editable posts in Vue and Vite.
 navigation:
   icon: i-lucide-replace
 category: Plugins
@@ -33,12 +33,26 @@ Run `pnpm dev:binding` from the repository root. Change the role, move the age s
 
 The layout follows [Vercel's design guidance](https://vercel.com/design.md), with Comark branding. It loads the published Vercel CSS foundation and Geist fonts over the network.
 
+## Try repeated content
+
+Run `pnpm dev:binding` from the repository root. In **Posts**, edit titles and descriptions, toggle **Published**, add or remove posts, or use **Reverse order**. **Clear posts** selects the `#empty` slot. **Reset** restores the initial posts. The highlighted **Source** view includes the `For` block and its nested `If`.
+
+```mdc
+::for{:each="data.posts" item="post" index="position" key="id"}
+### {{ props.post.title }}
+
+{{ props.post.description }}
+#empty
+No posts published yet.
+::
+```
+
 ## Usage
 
 1. Import the plugin and its Vue components:
 
    ```ts
-   import binding, { Binding, If } from '@comark/vue/plugins/binding'
+   import binding, { Binding, For, If } from '@comark/vue/plugins/binding'
    ```
 
 2. Wire them into `<Markdown>`:
@@ -47,7 +61,7 @@ The layout follows [Vercel's design guidance](https://vercel.com/design.md), wit
    <Markdown
      :value="markdown"
      :plugins="[binding()]"
-     :components="{ Binding, If }"
+     :components="{ Binding, For, If }"
      :data="data"
    />
    ```