@funcstache/stache-stream 0.2.2 → 0.2.3

package/src/lib/parse/Parse.ts

@@ -0,0 +1,92 @@
+import { ReadableStream } from "node:stream/web";
+import { EventEmitter } from "node:events";
+
+type ParseEventMap = { inactive: [Parse] };
+
+export interface ParseOptions {
+  onChar: (char: string | null) => Promise<void>;
+}
+
+export class Parse extends EventEmitter<ParseEventMap> {
+  #onChar: ParseOptions["onChar"];
+  #processPending = false;
+  #queue: string[] = [];
+  #readState: "finished" | "pending" | "reading" = "pending";
+
+  constructor(
+    options: ConstructorParameters<typeof EventEmitter<ParseEventMap>>[0] &
+      ParseOptions
+  ) {
+    super(options);
+    this.#onChar = options.onChar;
+  }
+
+  async read(readable: ReadableStream<string>) {
+    this.#readState = "reading";
+
+    for await (const chunk of readable) {
+      if (!chunk) {
+        break;
+      }
+
+      if (1 < chunk.length) {
+        for (const char of chunk) {
+          this.#push(char);
+        }
+      } else {
+        this.#push(chunk);
+      }
+    }
+
+    this.#readState = "finished";
+    this.#finalize();
+  }
+
+  #invokeChar(char: string | null) {
+    try {
+      this.#onChar(char);
+    } catch (err) {
+      console.error(err);
+    }
+  }
+
+  #process() {
+    this.#processPending = false;
+
+    while (this.#queue.length) {
+      const char = this.#queue.shift();
+      if (!char) {
+        continue;
+      }
+
+      this.#invokeChar(char);
+    }
+
+    this.#finalize();
+  }
+
+  #push(char: string) {
+    this.#queue.push(char);
+
+    if (this.#processPending) {
+      return;
+    }
+
+    this.#processPending = true;
+
+    setTimeout(() => this.#process(), 0);
+  }
+
+  #finalize() {
+    if (this.#readState !== "finished") {
+      return;
+    }
+
+    if (this.#queue.length) {
+      return;
+    }
+
+    this.#invokeChar(null);
+    this.emit("inactive", this);
+  }
+}

package/src/lib/parse/README.md

@@ -0,0 +1,62 @@
+# Parse
+
+`Parse` reads a `ReadableStream<string>` character-by-character and calls a user-supplied `onChar` callback for each character. When the stream is exhausted, `onChar` is called once more with `null` to signal end-of-input, and the `inactive` event is emitted.
+
+## How it works
+
+### Reading
+
+`read(readable)` iterates over the stream asynchronously. Each chunk is either pushed directly (single character) or split into individual characters before pushing. This ensures `onChar` is always called with exactly one character at a time regardless of chunk size.
+
+### Queuing and processing
+
+Characters are not dispatched immediately. `#push` adds each character to an internal queue and, if no processing tick is already scheduled, sets a `setTimeout(..., 0)` to drain the queue on the next event loop turn. This batches any characters that arrive in the same microtask tick into a single `#process` call, keeping `onChar` invocations orderly without blocking the stream reader.
+
+### Finalization
+
+`#finalize` is called after each `#process` drain and at the end of `read`. It only proceeds when both conditions are true:
+
+1. The stream has been fully read (`readState === "finished"`)
+2. The queue is empty
+
+When both are true, `onChar(null)` is called and the `inactive` event is emitted. Callers wait for this event to know that all characters have been processed.
+
+## Usage
+
+```ts
+import { Parse } from "./Parse";
+
+const parse = new Parse({
+  onChar: async (char) => {
+    if (char === null) return; // end of stream
+    process.stdout.write(char);
+  },
+});
+
+parse.on("inactive", () => console.log("done"));
+parse.read(myReadableStream);
+```
+
+## API
+
+### `new Parse(options)`
+
+| Option   | Type                                      | Description                                                     |
+| -------- | ----------------------------------------- | --------------------------------------------------------------- |
+| `onChar` | `(char: string \| null) => Promise<void>` | Called for each character. Called with `null` at end of stream. |
+
+Also accepts all `EventEmitter` constructor options.
+
+### `parse.on(eventName, listener)`
+
+Inherited from `EventEmitter`. Registers a listener for a parse event.
+
+### `parse.read(readable: ReadableStream<string>): Promise<void>`
+
+Starts reading from the stream. Resolves when the stream ends (but before `onChar(null)` is called — listen for `inactive` to know processing is complete).
+
+### Events
+
+| Event      | Payload | Description                                                                                                          |
+| ---------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
+| `inactive` | `Parse` | Emitted after `onChar(null)` has been called and the queue is empty. The `Parse` instance is passed as the argument. |

package/src/lib/plan_base_v2.md

@@ -0,0 +1,33 @@
+PLAN_FILENAME = "plan_comment.md"
+TOKEN_TYPE = "comment"
+TOKEN_TYPE_EXAMPLE = `{{! comment }}`
+
+The stache-stream components (libs/stache-stream/src/lib/) must handle {{TOKEN_TYPE}} tokens, e.g. {{TOKEN_TYPE_EXAMPLE}}. See: https://mustache.github.io/mustache.5.html#Comments. Create an implementation plan.
+
+## Tasks
+
+Do the following tasks in order:
+
+1. Create a new markdown file named {{PLAN_FILENAME}} to contain the plan.
+2. Create the specification in the file.
+   - must be implemented according to the Mustache specification
+   - include changes to the components in v2 and any other components
+   - include unit tests
+   - create a list of questions that need answers to resolve ambiguities, conflicts, or missing requirements
+3. STOP and get approval for all questions to be answered before proceeding.
+4. Tests for the `Template` class should be placed into a test file named "Template-{{TOKEN_TYPE}}.spec.ts".
+5. Suggest a phased implementations that uses a TDD approach:
+   1. define the text of a mustache template and context type that is expected to be supported, start with the least complex implementation that is in scope
+   2. create one or more tests using template and context defined in step 1
+   3. verify the test fails — confirm the test is failing by running it before proceeding
+   4. implement the changes in code
+   5. rerun the test; if the test fails iterate on fixing the code until the test passes
+   6. once the test passes start over at step 1 with the next more complex template, continue until all templates within scope are complete, if there are more than 15 tests stop and get approval for the tests
+
+## Out-of-scope
+
+- Any Mustache Template specifications that are not {{TOKEN_TYPE}} tags types.
+
+## Resources
+
+[README](../../README.md)

package/src/lib/plan_comment.md

@@ -0,0 +1,53 @@
+# Plan: Comment Token Implementation
+
+## Spec Requirements
+
+Per https://mustache.github.io/mustache.5.html#Comments:
+
+- `{{! comment text }}` — everything inside is ignored; produces no output.
+- Comment text may contain newlines.
+- **Standalone** (per https://github.com/mustache/spec/blob/master/specs/comments.yml): when a comment tag is the only non-whitespace content on a line, the entire line is suppressed — leading whitespace and trailing newline are not written to output.
+- **Non-standalone**: only the tag itself is removed; surrounding text on the same line is preserved.
+
+## Decisions
+
+1. **Multi-line comments are treated atomically.** Standalone detection is based only on what precedes `{{` on the current line. Newlines inside `{{! ... }}` do not affect `#lineHasContent` or `#pendingWhitespace`. This is naturally correct since `Tokenize` emits the entire comment as a single tag token.
+
+2. **Comments must be accumulated when inside a section body.** Dropping comment tokens from the accumulator would leave surrounding text tokens (`\n` before and after a standalone comment) intact, producing incorrect output. The child `Template` must receive the comment token in its reconstructed template string to apply standalone suppression. Comments are emitted immediately (not accumulated) only when `Queue` is not currently inside an accumulator.
+
+## Component Changes
+
+### `Queue.ts`
+
+1. Add `comment: TokenizeTagEvent` to `QueueEventMap`.
+2. Add a `case "comment":` branch in the `#processToken` switch that mirrors the `implicit`/`partial`/`variable` branch: push to `#accumulator` when inside a section, otherwise emit the `"comment"` event.
+
+### `Template.ts`
+
+1. In the `#queue` getter, register `.on("comment", this.#handleComment.bind(this))`.
+2. Add a `#handleComment` private method:
+   - **Standalone** (`!this.#lineHasContent`): set `#pendingWhitespace` to `""`, set `#consumeNextNewline = true`. Write nothing.
+   - **Non-standalone**: call `#flushPendingWhitespace()`. Write nothing.
+
+No changes are required to `Tag.ts` (type `comment` is already assigned for the `!` sigil) or `Tokenize.ts`.
+
+## Test File
+
+`libs/stache-stream/src/lib/template/Template-comment.spec.ts`
+
+Follow the `render` helper pattern from `Template-partials.spec.ts`. Section tests require context `{ s: true }`.
+
+### Planned tests
+
+| #   | Template                         | Context       | Expected output                                                   |
+| --- | -------------------------------- | ------------- | ----------------------------------------------------------------- |
+| 1   | `{{! comment }}`                 | —             | `""` — basic comment produces no output                           |
+| 2   | `before{{! comment }}after`      | —             | `"beforeafter"` — non-standalone comment stripped inline          |
+| 3   | `{{! multi\nline }}`             | —             | `""` — multi-line comment treated atomically                      |
+| 4   | `{{! comment }}\n`               | —             | `""` — standalone: tag line fully suppressed                      |
+| 5   | `  {{! comment }}\n`             | —             | `""` — standalone with leading whitespace suppressed              |
+| 6   | `before\n{{! comment }}\nafter`  | —             | `"before\nafter"` — standalone in middle of content               |
+| 7   | `text {{! comment }}\n`          | —             | `"text \n"` — non-standalone: leading text preserved, tag removed |
+| 8   | `{{#s}}{{! comment }}{{/s}}`     | `{ s: true }` | `""` — comment inside section body                                |
+| 9   | `{{#s}}\n{{! comment }}\n{{/s}}` | `{ s: true }` | `""` — standalone comment inside section body                     |
+| 10  | `{{!\n  I'm a comment\n}}`       | —             | `""` — comment with newlines spanning multiple source lines       |

package/src/lib/plan_implicit-iterator.md

@@ -0,0 +1,213 @@
+# Plan: Implicit Iterator (`{{.}}`)
+
+## Objective
+
+Implement rendering of `{{.}}` (the Mustache implicit iterator) in the v2 streaming template engine. Scope is limited to a `string` or `number` context value. `{{.}}` outputs the current context value directly; HTML escaping follows the same rules as `{{variable}}` (escaped by default).
+
+---
+
+## Background
+
+Per the [Mustache spec](https://mustache.github.io/mustache.5.html#Variables), `{{.}}` means _"the value currently sitting atop the context stack"_. When the context is a primitive string or number, `{{.}}` renders it directly.
+
+### What the pipeline already handles
+
+| Component  | Status              | Notes                                                                         |
+| ---------- | ------------------- | ----------------------------------------------------------------------------- |
+| `Tag`      | **Change required** | `{{{.}}}` and `{{&.}}` incorrectly classified as `type: "variable"`           |
+| `Tokenize` | No change           | Emits `TokenizeTagEvent` with the type set by `Tag`                           |
+| `Queue`    | No change           | Routes `"implicit"` events to registered listeners                            |
+| `Template` | **Change required** | `#handleImplicit` is a no-op                                                  |
+
+---
+
+## Implementation
+
+### `Tag/Tag.ts` — fix `#extractValueInformation`
+
+Two code paths misclassify implicit raw tags as `"variable"`:
+
+**1. `{{{.}}}` (triple-brace):** The `rawBraces` guard returns early before the value is inspected.
+
+```typescript
+// before
+if (this.#rawBraces) {
+  this.#type = "variable";
+  this.#raw = true;
+  return;
+}
+
+// after
+if (this.#rawBraces) {
+  this.#raw = true;
+  this.#type = this.value === "." ? "implicit" : "variable";
+  return;
+}
+```
+
+**2. `{{&.}}` (ampersand):** The `&` case sets `raw = true` but leaves `tagType` as `"variable"`. Add an override when the remaining value is `.`:
+
+```typescript
+case "&": {
+  raw = true;
+  if (normalizedTagValue.slice(1) === ".") {
+    tagType = "implicit";
+  }
+  break;
+}
+```
+
+After both fixes, all three forms — `{{.}}`, `{{{.}}}`, `{{&.}}` — produce `type: "implicit"`. The `raw` flag distinguishes whether output should be HTML-escaped.
+
+---
+
+### `template/Template.ts` — implement `#handleImplicit`
+
+Replace the no-op with logic that reads the current context and writes to output.
+
+```typescript
+async #handleImplicit({ data: tag }: TokenizeTagEvent): Promise<void> {
+  const ctx = this.context;
+
+  if (isPrimitive(ctx)) {
+    this.#writeToOutput(
+      tag.raw ? "" + ctx : escape("" + ctx)
+    );
+  }
+}
+```
+
+- `this.context` returns `this.#contextProvider?.context || {}`.
+- `isPrimitive` is already defined in the file — covers `string`, `number`, `boolean`.
+- `tag.raw` is `false` for `{{.}}`, `true` for `{{{.}}}` and `{{&.}}`.
+- Non-primitive context (object, array) silently skips output, consistent with `#handleVariable`.
+
+---
+
+## Tests
+
+### `Tag/Tag.spec.ts` — add cases for raw implicit tags
+
+```typescript
+describe("implicit iterator", () => {
+  it("triple-brace {{{.}}} produces type implicit with raw true", () => {
+    const tag = Tag.parse("{{{.}}}");
+    expect(tag?.type).toBe("implicit");
+    expect(tag?.raw).toBe(true);
+    expect(tag?.key).toBe(".");
+  });
+
+  it("ampersand {{&.}} produces type implicit with raw true", () => {
+    const tag = Tag.parse("{{&.}}");
+    expect(tag?.type).toBe("implicit");
+    expect(tag?.raw).toBe(true);
+    expect(tag?.key).toBe(".");
+  });
+});
+```
+
+### `template/Template.spec.ts` — add to the `"Template"` describe block
+
+```typescript
+describe("implicit iterator", () => {
+  async function render(template: string, context: string | number): Promise<string[]> {
+    return new Promise<string[]>((resolve) => {
+      const calls: string[] = [];
+      new Template({
+        contextProvider: { context },
+        readable: createReadableStream(template).pipeThrough(new TextDecoderStream()),
+        writeToOutput: async (text) => { calls.push(text); },
+      })
+        .on("inactive", () => resolve(calls))
+        .read();
+    });
+  }
+
+  it("renders a string context", async () => {
+    expect(await render("{{.}}", "hello")).toEqual(["hello"]);
+  });
+
+  it("renders a number context", async () => {
+    expect(await render("{{.}}", 42)).toEqual(["42"]);
+  });
+
+  it("HTML-escapes the context value", async () => {
+    expect(await render("{{.}}", '& " < >')).toEqual(["&amp; &quot; &lt; &gt;"]);
+  });
+
+  it("renders surrounding text alongside the implicit value", async () => {
+    expect(await render("Hello, {{.}}!", "world")).toEqual(["Hello, ", "world", "!"]);
+  });
+
+  it("produces no output when context is an object", async () => {
+    expect(await render("{{.}}", { name: "rich" } as any)).toEqual([]);
+  });
+
+  it("triple-brace {{{.}}} outputs without HTML escaping", async () => {
+    expect(await render('{{{.}}}', '& " < >')).toEqual(['& " < >']);
+  });
+
+  it("ampersand {{&.}} outputs without HTML escaping", async () => {
+    expect(await render('{{&.}}', '& " < >')).toEqual(['& " < >']);
+  });
+});
+```
+
+---
+
+## Files Changed
+
+| File | Change |
+| --- | --- |
+| `Tag/Tag.ts` | Fix `#extractValueInformation` — `{{{.}}}` and `{{&.}}` → `type: "implicit"` |
+| `Tag/Tag.spec.ts` | Add `"implicit iterator"` cases for triple-brace and ampersand forms |
+| `template/Template.ts` | Replace no-op `#handleImplicit` with primitive-context rendering logic |
+| `template/Template.spec.ts` | Add `"implicit iterator"` describe block with 7 test cases |
+
+---
+
+## Open Questions
+
+These questions should be answered before extending the implementation beyond the current scope.
+
+1. **`{{{.}}}` and `{{&.}}` (raw implicit iterator):** Both produce a `"variable"` event with `tag.key === "."` and `tag.raw === true`. `#handleVariable` calls `getContextValue` which will return `undefined` for a primitive context (because `isContext()` returns `false` for primitives and `getContextValue` skips the lookup). Should `#handleVariable` detect `tag.key === "."` and fall back to `this.context`, or should `Tag` be changed so that `{{{.}}}` produces an `"implicit"` event with `raw: true`?
+
+- **Spec finding:** The Mustache interpolation spec explicitly defines both forms as valid:
+  - `{{{.}}}` — "Triple mustaches should interpolate without HTML escaping."
+  - `{{&.}}` — "Ampersand should interpolate without HTML escaping."
+    Both must be supported.
+- **Root cause:** `Tag.#extractValueInformation` returns early when `rawBraces === true`, setting `type: "variable"` before checking whether the value is `"."`. As a result `{{{.}}}` never reaches the `"implicit"` branch.
+- **Recommended fix:** Add a check to `#handleVariable` — if `tag.key === "."`, delegate to the same primitive-context logic used in `#handleImplicit` (respecting `tag.raw` for escaping). This avoids touching `Tag`, which is shared across v1 and v2, and keeps the implicit iterator logic contained within `Template`.
+- **Files changed:** add `template/Template.ts` (`#handleVariable` guard for `tag.key === "."`) and corresponding tests to the `"implicit iterator"` describe block covering `{{{.}}}` and `{{&.}}` with `& " < >` as context.
+
+- It's OK to break v1. Propose an update to `Tag.#extractValueInformation` to properly handle a "raw" iterator tag.
+
+2. **Implicit iterator inside sections:** When `{{#list}}{{.}}{{/list}}` is processed, `{{.}}` appears inside a section block. The section handler (not yet implemented) will need to pass each list item as the context for a child `Template`. Should the child `Template` receive the list item as its `contextProvider.context`? If so, what interface should that context provider take — the same `ContextProvider` interface with a primitive `context` value?
+
+- **Spec finding:** The Mustache sections spec defines list items as any of: `string`, `integer`, `decimal`, nested `array`, or `object`. Examples:
+  - strings: `['a', 'b', 'c']` → child context is a primitive string
+  - integers/decimals: `[1, 2, 3.3]` → child context is a primitive number
+  - arrays: `[[1, 2, 3], ['a', 'b', 'c']]` → child context is an array (for nested iteration via `{{#.}}{{.}}{{/.}}`)
+  - objects: `[{ value: 'a' }]` → child context is an object (for key lookup)
+- **`ContextProvider` compatibility:** `ContextTypes` already covers all cases in scope:
+  - Primitives (string, number, boolean) via `VariableTagContext → VariableTagContextPrimitive → JsonType`
+  - 1-D primitive arrays via `VariableTagContext → VariableTagContextPrimitive → Array<boolean | number | string>`
+  - Objects via `Context` or `SectionTagContextRecord`
+  - Nested arrays (e.g. `[[1,2,3]]`) are **not** representable by the current types — this is an out-of-scope gap to note.
+- **Answer:** No interface changes are required for the string/number scope. Each child `Template` for a list item should receive `{ context: item }` as its `contextProvider`, which is valid since `ContextTypes` includes primitives. When section rendering is implemented, the `contextProvider` passed to the child `Template` should also hold a reference to the parent `Template` as a fallback (for the context-stack miss behavior described in question 3).
+
+3. **Context stack vs. flat context:** The current `Template` has a single `contextProvider`. The Mustache spec describes a _context stack_ where inner sections push new frames. For the implicit iterator, "current context" means the top of that stack. Does the architecture need a context stack, or is it sufficient for each nested `Template` instance (created when rendering sections) to hold its own frame and delegate to its parent for misses?
+
+- Each Template receives a ContextProvider, this has the context for the current Template and the ability to call a parent ContextProvider (if any) to get context values that are not found in the current context. See `Template.getContextValue`.
+
+4. **Float formatting:** When context is a `number` with decimal places (e.g. `3.14`), `"" + 3.14` gives `"3.14"`. Is this the desired output, or should a specific number-formatting strategy be applied?
+
+- The default ECMAScript formatting of primitives shall be applied. If clients need more precise formatting it's their responsibility to supply that value in a string.
+
+5. **Boolean context:** `ContextTypes` allows `boolean` via `JsonType`. Should `{{.}}` with a boolean context render `"true"` / `"false"`, or produce no output (as with object context)?
+
+- The default ECMAScript conversion from boolean to string shall be applied.
+
+6. **Existing broken test:** `Template.spec.ts` line 51–72 (`"processes a nested, implicit, template"`) has a template `"aa{{#ee}}{{#.}}{{.}}{{/.}}{{/ee}}zz"` but asserts `"ab"`, `"HELLO WORLD"`, `"yz"` — values inconsistent with the template. This test will need to be corrected when section rendering is implemented.
+
+- agreed, skip test for now

package/src/lib/plan_inverted-sections.md

@@ -0,0 +1,160 @@
+# Plan: Inverted Section Tags (`{{^s}}…{{/s}}`)
+
+## Objective
+
+Implement rendering of `{{^key}}…{{/key}}` (inverted section) blocks in the v2 streaming template engine per the [Mustache spec](https://mustache.github.io/mustache.5.html#Inverted-Sections). Scope is limited to the `inverted` tag type.
+
+---
+
+## Background
+
+`Tag` already parses `{{^key}}` as `type: "inverted"`. `Tokenize` emits these tokens correctly. However, `Queue` only accumulates and emits blocks for `section` tags — it ignores `inverted` open tags and errors on their closing `end` tags. `Template` has no `#handleInverted` method.
+
+### What the pipeline already handles
+
+| Component  | Status              | Notes                                                             |
+| ---------- | ------------------- | ----------------------------------------------------------------- |
+| `Tag`      | No change           | `{{^key}}` → `type: "inverted"`, `{{/key}}` → `type: "end"`       |
+| `Tokenize` | No change           | Emits tokens correctly                                            |
+| `Queue`    | **Change required** | Does not accumulate `inverted` blocks; errors on their `end` tags |
+| `Template` | **Change required** | No `#handleInverted` handler                                      |
+
+---
+
+## Mustache Spec Summary
+
+| Context value                    | Behavior               |
+| -------------------------------- | ---------------------- |
+| `false`                          | Block rendered         |
+| `undefined` / key not in context | Block rendered         |
+| Empty string `""`                | Block rendered         |
+| Empty list `[]`                  | Block rendered         |
+| Any truthy value                 | Block **not** rendered |
+
+Inverted sections do not push the context, do not iterate, and do not support lambdas.
+
+---
+
+## Questions
+
+The following must be answered before proceeding to implementation.
+
+1. **Number zero**: Should `0` (falsy in JavaScript but not listed in the Mustache spec's falsy values) cause an inverted block to render? The section implementation skips rendering for `false`, `undefined`, `""`, and `[]` but does not explicitly exclude `0`. Should inverted sections treat `0` as falsy (render) for consistency?
+
+   - yes
+
+2. **Null**: Should `null` (not in the current section falsy guard) cause the inverted block to render?
+
+   - yes
+
+---
+
+## Implementation
+
+### `queue/Queue.ts`
+
+#### Changes
+
+1. Add `inverted: TokenizeAllEvent[]` to `QueueEventMap`.
+2. In `#processToken`, add `case "inverted":` alongside `case "section":` to start accumulation (same logic).
+3. In the `end` tag handler, add a branch for `start.data.type === "inverted"` that emits the `"inverted"` event (parallel to the existing `"section"` emit).
+
+The `start.data.type === "section"` check currently guards the final emit. Extend it:
+
+```typescript
+if (start.data.type === "section" || start.data.type === "inverted") {
+  await this.#emit(start.data.type, [...Array.from(this.#accumulator), token]);
+  this.#accumulator = undefined;
+} else {
+  /* existing error */
+}
+```
+
+And in the open-tag switch block:
+
+```typescript
+case "inverted":
+case "section": {
+  if (!this.#accumulator) {
+    const acc: Accumulator = [token] as any;
+    acc.level = 0;
+    this.#accumulator = acc;
+  } else {
+    this.#accumulator.level++;
+    this.#accumulator.push(token);
+  }
+  break;
+}
+```
+
+### `template/Template.ts`
+
+#### Register handler
+
+In the `#queue` getter, add:
+
+```typescript
+.on("inverted", this.#handleInverted.bind(this))
+```
+
+#### `#handleInverted` implementation
+
+```typescript
+async #handleInverted(events: TokenizeAllEvent[]): Promise<void> {
+  await this.#flushPendingWhitespace();
+  const startEvent = events[0];
+  if (!startEvent || startEvent.type !== "tag") {
+    return;
+  }
+
+  const value = await this.getContextValue(startEvent.data);
+
+  const isFalsy =
+    value === undefined ||
+    value === false ||
+    value === "" ||
+    (Array.isArray(value) && value.length === 0);
+
+  if (!isFalsy) {
+    return;
+  }
+
+  const templateStr = events
+    .slice(1, -1)
+    .map((e) => e.data.toString())
+    .join("");
+
+  await this.#renderSectionContent(templateStr, this.context);
+}
+```
+
+Note: `#renderSectionContent` is reused from the sections implementation. The context passed is `this.context` (no context push — inverted sections do not change the context stack).
+
+---
+
+## Tests (TDD — phases in complexity order)
+
+All tests go in `template/Template-inverted-section.spec.ts` with the same `render` helper pattern used in `Template-section.spec.ts`.
+
+| #   | Template                     | Context                       | Expected output |
+| --- | ---------------------------- | ----------------------------- | --------------- |
+| 1   | `{{^s}}text{{/s}}`           | `{ s: false }`                | `["text"]`      |
+| 2   | `{{^s}}text{{/s}}`           | `{ s: true }`                 | `[]`            |
+| 3   | `{{^s}}text{{/s}}`           | `{}` (key absent)             | `["text"]`      |
+| 4   | `{{^s}}text{{/s}}`           | `{ s: [] }`                   | `["text"]`      |
+| 5   | `{{^s}}text{{/s}}`           | `{ s: "" }`                   | `["text"]`      |
+| 6   | `{{^s}}text{{/s}}`           | `{ s: [1, 2] }`               | `[]`            |
+| 7   | `{{^s}}text{{/s}}`           | `{ s: {} }`                   | `[]`            |
+| 8   | `{{^s}}{{name}}{{/s}}`       | `{ s: false, name: "Alice" }` | `["Alice"]`     |
+| 9   | `{{#a}}X{{/a}}{{^a}}Y{{/a}}` | `{ a: true }`                 | `["X"]`         |
+| 10  | `{{#a}}X{{/a}}{{^a}}Y{{/a}}` | `{ a: false }`                | `["Y"]`         |
+
+---
+
+## Files Changed
+
+| File                                         | Change                                                                                                         |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `queue/Queue.ts`                             | Handle `inverted` open tag (accumulation); emit `"inverted"` event on close; add `inverted` to `QueueEventMap` |
+| `template/Template.ts`                       | Register `"inverted"` listener; implement `#handleInverted`                                                    |
+| `template/Template-inverted-section.spec.ts` | New file — 10 test cases                                                                                       |