# How the `window` Directive Works in SwarmForge Configuration: A Complete Guide

> Learn how the SwarmForge `window` directive creates editable UI regions. This guide explains specifiers, titles, and content for dynamic rendering in your configuration.

- Repository: [Robert C. Martin/swarm-forge](https://github.com/unclebob/swarm-forge)
- Tags: how-to-guide
- Published: 2026-08-28

---

**The `window` directive in SwarmForge defines a bounded, editable UI region by declaring a specifier, title, and optional content in your configuration file, which the runtime registers and renders when triggered by requests or commands.**

The `window` directive is a core configuration primitive in **unclebob/swarm-forge** that bridges static YAML/json configuration with interactive document editing. When you declare a window, you're essentially creating a named, reusable UI component that can be summoned with a simple parameter or API call.

---

## What the `window` Directive Defines

SwarmForge configuration (typically [`forge.yaml`](https://github.com/unclebob/swarm-forge/blob/main/forge.yaml) or [`forge.json`](https://github.com/unclebob/swarm-forge/blob/main/forge.json)) uses the `window` directive to declare three essential properties:

- **Specifier** – A unique identifier (e.g., `coder`, `grok master`) that acts as the lookup key
- **Title** – The human-readable label displayed in the UI tab or header
- **Content** – Optional default text pre-loaded into the editor when the window opens

The directive follows a simple declarative pattern:

```yaml
window <specifier> "<title>"
  [optional multi-line content block]

```

According to the SwarmForge source code, this pattern is parsed by configuration handlers that extract these components and register them for runtime resolution.

---

## How the `window` Directive Is Parsed and Registered

### Configuration Parsing

The `window` block is scanned during forge initialization. The parser identifies the directive, tokenizes the specifier and title, and captures any indented body content as the window's default document state.

### Runtime Registration

Parsed window definitions are stored in an internal registry that maps **specifier → window object**. This registry enables O(1) lookup when windows are referenced by name in subsequent operations.

From [`src/config/windowParser.js`](https://github.com/unclebob/swarm-forge/blob/main/src/config/windowParser.js), the parsing logic extracts:

1. The *specifier* (first token after `window`)
2. The *title* (quoted string or unquoted identifier)
3. The *body* (all indented lines following the declaration)

### Request Resolution

When a request includes a `window` parameter—such as `fetch /doc?path=README.md&window=coder`—the runtime handler:

1. Extracts the `window` query parameter value (`coder`)
2. Queries the window registry for the matching specifier
3. Instantiates a client-side window component with the stored title and optional content
4. Renders the editable UI with **Save** and **Cancel** controls

---

## Practical `window` Directive Examples

### Example 1: Minimal Window Declaration

```yaml

# forge.yaml

window coder "Grok Coder"

```

This creates a window with specifier `coder` and title "Grok Coder". When triggered, it opens an empty editor ready for input.

### Example 2: Window with Default Content

```yaml

# forge.yaml

window specEditor "API Specification Editor"
  # API Contract Template

  
  ## Endpoints

  - GET /users
  - POST /users
  
  ## Schemas

  [Define your JSON schemas here]

```

The indented block becomes the initial document loaded into the editor. Users can modify this template before saving.

### Example 3: Triggering the Window from Client Code

```javascript
// Open the specEditor window with a specific document
await fetch('/doc?path=openapi.yaml&window=specEditor');

```

The `window=specEditor` parameter instructs the server to resolve and render the window defined above, pre-populated with the contents of [`openapi.yaml`](https://github.com/unclebob/swarm-forge/blob/main/openapi.yaml).

---

## Key Source Files in unclebob/swarm-forge

| File | Purpose |
|------|---------|
| [`src/config/windowParser.js`](https://github.com/unclebob/swarm-forge/blob/main/src/config/windowParser.js) | Tokenizes and validates `window` directives from configuration files |
| [`src/runtime/WindowRegistry.js`](https://github.com/unclebob/swarm-forge/blob/main/src/runtime/WindowRegistry.js) | Maintains the specifier-to-window mapping for runtime lookup |
| [`src/ui/WindowComponent.jsx`](https://github.com/unclebob/swarm-forge/blob/main/src/ui/WindowComponent.jsx) | React component rendering the editable window interface |
| [`src/api/windowApi.js`](https://github.com/unclebob/swarm-forge/blob/main/src/api/windowApi.js) | Server-side API handling save operations and content persistence |
| [`src/runtime/requestHandler.js`](https://github.com/unclebob/swarm-forge/blob/main/src/runtime/requestHandler.js) | Routes requests containing `window` parameters to the appropriate handler |
| [`test/dashboard/dashboard.spec.js`](https://github.com/unclebob/swarm-forge/blob/main/test/dashboard/dashboard.spec.js) | Test coverage demonstrating window directive behavior (lines 53 and 156) |

---

## Summary

- The **`window` directive** binds a specifier, title, and optional content into a reusable UI configuration
- **Parsing** occurs at forge startup via [`src/config/windowParser.js`](https://github.com/unclebob/swarm-forge/blob/main/src/config/windowParser.js), with definitions stored in `WindowRegistry`
- **Resolution** happens on-demand when requests include `window=<specifier>` parameters
- **Rendering** is handled by [`WindowComponent.jsx`](https://github.com/unclebob/swarm-forge/blob/main/WindowComponent.jsx), providing full edit-save-cancel functionality
- **API persistence** routes through [`windowApi.js`](https://github.com/unclebob/swarm-forge/blob/main/windowApi.js) to commit changes back to the document store

---

## Frequently Asked Questions

### What happens if I reference a window specifier that doesn't exist?

The runtime returns a configuration error at parse time if the directive is malformed, or a runtime lookup failure if the specifier is undefined. Always verify your specifier matches a declared `window` block.

### Can I define multiple windows with the same specifier?

No—specifiers must be unique within a configuration. The registry uses the specifier as a primary key; duplicates cause initialization errors in [`windowParser.js`](https://github.com/unclebob/swarm-forge/blob/main/windowParser.js).

### How do I pre-populate a window with content from a file rather than inline text?

Use the `fetch` command with `window=<specifier>` and a `path` parameter. The runtime loads the file content into the window's editor, overriding any inline default content defined in the directive.

### Are window titles localized?

Titles are defined literally in configuration. For localization, use a templating layer or externalize titles through environment-specific config overlays before the parser processes the directive.