DEV Community: Mikhail Andreev

Writing Workflows in Claude Code: What They Unlock and Where They Can Bite You

Mikhail Andreev — Mon, 01 Jun 2026 18:39:41 +0000

Anthropic has introduced the Workflow API for Claude Code, so I spent some time digging into how it works in practice.

I looked at how agents are launched, how they pass results between steps, when parallel makes sense, when pipeline is a better fit, and how workflows relate to skills and sub-agents.

In short, workflows let you describe Claude Code's work as a scenario, not as one long prompt.

Not like this:

First do this, then do not forget that, then check one more thing.

But as an actual executable process: phases, agents, input data, response schemas, and a final synthesis step.

Before getting to the nice examples, though, it is worth starting with the limitations. They matter more than they seem at first.

Start with the sandbox

A workflow script does not get full access to your project by itself.

It runs inside an isolated node:vm context. In other words, this is not a normal Node.js application where you can import modules, read files, call APIs, and execute shell commands.

The workflow script has no direct access to:

fs
process
require
module
__dirname
Buffer
fetch
networks
file system
shell commands
Node APIs

import() also does not behave like a normal ESM import.

At first, this may look strange. If the workflow cannot read files or call tools directly, how does it help with code?

The answer is simple: the workflow is not the thing doing the hands-on work.

The agents are.

An agent can read files, search through the project, use LSP, run bash, call MCP tools, or perform web search, assuming those tools are available in the current Claude Code session.

So the mental model looks like this:

workflow orchestrates the process
agents do the work
tools give agents access to code, search, and external context

That is the key idea.

A workflow is not a replacement for agents or skills. It is an orchestration layer above them.

The JavaScript inside the sandbox is still real JavaScript

Do not confuse "sandboxed" with "barely a language."

Inside the workflow, you still have modern JavaScript: arrays, objects, promises, classes, closures, Map, Set, recursion, eval, new Function, and modern V8 features.

For example, this works:

const makeScore = new Function("x", "return x.priority * 2")
const score = makeScore({ priority: 3 }) // 6

This works too:

const rule = "item.severity === 'high'"
const filter = new Function("item", "return " + rule)

const result = [
  { severity: "low" },
  { severity: "high" }
].filter(filter)

That can be useful if you want to build a small router, filter, state machine, or dynamic result-processing logic inside the workflow.

But all of that still happens inside the sandbox.

eval and new Function do not give you access to the host environment. You cannot use them to reach files, the network, or Node APIs.

This will not work:

const fs = require("fs") // require is not defined

And this is not something you should expect to work either:

const files = await fetch("https://example.com") // fetch is not defined

If you need to read a file, find a symbol in the project, call an external service, or run a command, the workflow should delegate that task to an agent via agent().

What we had before workflows

Before workflows, complex processes in Claude Code were usually assembled with skills and sub-agents.

For example, you could write a skill for code review:

First, understand the task.
Then find related files.
Then check the business logic.
Then check the tests.
Do not make a claim without a file and line reference.
If you are unsure, mark the finding as a hypothesis.

This approach works. It is still useful.

A skill gives an agent discipline: how to search, how to verify, which tools to use, and how to format the result. This is especially important in team workflows. Without these rules, agents quickly start producing polished but weak answers.

The problem is not that skills are bad.

The problem is that a skill is still a text instruction. It tells the model how it should behave, but the order of operations does not become a program.

The model has to keep the sequence in context: first find files, then review them, then gather evidence, then produce the report. For small tasks, that is fine. For longer tasks, familiar problems show up:

a step gets skipped;
the review stays too general;
several agents return nearly the same answer;
questionable findings are not rechecked;
the final report is written before all inputs are ready.

A workflow addresses exactly this layer.

It does not tell the agent, "please be careful."

It tells the system:

Run this first, then this, run these checks in parallel, and only then synthesize the result.

The difference may look small on paper, but it is significant in practice.

skills define rules
agents execute tasks
workflow controls the order

What a workflow is

A Claude Code workflow is a JavaScript file that orchestrates sub-agents.

It has a few core building blocks:

agent() starts an agent;
phase() marks a stage of work;
parallel() runs several tasks and waits for all of them;
pipeline() pushes items through several stages;
schema defines the expected response shape;
args passes input data into the workflow.

Simplified, a workflow feels like a small backend process.

The difference is that instead of calling normal functions, you launch agents.

In a skill, you might write:

First find candidate files.
Then verify each finding.
Then produce a report.

In a workflow, that becomes executable code:

phase("Explore")

const candidates = await agent(
  "Find candidate files related to this task."
)

phase("Verify")

const verified = await parallel(
  candidates.files.map(file => () =>
    agent("Verify findings in this file: " + file)
  )
)

phase("Synthesize")

return await agent(
  "Create a final report from verified findings."
)

In a skill, the order is described in words.

In a workflow, the order is executed.

When a workflow is actually worth it

Not every request should become a workflow.

If you need to explain one function, fix one test, or quickly find where something is defined, regular Claude Code is usually enough.

A workflow becomes useful when you have a repeatable sequence.

For example, before opening a pull request, you may always ask Claude Code to:

understand what changed;
find related parts of the codebase;
review business logic;
review tests;
check security risks;
remove weak or unsupported findings;
produce a short report.

In chat, this quickly turns into manual orchestration. You keep reminding the model what to do next. The model remembers some things, misses others, and then you ask it to recheck or shorten the result.

A workflow lets you write that order once.

How workflows relate to skills

There is an important nuance here.

The workflow script itself does not automatically inherit rules from skills. Skills are loaded into the context of a specific agent, usually through agentType.

If you call a plain agent() without an agentType, it may not receive the project-specific rules you expected.

For example, suppose you have an agent that knows how your team searches the codebase: use LSP first, then grep, make claims only with evidence, and always return path and line.

In that case, it is better to explicitly select that agent type:

await agent(
  "Find where this symbol is used. Use LSP before grep. Return path and line.",
  {
    agentType: "keep-backend:codebase-explorer",
    phase: "Explore",
    schema: RESULT_SCHEMA
  }
)

Otherwise, you may get a generic agent that understands the task but does not follow the exact workflow discipline you rely on.

A good rule of thumb:

If the discipline of a step matters, do not rely on magic. Use the right agentType, or write the rule directly in the prompt.

workflow controls the order
skill controls the agent's behavior
agent performs the concrete step

Start with the process, not the code

The most common mistake is to start writing JavaScript immediately.

It is usually better to start with plain text.

For example:

Task: check whether a feature is ready for a pull request.

1. Understand which areas were affected.
2. Separately review logic, tests, and security.
3. Collect the results.
4. Remove duplicates and weak claims.
5. Return risks and next steps.

After that, the code is almost mechanical.

You already have the phases:

Scope → Review → Synthesize

Now you only need to decide where one agent is enough, where several agents should run in parallel, and where you need a final synthesis step.

A minimal workflow

A workflow file starts with meta.

This describes the workflow to Claude Code:

export const meta = {
  name: "feature-review",
  description: "Review a feature before opening a pull request.",
  whenToUse: "Use after implementing a feature.",
  phases: [
    { title: "Scope" },
    { title: "Review" },
    { title: "Synthesize" }
  ]
}

meta should be a simple object. No variables, functions, spread operators, or computed values. The runtime reads it statically.

After that, you can write normal JavaScript:

const A = typeof args === "string" ? JSON.parse(args) : (args || {})
const task = A.task || ""

if (!task) {
  return {
    status: "error",
    message: "Pass task in args."
  }
}

There is an annoying but important detail here: args may arrive as a string. Even if you passed an object, it is safer to parse it with JSON.parse.

If you skip this, you can spend too much time wondering why A.task is empty.

The first agent

An agent performs one concrete step.

phase("Scope")

const scope = await agent(
  "Read the task and identify review areas.\n\nTask:\n" + task,
  {
    label: "scope",
    phase: "Scope"
  }
)

What happens here:

phase("Scope") opens the stage;
agent() starts a sub-agent;
the result is saved into scope.

So far, it looks like a normal prompt. The difference is that the result can now be used by the rest of the code.

Why life gets painful without schemas

Without a schema, an agent returns text.

Text is fine for a human, but it is inconvenient for the next step in a workflow. It is harder to filter, merge, verify, and transform.

That is why most workflows should define response schemas early.

For example, suppose you want a list of review areas:

const SCOPE_SCHEMA = {
  type: "object",
  required: ["areas"],
  properties: {
    areas: {
      type: "array",
      items: { type: "string" }
    }
  }
}

Now use that schema in the agent call:

const scope = await agent(
  "Identify review areas for this task.\n\nTask:\n" + task,
  {
    label: "scope",
    phase: "Scope",
    schema: SCOPE_SCHEMA
  }
)

Now scope.areas is data, not a block of text you have to guess your way through with regexes.

Parallel checks

Suppose the first agent returns three areas:

logic
tests
security

You can review them in parallel:

phase("Review")

const reviews = await parallel(
  scope.areas.map(area => () =>
    agent(
      "Review this task from the angle: " + area + "\n\nTask:\n" + task,
      {
        label: "review:" + area,
        phase: "Review",
        schema: REVIEW_SCHEMA
      }
    )
  )
)

const validReviews = reviews.filter(Boolean)

One important detail: pass functions to parallel(), not already-started promises.

Correct:

parallel([
  () => agent("Check tests"),
  () => agent("Check security")
])

Incorrect:

parallel([
  agent("Check tests"),
  agent("Check security")
])

parallel() is a barrier. It starts several tasks and waits until all of them are done.

That is useful when the next step needs to see the full set of results.

When you need pipeline

pipeline() solves a different problem.

Imagine you have a list of files. Each file must be analyzed first and verified after that. But you do not need to wait until all files are analyzed before starting verification for the first one.

That is what pipeline() is for:

const results = await pipeline(
  files,

  file => agent(
    "Analyze this file for risky changes: " + file,
    {
      label: "analyze:" + file,
      phase: "Analyze",
      schema: REVIEW_SCHEMA
    }
  ),

  (analysis, file) => agent(
    "Verify these findings for " + file + ". Remove weak claims.\n\n" +
    JSON.stringify(analysis),
    {
      label: "verify:" + file,
      phase: "Verify",
      schema: REVIEW_SCHEMA
    }
  )
)

In short:

parallel = start several tasks and wait for all of them
pipeline = move each item through several stages

Use parallel when you need one consolidated report after all checks are complete.

Use pipeline when each file, module, ticket, or item goes through the same chain of steps.

The workflow does not read files, and that is fine

This is worth repeating because it is easy to forget.

The workflow script should not be the hands.

It does not read files. It does not call the network. It does not run shell commands.

This is the wrong mental model:

// now the workflow will read files and find changes by itself

Think like this instead:

await agent(
  "Read the changed files and find risky logic. Cite file paths and lines."
)

If the agent has tools available, it can read files, search the project, use LSP, or run commands.

The workflow does not do the work directly.

It assigns work to agents.

Final synthesis

Do not return raw outputs from every agent directly to the user.

They will almost always contain repetition, inconsistent style, and unnecessary detail. A separate synthesis step usually produces a much better result:

phase("Synthesize")

const report = await agent(
  "Merge these reviews into one concise report. " +
  "Remove duplicates. Keep only actionable findings.\n\n" +
  JSON.stringify(validReviews),
  {
    label: "final-report",
    phase: "Synthesize",
    schema: REVIEW_SCHEMA
  }
)

return {
  status: "ok",
  task,
  report
}

A good final report answers four questions:

what was found
why it matters
where the evidence is
what to do next

A complete starter template

Here is a template you can start from. The prompts should be adjusted for your own project and workflow.

export const meta = {
  name: "custom-review",
  description: "Run a structured review and return actionable findings.",
  whenToUse: "Use when a task needs several checks.",
  phases: [
    { title: "Scope" },
    { title: "Review" },
    { title: "Synthesize" }
  ]
}

const A = typeof args === "string" ? JSON.parse(args) : (args || {})
const task = A.task || ""

if (!task) {
  return {
    status: "error",
    message: "Missing task."
  }
}

const SCOPE_SCHEMA = {
  type: "object",
  required: ["areas"],
  properties: {
    areas: {
      type: "array",
      items: { type: "string" }
    }
  }
}

const REVIEW_SCHEMA = {
  type: "object",
  required: ["summary", "findings"],
  properties: {
    summary: { type: "string" },
    findings: {
      type: "array",
      items: {
        type: "object",
        required: ["severity", "claim", "evidence"],
        properties: {
          severity: { enum: ["high", "medium", "low"] },
          claim: { type: "string" },
          evidence: { type: "string" }
        }
      }
    }
  }
}

phase("Scope")

const scope = await agent(
  "Read the task and identify 3 to 5 useful review areas.\n\nTask:\n" + task,
  {
    label: "scope",
    phase: "Scope",
    schema: SCOPE_SCHEMA
  }
)

if (!scope || !scope.areas || scope.areas.length === 0) {
  return {
    status: "blocked",
    message: "Could not identify review areas."
  }
}

phase("Review")

const reviews = await parallel(
  scope.areas.map(area => () =>
    agent(
      "Review the task from this angle: " + area + "\n\n" +
      "Return concrete findings only. Include evidence.\n\nTask:\n" + task,
      {
        label: "review:" + area,
        phase: "Review",
        schema: REVIEW_SCHEMA
      }
    )
  )
)

const validReviews = reviews.filter(Boolean)

phase("Synthesize")

const finalReport = await agent(
  "Merge the review results into one concise report. " +
  "Deduplicate findings. Keep only actionable issues.\n\n" +
  JSON.stringify(validReviews),
  {
    label: "final-report",
    phase: "Synthesize",
    schema: REVIEW_SCHEMA
  }
)

return {
  status: "ok",
  task,
  report: finalReport
}

How to add agentType

If your project already has specialized agents with skills, use them explicitly.

For example:

const codeFindings = await agent(
  "Explore the codebase for files related to this task. " +
  "Use LSP for symbols. Return exact paths and evidence.\n\nTask:\n" + task,
  {
    agentType: "keep-backend:codebase-explorer",
    label: "code-explorer",
    phase: "Review",
    schema: REVIEW_SCHEMA
  }
)

This starts not just "some agent," but an agent with the rules you actually need.

That matters a lot in team workflows where you may have requirements such as:

use LSP before grep;
do not make claims without evidence;
verify external data through MCP;
return path and line;
separate facts from hypotheses.

Where to save the workflow

Usually, workflows live inside the project:

.claude/workflows/custom-review.js

After that, you can run the workflow by name.

During development, it is often more convenient to run it by file path. That way, Claude Code reads the latest version from disk each time.

If you run a workflow by name and then change the file, reload the registration:

/reload-plugins

Common mistakes

Turning the workflow into one giant prompt

At that point, it becomes the same chat prompt, just stored in a file.

Break the work into phases instead:

Scope → Review → Verify → Synthesize

Forgetting about skills

A workflow does not replace skills.

If an agent must follow specific rules, use the right agentType or write those rules directly into the prompt.

Not defining schemas

Without a schema, the agent returns text.

Text is harder to verify, merge, filter, and pass to the next step.

Waiting for user input inside the workflow

A workflow should not ask the user questions halfway through execution.

If information is missing, return needs_input:

return {
  status: "needs_input",
  questions: [
    "Which branch should I compare against?",
    "Which service is in scope?"
  ]
}

Then the main flow can ask those questions and rerun the workflow with the answers.

Using parallel when you need pipeline

If each item has to pass through several stages, use pipeline().

Otherwise, you create unnecessary waiting points.

Thinking eval bypasses the sandbox

eval and new Function are available, but they still run inside the same isolated context.

They are useful for dynamic logic inside the workflow, such as building a filter function or a small router.

They are not a way to access fs, process, require, the network, or shell commands.

If you need files, commands, or network access, delegate the work to an agent and its tools.

Forgetting about args

Parse args defensively:

const A = typeof args === "string" ? JSON.parse(args) : (args || {})

Otherwise, the workflow may receive a string while your code expects an object.

The main idea

A Claude Code workflow makes the process executable.

A skill tells an agent how to work.

A workflow tells the system in which order to work.

For a useful first workflow, three phases are enough:

Scope → Review → Synthesize

First, the workflow understands the task.

Then it runs the checks.

Then it assembles the final report.

That alone turns a normal prompt into a repeatable working process.

After that, you can add agentType, schema, parallel, pipeline, and stricter rules for agents.

Do not add everything at once.

Start with order, then add discipline, then scale.

What it feels like

If you have worked with LangGraph, the idea will feel familiar.

A Claude Code workflow is similar to building a flow graph: there are steps, executors, transitions, waiting points, and final response assembly.

The difference is the abstraction level.

In LangGraph, you usually build the graph yourself: nodes, edges, state, routing. In Claude Code, the workflow looks simpler: a JavaScript scenario that starts agents with agent(), merges results with parallel(), and moves items through stages with pipeline().

But the thinking is almost the same:

split the task → start executors → pass state → assemble the result

That is why workflows are useful to think of as Claude Code's built-in version of an agentic flow.

Not just "ask the model."

More like building a small system out of steps, agents, and rules.

Autotile Routing Pipeline — Automatic Tile Transition Selection for 2D Maps

Mikhail Andreev — Fri, 27 Feb 2026 23:59:44 +0000

The Problem

Imagine a 2D map editor: the user paints with materials — grass, water, sand, stone. At boundaries between them, you need smooth transitions — not just a hard cut "grass | water", but beautiful smooth edges, corners, and corridors.

This is what autotiling does — a system that automatically selects the right sprite frame based on the cell's neighborhood.

But classic autotiling only handles one transition type (material present / absent). What if you have 10+ materials and not every pair has a dedicated transition spritesheet? How do you visually connect sand to water when you only have sand→dirt and dirt→water?

The Solution: Material Routing

The idea: treat materials as nodes in a graph and transition tilesets as edges. Then "how to visually connect two materials" becomes a shortest path problem.

The 5-Step Pipeline

Step 1 — Tileset Registry

What it is. A centralized, immutable index of all available tilesets. Each tileset declares a pair of materials it can render a transition for: foreground (FG) on top of background (BG). For example:

grass_dirt — grass on a dirt background (transition tileset)
dirt_water — dirt on a water background (transition tileset)
grass (standalone) — grass with no transition, solid fill (base tileset)

If tileset A_B doesn't exist but B_A does, it's used in reverse orientation (mirrored). The registry handles this internally: when asked "can you render grass on water?", it checks both grass_water (direct) and water_grass (reverse) and returns the first hit along with the orientation flag.

Why it's needed. Every downstream step needs fast answers to questions like "does a tileset exist for this pair?", "what's the base tileset for this material?", "give me all known transition pairs." The registry resolves each of these in O(1) via prebuilt hash maps, so the rest of the pipeline never needs to scan the raw tileset array again.

Step 2 — Compatibility Graph Construction

What it is. An undirected graph built from the registry. Nodes are materials. An edge A↔B exists if a tileset for the pair A_B or B_A is registered (in any orientation). A second, directed graph is also built: edge A→B exists only if the direct tileset A_B exists.

Why it's needed. The graph is the input for the routing algorithm in the next step. Without it, we'd have no way to discover multi-hop connections between materials. The undirected graph tells us "which materials can visually transition to each other, directly or through intermediaries." The directed graph is used later for rendering decisions — knowing whether a tileset is direct or reverse matters for correct sprite orientation.

Example. Given tilesets grass_dirt, dirt_water, and sand_dirt, the compatibility graph contains edges: grass↔dirt, dirt↔water, sand↔dirt. There's no direct edge grass↔water or sand↔water, but paths exist through dirt.

Step 3 — BFS Routing (All-Pairs)

What it is. A classic Breadth-First Search from every node over the compatibility graph — an all-pairs shortest path algorithm. For each pair of materials (A, B), the result is stored in a routing table as nextHop(A, B) — the first material on the shortest path from A to B.

nextHop(sand, water) → dirt

This means: "to visually connect sand to water, the first step is dirt — so use the sand_dirt tileset at this boundary."

When multiple shortest paths of equal length exist, tie-breaking uses a configurable preference array (e.g., prefer dirt over stone as an intermediate). This guarantees deterministic, artist-controllable results.

Why it's needed. This is the core insight of the entire pipeline. Classic autotiling requires a dedicated spritesheet for every pair of adjacent materials. With M materials, that's up to M×(M−1)/2 spritesheets — a combinatorial explosion. The routing table eliminates this: artists only need to draw tilesets for direct neighbors in the graph, and the system automatically chains multi-hop transitions for distant materials.

Why BFS specifically? BFS finds the shortest path in an unweighted graph, which maps directly to our goal: minimize the number of intermediate materials in a visual transition chain. It runs in O(V + E) per source, O(V × (V + E)) total — fast enough for the typical 10–30 materials in a game.

Step 4 — Edge Ownership Resolution

What it is. For each cardinal boundary (N/E/S/W) between two cells with different materials, the algorithm determines which cell "owns" the transition — i.e., which cell is responsible for drawing the boundary sprite.

The resolution algorithm:

Compute virtual backgrounds. Both sides query the routing table: cell A computes nextHop(A_material, B_material), cell B computes nextHop(B_material, A_material).
Check tileset availability. Each candidate is valid only if registry.resolvePair(material, virtualBG) returns a result.
Resolve conflicts. If only one side has a valid tileset — that side wins ownership by default. If both sides are valid — the material with the higher priority wins (priority is an artist-configured number). If priorities are equal — lexicographic order on material keys serves as a deterministic tiebreaker so the result is identical regardless of which cell queries.

Why it's needed. Without ownership, both cells would try to draw the same boundary — resulting in double-rendered edges, z-fighting, or visual seams. Exactly one cell must take responsibility for each edge. Ownership also feeds into the Blob-47 mask computation in the next step: a cell's mask bits are adjusted based on which edges it owns, preventing incorrect corner patterns at transition boundaries.

Step 5 — Blob-47 Autotiling

Now we need to turn the routing decisions into an actual sprite frame. This is where Blob-47 comes in — an autotile technique for square-grid tilemaps that determines which sprite to draw based on which of a cell's 8 neighbors share the same terrain. It's called "47" because exactly 47 unique tile configurations exist after applying diagonal gating rules.

The 8-Neighbor Bitmask

Each cell examines all 8 neighbors and builds an 8-bit mask using these weights:

If a neighbor has the same terrain, its bit is set to 1. Otherwise, 0.

For example, if a grass cell has grass neighbors to the North, East, and Northeast, the raw mask is:

N(1) + NE(2) + E(4) = 7

Why a bitmask? It encodes all 256 possible 8-neighbor combinations into a single integer, enabling O(1) lookup into a precomputed frame table. No conditionals, no branching — just a table index.

Diagonal Gating

Here's the key insight: a diagonal neighbor only matters if both adjacent cardinals are also present. Without this rule, you'd get visual artifacts — a corner tile drawn where there's no actual corner.

Consider a cell with grass to the North and Northeast, but not to the East. Drawing a NE corner here is wrong — there's no actual enclosed corner, just two separate edges. Diagonal gating prevents this by clearing the NE bit whenever N or E is absent.

The gating rules:

NE counts only if both N and E are set
SE counts only if both S and E are set
SW counts only if both S and W are set
NW counts only if both N and W are set

gated_mask = keep only cardinal bits (N, E, S, W)
if N and E are set and NE was set → add NE
if S and E are set and SE was set → add SE
if S and W are set and SW was set → add SW
if N and W are set and NW was set → add NW

This reduces the 256 possible raw masks down to exactly 47 valid configurations.

Why exactly 47? There are 4 cardinal bits (2⁴ = 16 cardinal combinations). For each cardinal combination, only the diagonals adjacent to two present cardinals can vary. The math works out to exactly 47 valid gated masks — every other one is impossible under gating.

The 47 Configurations

The 47 valid masks map to specific tile shapes:

Frame Range	Shape	Description
1	Solid	All 8 neighbors present
2–16	Center variants	All 4 cardinals present, different corner combinations
17–20	T-junction open West	N+E+S present, W absent, corner variants
21–24	T-junction open North	E+S+W present, N absent, corner variants
25–28	T-junction open East	N+S+W present, E absent, corner variants
29–32	T-junction open South	N+E+W present, S absent, corner variants
33–34	Corridors	Vertical (N+S) or Horizontal (E+W)
35–42	L-corners	Two adjacent cardinals, with/without filled corner
43–46	Dead-ends	Only one cardinal neighbor
47	Isolated	No neighbors at all

Frame Table Lookup

Instead of computing the frame at runtime with conditionals, a 256-entry lookup table is prebuilt at load time:

FRAME_TABLE[gated_mask] → frame index (0–47)

Frame 0 is reserved for "empty" (no terrain). Frames 1–47 correspond to the autotile variants. Any invalid mask maps to the isolated frame (47) as a fallback.

The full computation for a single cell is:

raw_mask = scan 8 neighbors, set bits for matching terrain
gated_mask = apply diagonal gating
frame = FRAME_TABLE[gated_mask]

This is O(1) per cell — just a bitmask build + a single array lookup.

Why a lookup table instead of if/else chains? With 47 unique cases, hand-coding conditional logic would be error-prone and slow. A 256-byte table is trivial to precompute, fits in L1 cache, and reduces frame resolution to a single memory access.

Spritesheet Layout

Each terrain's spritesheet is a grid of 12 columns × 4 rows = 48 frames:

Frame 0  = empty/transparent
Frame 1  = solid (all neighbors)
Frame 2  = missing NW corner
...
Frame 47 = isolated (no neighbors)

The ordering goes from most connected (solid, frame 1) to least connected (isolated, frame 47). This convention is shared across all terrain types, so artists always know which frame corresponds to which shape.

Out-of-Bounds Handling

Cells at map edges have fewer than 8 neighbors. Two strategies:

Out-of-bounds = matching (default): map edges appear seamless, as if terrain continues beyond the border
Out-of-bounds = not matching: map edges show explicit borders (island-style)

The choice is a single boolean flag on the mask computation — no extra logic needed.

Why Not Blob-255?

Blob-255 uses all 256 possible masks without diagonal gating, requiring 256 sprites per terrain. Blob-47 achieves nearly identical visual quality with 6× fewer sprites — a significant reduction in art production effort. The diagonal gating rule eliminates configurations that would be visually indistinguishable or incorrect anyway.

Transition Mode Extension

Everything described above works for a single terrain type ("same material or not"). The routing pipeline extends it for multi-material transitions:

Base mode (no transition): the mask checks whether each neighbor is the same FG material
Transition mode (selected BG via routing): the mask is built relative to the virtual background material. Additionally, ownership gating overrides cardinal bits based on which cell owns each boundary edge (from Step 4)

This means the same Blob-47 frame table is reused for both plain terrain fills and complex routed transitions — only the mask computation changes.

Why this matters. Reusing the same 47-frame spritesheet for both base terrain and routed transitions means zero additional art assets for multi-material support. The entire multi-material complexity is handled purely in code at the mask level.

Repaint Optimization

When a single cell changes, there's no need to recompute the entire map. The system uses smart dirty propagation:

1. Chebyshev R=2 expansion. When a cell changes, a 5×5 square around it is marked dirty. Why R=2 and not R=1? Because diagonal gating means a cell's frame depends on its neighbors' neighbors. If cell X changes, its neighbor Y's mask changes, and Y's diagonal neighbor Z might also be affected via Y's cardinal relationship with Z. Two hops in Chebyshev distance covers the full influence radius.

2. Edge stability classification. Not all dirty cells actually need redrawing. Each cardinal boundary gets a stability class:

C1 — same material (always stable — nothing to redraw)
C2 — symmetric direct pair; both sides have direct tilesets (stable)
C3 — pair through a common intermediate hop; both sides direct (stable)
C4 — both resolved but routing may change on neighbor edit (unstable)
C5 — at least one side has no route (invalid)

Why classify? The stability class drives the selective commit policy: only cells near stable edges (C1/C2/C3) are committed. C4/C5 neighbors are left untouched — their cached visual state is preserved. This prevents "ripple" artifacts where editing one cell causes a cascade of visual changes across the map through unstable routing chains.

3. Selective commit. From the dirty set, only these are actually redrawn:

The changed cell itself (always)
Cardinal neighbors with C1/C2/C3 edges
Diagonal neighbors, but only if both adjacent cardinals are stable
C4/C5 neighbors are left untouched — their visual state is preserved from cache

4. Per-cell cache. Each cell stores its last computation result: selected tileset key, render tileset key, frame index, virtual background, and orientation. Reverse indices (tileset key → set of cells) enable instant lookup when a tileset is updated or removed — no full-map scan needed.

Complexity Summary

Component	Complexity	Purpose
Registry	O(T)	Index T tilesets into hash maps
Graph	O(T)	Build adjacency from T pairs
BFS Router	O(M² · E)	All-pairs shortest path for M materials
Edge Resolution	O(1) per edge	Determine boundary owner per cardinal
Blob-47	O(1) per cell	Lookup table `mask → frame`
Dirty propagation	O(changed × 25)	Chebyshev 5×5 per changed cell

The entire pipeline exists for one thing: the user just paints with a brush, and the system picks the correct transition tiles in real time — even for materials that have no direct tileset between them — via routing through intermediate materials.