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

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 or 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:

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, 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

# 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

# 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

// 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.

---

Key Source Files in unclebob/swarm-forge

File	Purpose
src/config/windowParser.js	Tokenizes and validates window directives from configuration files
src/runtime/WindowRegistry.js	Maintains the specifier-to-window mapping for runtime lookup
src/ui/WindowComponent.jsx	React component rendering the editable window interface
src/api/windowApi.js	Server-side API handling save operations and content persistence
src/runtime/requestHandler.js	Routes requests containing window parameters to the appropriate handler
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, with definitions stored in WindowRegistry
• Resolution happens on-demand when requests include window=<specifier> parameters
• Rendering is handled by WindowComponent.jsx, providing full edit-save-cancel functionality
• API persistence routes through 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}