Reference Guide

Behavioral Patterns

Blocktail introduces two behavioral patterns—observer and agent—on top of the foundational L1–L5 layers (matrix, context, block, mutation, tail) that we previously discussed. While those five layers define where components live, Observers and Agents define how they behave. This system provides a structured way to handle block-level lifecycle (Observers) and cross-layer behaviors (Agents) without violating Blocktail’s semantic boundaries.

Understanding the Behavioral Layer System

Copy link to this section

Observer (B1) and Agent (B2)

Copy link to this section

B1: Observer (Behavioral Sovereignty Layer)
- Marker: data-observer="{ObserverName}"
- Purpose: Owns the entire block lifecycle, states, and resources; ensures block-level sovereignty
B2: Agent (Behavioral Application Layer)
- Marker: data-agent="{AgentName}"
- Purpose: Attaches modular or cross-layer behaviors (e.g., analytics, animations) without claiming block sovereignty

By separating block-level ownership (Observer) from modular utilities (Agent), we preserve clear boundaries. Observers control all block logic, yet Agents remain reusable across any layer.

B1: Behavioral Sovereignty Layer (Observer)

Copy link to this section

Marker

Copy link to this section

data-observer="{ObserverName}"

Purpose

Copy link to this section

An Observer manages all lifecycle events, state transitions (mutations), resource usage, and child element interactions for a single block.

Boundary

Copy link to this section

Operates only at the block level (L3)
Claims full control over the block’s mutations and resource governance
One Observer per block (no shared sovereignty)
Establishes a root for processing the block’s behavior

Scope

Copy link to this section

Governs state transitions, e.g., toggling --featured, --on_sale
Manages child elements and event handlers within the block boundary
Maintains resource lifecycle (listeners, network calls)

Composition Model

One observer per block—never mount multiple observers on the same block or violate the sister block’s sovereignty.
Observers may invoke Agents or utility modules (e.g., analytics, logging) internally when extra functionality is needed
Observer-First: All lifecycle logic stays in the main observer. Agents or helper modules remain add-ons but do not become second observers
Clear Sovereignty: Avoid sub-observers in the DOM—any specialized or repeated tasks can be delegated to an Agent or a utility imported directly into the observer

Behavioral Sovereignty terminology: The notion that one entity (the Observer) is the single authority over a block’s states, resources, and lifecycle.

B2: Behavioral Application Layer (Agent)

Copy link to this section

Marker

Copy link to this section

data-agent="{AgentName}"

Purpose

Copy link to this section

Applies standardized or reusable behaviors across any layer (L1–L5). Agents may be:

Mounted via data-agent (e.g., data-agent="LazyLoad")
Invoked by an Observer for cross-layer tasks (analytics, animations, global updates, logging)

Boundary

Copy link to this section

No sovereignty claims over the block
Practically enhances or augments any layer: system, context, block, or tail
Coexists with Observers but never competes for state or lifecycle

Scope

Copy link to this section

Integrates third-party functionality or custom utility scripts
Maintains pattern consistency by separating cross-layer behaviors from block-specific logic

Behavioral Application terminology: A utility or cross-layer behavior that applies enhancements without claiming ownership.

Layer Integration Matrix

Copy link to this section

Let’s take a look at how B1 (Observer) and B2 (Agent) integrate with the core L1–L5 layers:

System Context Layer (L1: matrix--)

Copy link to this section

<!-- L1 + B2: System-wide Agent -->
<body class="matrix--shop"                 <!-- L1 -->
      data-agent="SystemAnalytics">        <!-- B2: global analytics -->
  <!-- System-wide behavior application -->
</body>

/* ✗ INVALID: Observers at system level */
<body class="matrix--shop"
      data-observer="SystemObserver">      <!-- Invalid -->
</body>

Local Context Layer (L2: context--)

Copy link to this section

<!-- L2 + B2: Context Agent -->
<main class="context--catalog"             <!-- L2 -->
      data-agent="InfiniteScroll">         <!-- B2 -->
  <!-- Context-level behavior application -->
</main>

/* ✗ INVALID: Observers at context level */
<main class="context--catalog"
      data-observer="CatalogObserver">     <!-- Invalid -->
</main>

Component Reference Layer (L3: block_name)

Copy link to this section

<!-- L3 + B1: Block Observer with Mutations -->
<article class="product_card --featured"   <!-- L3 + L4 -->
         data-observer="ProductObserver">  <!-- B1 -->
  <!-- Observer controls block lifecycle & states -->
</article>

<!-- L3 + B2: Block Agent -->
<article class="product_card"              <!-- L3 -->
         data-agent="RevealAnimation">     <!-- B2 -->
  <!-- Reusable cross-layer behavior at the block level -->
</article>

<!-- L3 + B1 + B2: Combined with Mutations -->
<article class="product_card --featured    <!-- L3 + L4 -->
         --on_sale"                       <!-- Additional mutation -->
         data-observer="ProductObserver"   <!-- B1 -->
         data-agent="RevealAnimation">     <!-- B2 -->
  <!-- Observer retains sovereignty while Agent adds behavior -->
</article>

Element Layer (L5: -tail)

Copy link to this section

<!-- L5 + B2: Tail Agent -->
<article class="product_card"              <!-- L3 -->
         data-observer="ProductObserver">   <!-- B1 -->
  <div class="-content"                    <!-- L5 -->
       data-agent="LazyLoad">             <!-- B2 -->
    <!-- Tail-level behavior application -->
  </div>
</article>

/* ✗ INVALID: Observers at tail level */
<article class="product_card">             <!-- L3 -->
  <div class="-content"                    <!-- L5 -->
       data-observer="ContentObserver">    <!-- Invalid -->
  </div>
</article>

Layer Access Rules

Copy link to this section

Observer

Copy link to this section

<!-- ✓ VALID: Block-Level with Mutations -->
<article class="product_card --featured --on_sale" 
         data-observer="ProductObserver">
  <!-- Observer controls the entire block (states, resources) -->
  <div class="-content">
    <!-- Everything is under observer control -->
  </div>
</article>

/* ✗ INVALID: Observers at other layers */
<body class="matrix--shop" data-observer="ShopObserver">         <!-- Invalid -->
<main class="context--catalog" data-observer="CatalogObserver">  <!-- Invalid -->
<div class="-content" data-observer="ContentObserver">           <!-- Invalid -->

Agent

Copy link to this section

<!-- ✓ VALID: Agents can attach to any layer -->
<body class="matrix--shop" data-agent="SystemAgent">          <!-- L1 -->
<main class="context--catalog" data-agent="ContextAgent">     <!-- L2 -->
<article class="product_card" data-agent="BlockAgent">        <!-- L3 -->
<div class="-content" data-agent="TailAgent">                 <!-- L5 -->

Observer Mutation Control

Copy link to this section

Observers manage all block-level mutations (e.g. --active, --featured) without interference:

class ProductObserver {
  constructor(element) {
    this.block = element;
    this.mutations = this.getCurrentMutations();
  }

  getCurrentMutations() {
    return {
      featured: this.block.classList.contains('--featured'),
      onSale:   this.block.classList.contains('--on_sale')
    };
  }

  init() {
    if (this.mutations.featured) this.initializeFeaturedState();
    if (this.mutations.onSale)   this.initializeSaleState();
  }

  setMutation(mutation, active) {
    const mutClass = `--${mutation}`;
    this.block.classList.toggle(mutClass, active);
    this.mutations[mutation] = active;
    active ? this.initializeMutationState(mutation)
           : this.cleanupMutationState(mutation);
  }
}

This approach:

Enforces single ownership of states
Keeps block-level transitions consistent
Preserves pattern recognition across expansions

Pattern Recognition Flow

Copy link to this section

<PATTERN_FLOW>
matrix--shop                     <!-- L1: system -->
  data-agent="Analytics"         <!-- Agent for system-wide analytics -->
  context--catalog               <!-- L2: context -->
    data-agent="InfiniteScroll"  <!-- Agent for context-level pagination -->
    product_card                 <!-- L3: block -->
      --featured --on_sale       <!-- L4: mutations -->
      data-observer="ProductObserver"   <!-- Observer = block sovereignty -->
      data-agent="RevealAnimation"      <!-- Agent = cross-layer effect -->
      -content                   <!-- L5: tail -->
        data-agent="LazyLoad"    <!-- Additional tail-level agent -->
</PATTERN_FLOW>

Implementation Benefits

Copy link to this section

Clear Behavioral Boundaries
- Observer for block sovereignty, Agent for modular behaviors
State Management
- Observers unify block-level state transitions
- Agents add or remove cross-layer tasks easily
Pattern Recognition Stability
- Minimal collisions, fewer naming collisions or confusion
Predictable Scaling
- Observers handle complex block expansions; Agents remain reusable
Maintainable Structure
- Single responsibility for block logic, flexible agent invocation

Key Takeaways

Copy link to this section

Observer (B1): Block sovereignty: all lifecycle, states, resource usage in a single owner
Agent (B2): Cross-layer or reusable utilities: attachable at any layer, never overshadowing the observer

This Behavioral Layer System ensures semantic clarity, predictable evolution, and scalable mission-critical architecture. Observers keep each block’s logic unified, while Agents offer flexible, reusable enhancements with minimal overhead or fragmentation—a crucial balance for large or fast-evolving front-end codebases.

Code licensed MIT, docs CC BY 4.0.