@funcstache/stache-stream 0.2.2 → 0.2.3

package/src/lib/plan_partials.md

@@ -0,0 +1,237 @@
+# Plan: Partials (`{{> name}}`)
+
+## Scope
+
+Implement `{{> name}}` partial tags per the [Mustache spec](https://mustache.github.io/mustache.5.html#Partials).
+
+---
+
+## Mustache Spec Summary
+
+- `{{> name}}` includes the partial named `name` rendered with the current context.
+- A partial missing from the context produces no output (spec: treated as empty string).
+- Standalone partial tags (only tag on a line, possibly with leading whitespace) consume the trailing newline; the leading whitespace becomes the indent prepended to every line of the partial's content.
+- Partials may be recursive.
+
+---
+
+## Resolved Decisions
+
+1. **Context mechanism** — `PartialTagContextLambda` is the only mechanism in v2. File loading is a client concern: the client receives the partial name via `Tag` and returns a `ReadableStream`. `TemplateName` remains a type alias for use by clients outside v2.
+2. **Missing partial** — Silently produces no output (spec compliant).
+3. **Indentation** — In scope; standalone detection and indent application are required.
+4. **Recursive partials** — No depth limit; the child `Template` approach handles it naturally.
+5. **`PartialTagContextRecord`** — Remove from `PartialTagContext`; it duplicates `Context`. See types change below.
+
+---
+
+## Changes Required
+
+### `types.ts`
+
+Remove `PartialTagContextRecord` from `PartialTagContext` and delete the interface:
+
+```typescript
+// Before
+export type PartialTagContext =
+  | PartialTagContextLambda
+  | PartialTagContextRecord
+  | TemplateName;
+
+export interface PartialTagContextRecord {
+  [key: string]: JsonType | PartialTagContextLambda | PartialTagContextRecord;
+}
+
+// After
+export type PartialTagContext = PartialTagContextLambda | TemplateName;
+```
+
+`Context` already covers object-shaped context values, so `PartialTagContextRecord` is redundant.
+
+---
+
+### `Template` (`template/Template.ts`)
+
+#### Indentation: deferred whitespace approach
+
+The spec's standalone/indent behavior requires knowing whether the partial tag is the only non-whitespace on its line. To support this, `Template` defers writing horizontal whitespace at the start of a line until it knows what follows. Non-whitespace text is always written immediately.
+
+New private state:
+
+```typescript
+#pendingWhitespace = "";     // horizontal whitespace buffered since last newline
+#lineHasContent = false;     // true if current line has non-whitespace already written
+#consumeNextNewline = false;
+```
+
+**`#handleText` change** — flush non-whitespace immediately; buffer only trailing horizontal whitespace on the current line:
+
+```typescript
+async #handleText(event: TokenizeTextEvent): Promise<void> {
+  let text = event.data;
+  // After a standalone partial the trailing newline belongs to the partial tag, not the output.
+  if (this.#consumeNextNewline) {
+    if (text.startsWith("\r\n")) text = text.slice(2);
+    else if (text.startsWith("\n")) text = text.slice(1);
+    this.#consumeNextNewline = false;
+    if (!text) return;
+  }
+
+  const lastNewlineEnd = lastNewlineIndex(text);
+  if (lastNewlineEnd !== -1) {
+    // Flush everything up to and including the last newline, then reset line state.
+    await this.#writeToOutput(this.#pendingWhitespace + text.slice(0, lastNewlineEnd));
+    this.#pendingWhitespace = "";
+    this.#lineHasContent = false;
+    text = text.slice(lastNewlineEnd);
+    if (!text) return;
+  }
+
+  // text contains no newlines — process as current-line fragment.
+  if (isHorizontalWhitespace(text)) {
+    this.#pendingWhitespace += text;
+  } else {
+    await this.#writeToOutput(this.#pendingWhitespace + text);
+    this.#pendingWhitespace = "";
+    this.#lineHasContent = true;
+  }
+}
+```
+
+`lastNewlineIndex` returns the index just past the last `\n` (or `\r\n`).
+`isHorizontalWhitespace` returns true if the string contains only spaces and tabs.
+
+`#pendingWhitespace` therefore only ever holds `[ \t]*` — at most a few characters — keeping memory overhead minimal even for large template files.
+
+**`#handlePartial` implementation:**
+
+```typescript
+async #handlePartial(event: TokenizeTagEvent): Promise<void> {
+  const partialContext = await this.getContextValue<PartialTagContextLambda>(event.data);
+  if (typeof partialContext !== "function") {
+    await this.#flushPendingWhitespace();
+    return;
+  }
+
+  // Standalone: current line has no non-whitespace content yet
+  const isStandalone = !this.#lineHasContent;
+  const indent = isStandalone ? this.#pendingWhitespace : "";
+
+  if (isStandalone) {
+    this.#pendingWhitespace = "";
+    this.#consumeNextNewline = true;
+  } else {
+    await this.#flushPendingWhitespace();
+  }
+
+  const { input, context } = await partialContext(event.data);
+  const readable = await input();
+
+  await this.#renderPartialContent(readable, context, indent);
+}
+```
+
+**`#renderPartialContent` (new private method):**
+
+```typescript
+async #renderPartialContent(
+  readable: ReadableStream,
+  context: ContextTypes | undefined,
+  indent: string
+): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const childContextProvider: ContextProvider = {
+      context: context ?? this.context,
+      getContextValue: <CTX extends ContextTypes>(tag: TagType) =>
+        this.getContextValue<CTX>(tag),
+    };
+
+    const indentingWriter: WriteToOutput = indent
+      ? makeIndentingWriter(this.#writeToOutput, indent)
+      : this.#writeToOutput;
+
+    new Template({
+      contextProvider: childContextProvider,
+      readable: readable as ReadableStream<string>,
+      writeToOutput: indentingWriter,
+    })
+      .on("inactive", () => resolve())
+      .read();
+  });
+}
+```
+
+**`#flushPendingWhitespace` (new private method):**
+
+```typescript
+async #flushPendingWhitespace(): Promise<void> {
+  if (this.#pendingWhitespace) {
+    await this.#writeToOutput(this.#pendingWhitespace);
+    this.#pendingWhitespace = "";
+  }
+}
+```
+
+**`#handleInactive` change** — flush any buffered whitespace before emitting:
+
+```typescript
+async #handleInactive(): Promise<void> {
+  await this.#flushPendingWhitespace();
+  this.emit("inactive", undefined);
+}
+```
+
+All other handlers (`#handleVariable`, `#handleImplicit`, `#handleSection`) must call `#flushPendingWhitespace()` before their own logic.
+
+**`makeIndentingWriter` (new module-level helper):**
+
+Prepends `indent` after every newline in the output stream, and before the first write (since the standalone indent was not written):
+
+```typescript
+function makeIndentingWriter(
+  writeToOutput: WriteToOutput,
+  indent: string
+): WriteToOutput {
+  let atLineStart = true;
+  return async (text: string) => {
+    const indented = (atLineStart ? indent : "") +
+      text.replace(/\n(?!$)/g, "\n" + indent);
+    atLineStart = text.endsWith("\n");
+    return writeToOutput(indented);
+  };
+}
+```
+
+---
+
+### No changes required to
+
+- `Parse` — unchanged
+- `Tokenize` — unchanged
+- `Queue` — already emits `"partial"` events
+
+---
+
+## Unit Test File
+
+```
+libs/stache-stream/src/lib/v2/template/Template-partials.spec.ts
+```
+
+---
+
+## Test Phases (TDD)
+
+| # | Template | Context | Expected output |
+|---|---|---|---|
+| 1 | `{{> p}}` | `{ p: lambda → "hello" }` | `["hello"]` |
+| 2 | `before {{> p}} after` | `{ p: lambda → "mid" }` | `["before ", "mid", " after"]` |
+| 3 | `{{> missing}}` | `{}` | `[]` |
+| 4 | `{{> p}}` | `{ p: lambda → "{{name}}", context: { name: "Alice" } }` | `["Alice"]` — partial uses lambda-provided context |
+| 5 | `{{> p}}` | `{ name: "Bob", p: lambda → "{{name}}" }` | `["Bob"]` — partial inherits parent context |
+| 6 | `{{#items}}{{> p}}{{/items}}` | `{ items: [{ name: "A" }, { name: "B" }], p: lambda → "{{name}}" }` | `["A", "B"]` |
+| 7 | `"{{> outer}}"` where outer = `"{{> inner}}"`, inner = `"hi"` | lambdas | `["hi"]` — recursive include |
+| 8 | `"  {{> p}}\n"` (standalone with 2-space indent) | `{ p: lambda → "a\nb" }` | `["  a\n  b"]` — indent applied to each line |
+| 9 | `"  {{> p}}\n"` (standalone) | `{ p: lambda → "line1\nline2\n" }` | indent on every line, trailing newline preserved |
+| 10 | `"text {{> p}}\n"` (non-standalone) | `{ p: lambda → "a\nb" }` | `["text ", "a\nb"]` — no indent applied |
+| 11 | `{{#s}}{{> p}}{{/s}}` | `{ name: "root", s: { }, p: lambda → "{{name}}" }` | `["root"]` — partial inside section falls back through section context to root context |

package/src/lib/plan_sections.md

@@ -0,0 +1,167 @@
+# Plan: Section Tags (`{{#s}}…{{/s}}`)
+
+## Objective
+
+Implement rendering of `{{#section}}…{{/section}}` blocks in the v2 streaming template engine per the [Mustache spec](https://mustache.github.io/mustache.5.html#Sections). Scope is limited to the `section` tag type; `{{^inverted}}` blocks are out of scope.
+
+---
+
+## Background
+
+The `Queue` already accumulates all tokens between a section open-tag and its matching close-tag into a `TokenizeAllEvent[]` and fires a `"section"` event. `Template.#handleSection` is a no-op. This plan implements that handler.
+
+### What the pipeline already handles
+
+| Component | Status | Notes |
+| --- | --- | --- |
+| `Tag` | No change | `{{#key}}` → `type: "section"`, `{{/key}}` → `type: "end"` |
+| `Tokenize` | No change | Emits tokens correctly |
+| `Queue` | No change | Accumulates full section block; emits `"section"` with `TokenizeAllEvent[]` |
+| `Template` | **Change required** | `#handleSection` is a no-op |
+
+---
+
+## Mustache Spec Summary
+
+Per the spec, a section renders its block zero or more times depending on the context value at its key:
+
+| Context value | Behavior |
+| --- | --- |
+| `false`, empty string `""`, empty list `[]` | Block not rendered |
+| `undefined` / key not in context | Block not rendered |
+| Non-empty list | Block rendered once per item; each item becomes the context |
+| Lambda `(content: string) => string` | Called with raw (unrendered) section content; result written to output |
+| Any other truthy value (object, `true`, number) | Block rendered once; value pushed onto context stack |
+
+---
+
+## Implementation
+
+### `template/Template.ts` — implement `#handleSection`
+
+#### Key design decisions
+
+1. **Template string reconstruction**: Inner tokens (between open and close tags) are converted back to a template string via `tokenEventToString`. Text tokens use `event.data`; tag tokens use `event.data.toString()` (which returns the original `{{…}}` form).
+
+2. **Child `Template` per render**: Each section render creates a child `Template` with a `ReadableStream<string>` built from the reconstructed template string and a `contextProvider` that:
+   - sets `context` to the item being rendered
+   - sets `getContextValue` to the parent template's `getContextValue`, enabling the Mustache context-stack fall-through behavior
+
+3. **Lambda**: Detected via `isSectionLambda` type guard (`typeof === "function" && length === 1`). Called synchronously with the raw template string; result written directly to output.
+
+4. **Falsy guard**: `undefined`, `false`, `""`, and `[]` (empty array) all suppress rendering. All other values render at least once.
+
+#### New module-level helpers
+
+```typescript
+function stringToReadableStream(str: string): ReadableStream<string> {
+  return new ReadableStream<string>({
+    start(controller) {
+      controller.enqueue(str);
+      controller.close();
+    },
+  });
+}
+
+function isSectionLambda(
+  value: ContextTypes
+): value is SectionTagContextSpecFunction {
+  return typeof value === "function";
+}
+```
+
+#### `#handleSection` implementation
+
+```typescript
+async #handleSection(events: TokenizeAllEvent[]): Promise<void> {
+  const startEvent = events[0];
+  if (!startEvent || startEvent.type !== "tag") {
+    return;
+  }
+
+  const sectionContext = await this.getContextValue(startEvent.data);
+
+  if (
+    sectionContext === undefined ||
+    sectionContext === false ||
+    sectionContext === "" ||
+    (Array.isArray(sectionContext) && sectionContext.length === 0)
+  ) {
+    return;
+  }
+
+  const innerEvents = events.slice(1, -1);
+  const templateStr = innerEvents.map((e) => e.data.toString()).join("");
+
+  if (isSectionLambda(sectionContext)) {
+    await this.#writeToOutput(sectionContext(templateStr));
+    return;
+  }
+
+  const items: ContextTypes[] = Array.isArray(sectionContext)
+    ? sectionContext
+    : [sectionContext];
+
+  for (const item of items) {
+    await this.#renderSectionContent(templateStr, item);
+  }
+}
+```
+
+#### `#renderSectionContent` implementation
+
+```typescript
+async #renderSectionContent(
+  templateStr: string,
+  context: ContextTypes
+): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const childContextProvider: ContextProvider = {
+      context,
+      getContextValue: <CTX extends ContextTypes>(
+        tag: TagType
+      ): Promise<CTX | undefined> => this.getContextValue<CTX>(tag),
+    };
+
+    new Template({
+      contextProvider: childContextProvider,
+      readable: stringToReadableStream(templateStr),
+      writeToOutput: this.#writeToOutput,
+    })
+      .on("inactive", () => resolve())
+      .read();
+  });
+}
+```
+
+#### Import additions
+
+Add `SectionTagContextSpecFunction` to the import from `"../../types"`.
+
+---
+
+## Tests (TDD — phases in complexity order)
+
+All tests go in a `describe("sections", …)` block in `template/Template.spec.ts` with a shared `render` helper.
+
+| # | Template | Context | Expected output |
+| --- | --- | --- | --- |
+| 1 | `{{#s}}text{{/s}}` | `{ s: true }` | `["text"]` |
+| 2 | `{{#s}}text{{/s}}` | `{ s: false }` | `[]` |
+| 3 | `{{#s}}text{{/s}}` | `{ s: [] }` | `[]` |
+| 4 | `{{#s}}{{name}}{{/s}}` | `{ s: { name: "Alice" } }` | `["Alice"]` |
+| 5 | `{{#s}}{{name}}{{/s}}` | `{ s: [{ name: "Alice" }, { name: "Bob" }] }` | `["Alice", "Bob"]` |
+| 6 | `{{#s}}{{.}}{{/s}}` | `{ s: ["a", "b"] }` | `["a", "b"]` |
+| 7 | `{{#s}}text{{/s}}` | `{ s: (c) => \`<em>${c}</em>\` }` | `["<em>text</em>"]` |
+| 8 | `{{#outer}}{{#inner}}text{{/inner}}{{/outer}}` | `{ outer: { inner: true } }` | `["text"]` |
+| 9 | `{{#s}}{{name}}{{/s}}` | `{ s: true, name: "Alice" }` | `["Alice"]` |
+| 10 | `a {{#outer}} L {{#inner}}text{{/inner}} N {{/outer}} z` | `{ outer: { inner: true } }` | `["a ", " L ", "text", " N ", " z"]` |
+
+---
+
+## Files Changed
+
+| File | Change |
+| --- | --- |
+| `template/Template.ts` | Implement `#handleSection` and `#renderSectionContent`; add `stringToReadableStream`, `isSectionLambda` helpers; import `SectionTagContextSpecFunction` |
+| `template/Template.spec.ts` | Add `"sections"` describe block with 9 test cases |

package/src/lib/plan_stache-stream.md

@@ -0,0 +1,110 @@
+# Plan: Update StacheTransformStream to Use v2 Components
+
+## Goal
+
+Replace `StacheTransformStream`'s dependency on the v1 `Template` (character-push model) with the v2 `Template`
+(streaming `ReadableStream<string>` model). All Mustache tag types currently supported by v2 must be covered by
+tests on `StacheTransformStream`.
+
+---
+
+## Background
+
+`StacheTransformStream` is a `TransformStream<string, string>`. Its current `#transform(chunk, controller)` method
+feeds chunks one at a time into the v1 `Template.push(chunk)`. The v1 `Template` is a character-level state machine.
+
+The v2 `Template` has a different contract:
+
+- **Constructor** receives a `ReadableStream<string>`, a `writeToOutput` sink, and an optional `contextProvider`.
+- **`read()`** starts the internal `Parse → Tokenize → Queue` pipeline.
+- **`"inactive"` event** is emitted when all output has been written.
+
+Bridging `TransformStream` callbacks to `ReadableStream` requires a "pushable" `ReadableStream` — a stream whose
+controller is captured at construction time so external code can enqueue chunks and close it on demand.
+
+---
+
+## Tag Types Supported by v2 (Scope)
+
+| Tag syntax               | Type               | Status in v2 |
+| ------------------------ | ------------------ | ------------ |
+| plain text               | —                  | implemented  |
+| `{{key}}`                | variable (escaped) | implemented  |
+| `{{{key}}}` / `{{&key}}` | variable (raw)     | implemented  |
+| `{{.}}`                  | implicit iterator  | implemented  |
+| `{{>name}}`              | partial            | implemented  |
+| `{{#key}}…{{/key}}`      | section            | implemented  |
+
+---
+
+## Changes
+
+### 1. `StacheStream.ts`
+
+Replace the class body. The new implementation:
+
+1. Creates a pushable `ReadableStream<string>` whose controller is captured synchronously in its `start` callback.
+2. Instantiates the v2 `Template` with that `ReadableStream`, a `writeToOutput` that calls
+   `controller.enqueue(text)`, and the caller-supplied `contextProvider`.
+3. Calls `template.read()` to start the pipeline.
+4. In `transform(chunk)`: enqueues `chunk` into the pushable stream.
+5. In `flush()`: closes the pushable stream and returns a `Promise` that resolves when the `"inactive"` event fires.
+
+A private helper `createPushableStream<T>()` is introduced to keep the constructor body readable. It returns
+`{ readable, push, close }` using the `ReadableStream` `start` callback to capture the controller (no `as` cast
+needed; definite-assignment assertions via `!` are acceptable since `start` is called synchronously).
+
+The v1 `#template`, `#contextProvider`, `#getTemplate`, and `#transform` private members are removed entirely.
+
+### 2. `StacheStream.spec.ts`
+
+The existing two tests are replaced. With v2, text is grouped into segments rather than emitted character by
+character, so the expected `chunks` arrays change. New tests cover all six tag types in scope:
+
+| Test                        | Template                       | Context                             | Expected output          |
+| --------------------------- | ------------------------------ | ----------------------------------- | ------------------------ |
+| plain text                  | `"fubar"`                      | —                                   | `["fubar"]`              |
+| variable (escaped)          | `"Hi {{name}}!"`               | `{name: "Alice"}`                   | `["Hi ", "Alice", "!"]`  |
+| variable (raw triple-brace) | `"{{{html}}}"`                 | `{html: "<b>ok</b>"}`               | `["<b>ok</b>"]`          |
+| variable (raw ampersand)    | `"{{&html}}"`                  | `{html: "<b>ok</b>"}`               | `["<b>ok</b>"]`          |
+| variable HTML-escapes       | `"{{val}}"`                    | `{val: "a&b"}`                      | `["a&amp;b"]`            |
+| implicit iterator           | `"{{.}}"`                      | `"hello"`                           | `["hello"]`              |
+| partial                     | `"{{>name}}"`                  | lambda returning template + context | partial content rendered |
+| section — truthy            | `"{{#show}}yes{{/show}}"`      | `{show: true}`                      | `["yes"]`                |
+| section — falsy             | `"{{#show}}yes{{/show}}"`      | `{show: false}`                     | `[]`                     |
+| section — list              | `"{{#items}}{{.}} {{/items}}"` | `{items: ["a","b"]}`                | `["a ", "b "]`           |
+
+Tests use the existing `createReadableStream` helper (from `./test/streams`) piped through `TextDecoderStream`
+before `StacheTransformStream`, matching current caller convention.
+
+### 3. No other files change
+
+The v2 `Template`, `Parse`, `Tokenize`, `Queue`, and `Tag` files are not modified. The v1 `Template` and its spec
+remain in place (they are not removed by this plan).
+
+---
+
+## Decisions
+
+1. **Output chunk granularity** — segment-level chunks are acceptable; character-by-character output is not required.
+
+2. **Inverted sections and comment tags** — both have been removed from scope; no tests for these in `StacheStream.spec.ts`.
+
+3. **Type parameter order** — Node.js defines `TransformStream<I, O>` where `I` is the input (writable side) and
+   `O` is the output (readable side):
+   ```typescript
+   interface TransformStream<I = any, O = any> {
+     readonly readable: ReadableStream<O>;
+     readonly writable: WritableStream<I>;
+   }
+   ```
+   The current class declaration `TransformStream<O, I>` has the names reversed from this convention. The class
+   will be updated to use `TransformStream<I, O>` with conventional naming.
+
+4. **Error propagation** — Node.js convention is to call `controller.error(reason)` on the
+   `TransformStreamDefaultController` to signal errors to stream consumers. The updated `StacheStream.ts` will:
+   - Wrap `writeToOutput` in a try/catch; on error call `controller.error(err)`.
+   - Use a shared `Promise` for the `flush()` return that can be either resolved (on `"inactive"`) or rejected (on
+     pipeline error); on rejection also call `controller.error(err)`.
+   - The `flush()` callback returns this promise, so any pipeline error will cancel the writable side and surface
+     to the caller.

package/src/lib/plan_whitespace.md

@@ -0,0 +1,98 @@
+# Plan: Standalone Whitespace Suppression for Section and Inverted Section Tags
+
+## Spec Requirements
+
+Per https://mustache.github.io/mustache.5.html#Sections and the standalone-tag rules in
+https://github.com/mustache/spec/blob/master/specs/sections.yml:
+
+- A section or inverted-section tag is **standalone** when it is the only non-whitespace content
+  on its line — no non-whitespace text precedes it on the current line, and the character
+  immediately following the tag is a newline (or end of input).
+- For a standalone opening tag (`{{#s}}` / `{{^s}}`): suppress the leading whitespace on the tag's
+  line and consume the newline that follows the tag (i.e., that newline is not part of the body).
+- For a standalone closing tag (`{{/s}}`): consume the newline that follows it in the parent output
+  stream.
+
+---
+
+## Decisions
+
+1. **Tests go in existing spec files.** Standalone-suppression tests for `{{#s}}` go in
+   `Template-section.spec.ts`; tests for `{{^s}}` go in `Template-inverted-section.spec.ts`.
+
+2. **Closing-tag body whitespace is out of scope.** Stripping horizontal whitespace that precedes
+   `{{/s}}` from the body string (e.g., the `  ` in `"{{#s}}\nbody\n  {{/s}}\n"`) is deferred to
+   a future iteration.
+
+3. **Comment tags are not transparent for standalone detection.** The opening tag is standalone
+   only when its first body event is a `TextEvent` starting with `\n` or `\r\n`. If the first body
+   event is a tag (including a comment), the opening tag is treated as non-standalone. This is the
+   simpler of the two alternatives; skipping comment events to find the first "real" body event
+   adds complexity with no practical benefit given realistic template usage.
+
+4. **`\r\n` is handled wherever `\n` is.** Consistent with the existing `#handleText`
+   implementation.
+
+---
+
+## Component Changes
+
+### `Template.ts`
+
+Replace the unconditional `await this.#flushPendingWhitespace()` at the top of `#handleSection`
+and `#handleInverted` with standalone detection:
+
+```typescript
+const bodyEvents = events.slice(1, -1);
+const firstBodyEvent = bodyEvents[0];
+const isOpeningStandalone =
+  !this.#lineHasContent &&
+  firstBodyEvent !== undefined &&
+  firstBodyEvent.type === "text" &&
+  /^(\r\n|\n)/.test(firstBodyEvent.data.toString());
+```
+
+If `isOpeningStandalone`:
+
+- Clear `#pendingWhitespace` (suppress leading whitespace on the tag's line).
+- Set `#consumeNextNewline = true` (consume newline after the closing tag in the parent stream).
+- Strip the leading `\n` or `\r\n` from `templateStr` (consume newline after the opening tag).
+
+If NOT standalone, call `#flushPendingWhitespace()` (preserve current behavior).
+
+### `Template-comment.spec.ts`
+
+Update the expected value of `"suppresses a standalone comment line inside a section body"`:
+
+```diff
+-    ).toBe("\n");
++    ).toBe("");
+```
+
+The leading `\n` currently in the output comes from `{{#s}}\n` not being suppressed. After the
+fix, standalone detection eliminates it.
+
+---
+
+## Test Files
+
+`libs/stache-stream/src/lib/template/Template-section.spec.ts` — section tests (#1–#8, #11–#12)
+
+`libs/stache-stream/src/lib/template/Template-inverted-section.spec.ts` — inverted tests (#9–#10)
+
+### Planned tests
+
+| # | Template | Context | Expected output |
+| --- | --- | --- | --- |
+| 1 | `"{{#s}}\nbody\n{{/s}}\n"` | `{ s: true }` | `"body\n"` — standalone opening and closing tags suppressed |
+| 2 | `"{{#s}}\nbody\n{{/s}}\n"` | `{ s: false }` | `""` — falsy context, nothing rendered |
+| 3 | `"before\n{{#s}}\nbody\n{{/s}}\nafter"` | `{ s: true }` | `"before\nbody\nafter"` — standalone section in middle of content |
+| 4 | `"before\n{{#s}}\nbody\n{{/s}}\nafter"` | `{ s: false }` | `"before\nafter"` — standalone section lines suppressed, body not rendered |
+| 5 | `"  {{#s}}\nbody\n{{/s}}\nafter"` | `{ s: true }` | `"body\nafter"` — leading whitespace on tag line suppressed |
+| 6 | `"  {{#s}}\nbody\n{{/s}}\nafter"` | `{ s: false }` | `"after"` — standalone tag lines suppressed, body not rendered |
+| 7 | `"  {{#s}}text{{/s}}\n"` | `{ s: true }` | `"  text\n"` — not standalone: pending whitespace flushed |
+| 8 | `"a {{#s}}body{{/s}}\nz"` | `{ s: true }` | `"a body\nz"` — not standalone: content precedes opening tag |
+| 9 | `"{{^s}}\nbody\n{{/s}}\n"` | `{ s: false }` | `"body\n"` — standalone inverted section |
+| 10 | `"before\n{{^s}}\nbody\n{{/s}}\nafter"` | `{ s: false }` | `"before\nbody\nafter"` — standalone inverted section in middle of content |
+| 11 | `"{{#a}}\n{{#b}}\nbody\n{{/b}}\n{{/a}}\n"` | `{ a: true, b: true }` | `"body\n"` — nested standalone sections |
+| 12 | `"{{#s}}\n{{! comment }}\n{{/s}}"` | `{ s: true }` | `""` — standalone section with standalone comment body |