Mogu Visual

Mogu Visual

Transform technical concepts into interactive animated HTML visualizations starring Mogu.

Before writing any code, read references/character.md -- it contains the canonical Mogu specification that governs every visual decision below. If the reference fails to load, the inline quick reference in Section 4 of this document is sufficient to draw a correct Mogu.

Workflow

Step 1: Extract Concepts

Parse the user's input and enumerate every distinct concept before doing anything else. This is the most critical step — concepts that aren't listed here will be invisible in the output.

1a. Section-by-section extraction: Walk through the input text section by section (not a single pass). For each paragraph or section, ask: "What concepts are introduced here that aren't already in my list?" Tag each concept with the source section for traceability.

1b. Implicit concept scan: After the explicit pass, scan for concepts the text implies but doesn't name directly: consistency boundaries, failure domains, trust zones, ownership boundaries, backpressure, retry behavior, ordering guarantees, staleness.

1c. Deduplication: Group aliases that refer to the same concept. "Broker," "message broker," and "coordination layer" might be one concept or three — resolve based on context.

1d. Assign concept IDs: Give each deduplicated concept a stable ID (C01, C02, ...). These IDs track through the entire pipeline: extraction → categorization → mapping → code → rendered output.

1e. Concept categorization: Classify each concept. The taxonomy has 12 types — use the most specific match, not the first match:

Multi-type concepts: A concept can have a primary type and secondary tags. A database is primarily an Entity but also a Source of Truth. A queue is an Entity but also has Metric/Resource (depth) and Constraint (capacity limit). Tag the primary type in the categorization, add secondary tags in parentheses: C07 MessageQueue [Entity (Metric, Constraint)]. The primary type determines the main visual element; secondary tags add overlays (gauge, boundary, badge).

1f. Complexity assessment: Count concepts. Then decide the scope:

1g. View design (if multi-view):

First, group concepts using one of these strategies (pick the one that best fits the input):

Then for each view, define:

• Purpose: what question does this view answer?
• Concepts shown (by ID): which concepts are active? Target ≤ 8 per view (soft cap — allow 9-10 if concepts are spatially grouped and don't clutter; never exceed 12)
• Anchor concepts: which concepts appear in ALL views as spatial landmarks (same position)?
• Cross-view links: which flows/relationships connect this view to others?

1h. Clarifying questions (only if needed):

• Audience? Developer, student, PM, general public?
• Which aspect? The whole system or a specific mechanism?
• Depth? High-level overview or implementation-level detail?

Step 2: Write the Scene Script

The scene script must include a concept coverage manifest — every concept ID from Step 1 must appear with its visual encoding. This is the traceability contract.

Scene: [title]
Archetype: [archetype name or "custom: X + Y"]

Concept Coverage Manifest:
  C01 [concept name] → [visual element] — [encoding: position/cap/shape/motion/color/size/zone/stat/gate]
  C02 [concept name] → [visual element] — [encoding]
  C03 [concept name] → deferred to view:[view name] — [encoding when active]
  ...
  Coverage: N/N concepts mapped (must be 100%)

Views (if multi-view):
  - [view name] — purpose: [question it answers]
    Active: C01, C03, C07, C12 (≤8)
    Anchors: C01, C03
    Toggle: param "view" value "[name]"

Actors:
  - [role] ([size], [cap color], [cap shape], [texture]) — represents C01, C04
Items: [what flows, differentiated by shape/color — each type maps to a concept ID]
Connections: [relationships, style maps to relationship type]
Zones: [boundary/domain regions drawn via onDraw — each maps to a concept ID]
Parameters:
  - [name]: [type] [range] [default] — reveals/controls C07
  - view: toggle [view names] — switches active concept set
Key Moments:
  - [trigger] → [visual effect] — demonstrates C09 ([event/trigger concept])
Stats:
  - [stat name] — tracks C15 ([metric concept])

Rendering patterns for hard concept types (not just actors and items):

Scene archetype selection (see references/scenes.md):

Present the scene script to the user for confirmation before generating code. This is the contract — changes after code generation are expensive.

Step 2.5: Concept Coverage Audit

Before proceeding to Step 3, run this checklist against the concept manifest:

1. 100% coverage: Every concept ID from Step 1 appears in the manifest. Count them. If coverage < 100%, stop and fix the scene script. No exceptions.
2. No text-only escapes: If a concept's encoding is just "label" or "annotation," reconsider — can it be a cap shape, item variation, zone, gauge, gate, or expression instead? Text is a last resort. If text is truly the only option, add a textOnlyReason.
3. "Deferred" concepts must resolve: Every concept deferred to a view must have that view defined, with the concept listed as active in that view. Grep the manifest for "deferred" and verify each has a matching view entry.
4. Visual differentiation: If multiple concepts share the same type (e.g., 4 kinds of WorkItem), each must have a distinct visual encoding (shape + color, not just label).
5. States have transitions: If a concept has a lifecycle (proposed → active → blocked → completed), the visualization must show ≥ 2 states and animate the transition.
6. Layers are spatial: If the concept has architectural layers or tiers, they must be visually separated as canvas zones, not just described in text.
7. Policies branch: If a concept is a policy/strategy, the visualization must show the decision point and at least 2 different outcomes.
8. Boundaries enclose: If a concept is a boundary/domain, it must be drawn as a visible region with actors inside, not just labeled.

If any check fails, revise the scene script before generating.

Step 3: Design the Cast

Select cap shapes, textures, and colors for each Mogu actor. Follow rules from references/character.md:

• Size = importance. Central component gets the largest Mogu.
• Same color = same role. All API services share one color, all databases another.
• Max 3 cap colors per scene. More than 3 creates visual noise. Use shape/texture variation instead if you need more groups.
• Colors: Saturated but muted. Must pair with cream stem #F5EDE0.

Step 4: Generate HTML

Use the MoguScene engine (components/mogu-engine.js) to keep generated HTML short and focused on scene logic.

HTML template:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>[Scene Title] — Mogu Visual</title>
  <style>
    * { margin:0; padding:0; box-sizing:border-box; }
    html, body { width:100%; height:100%; overflow:hidden; }
    canvas { display:block; width:100%; height:100%; }
  </style>
</head>
<body>
<canvas id="c"></canvas>
<!-- Path assumes output is in a sibling directory to components/ (e.g., test-output/).
     For standalone distribution, inline the engine or adjust the path. -->
<script src="../components/mogu-engine.js"></script>
<script>
// --- Scene code starts here (target: 150-250 lines) ---
var scene = new MoguScene(document.getElementById('c'), { title: '[Scene Title]' });

// 1. Add actors
scene.addActor('id', { label: 'Name', x: 0.5, y: 0.5, size: 80, cap: { color: '#FF4D4D' } });

// 2. Add connections
scene.connect('from', 'to', { style: 'dashed' });

// 3. Add parameters
scene.addParam({ id: 'rate', label: 'Rate', type: 'slider', min: 1, max: 30, value: 5, step: 1 });

// 4. Scene logic
scene.onUpdate(function(dt, time) { /* spawn items, manage state */ });
scene.onDraw(function(ctx, w, h, time) { /* custom visuals */ });

// 5. Start with absorption
scene.start(['keyword1', 'keyword2'], '#targetCapColor');
</script>
</body>
</html>

Engine API quick reference:

Built-in cap shapes (use by string name): dome, flat, pointy, wavy, bumpy, droopy, split, spiky

Built-in textures (use by string name): spots, stripes, hex, circuit, swirl, constellation, scales, lightning

The rule: AI generates only scene-specific code. The engine handles rendering, game loop, controls, labels, connections, items, and the absorption ceremony. If the generated HTML exceeds 300 lines, you're probably reimplementing something the engine already provides.

Step 5: Quality Gate

Check every item before delivering. If any row fails, fix it before handing off.

Label layout rules (common source of visual bugs):

1. Labels go below their Mogu, offset by at least moguSize * 0.35 from center. Never place labels at a fixed y that ignores Mogu size.
2. Never stack two text elements without clearance. If a queue bar / counter / status text exists between a Mogu and its label, the label goes below ALL of them.
3. Shorten labels when actors multiply. 5 consumers labeled "Consumer 1" through "Consumer 5" will overlap. Use "C1"–"C5" or omit labels when the cap color already distinguishes roles.
4. Queue/status indicators inside or to the side, not stacked below in the same column as the label. Prefer rendering counts inside bars (textBaseline = 'middle') rather than as separate text below.
5. Test at extremes. Check layout with max actor count (e.g., 5 consumers) and max queue depth. If pills/items overflow their container, cap the visible count.

Mogu Character Quick Reference

This section is the fallback specification. If references/character.md loads, prefer that. If it does not, everything below is sufficient to draw a correct Mogu.

Canonical SVG

Source of truth. ViewBox: 0 0 140 170.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 170">
  <!-- Stem: rx=14 gives soft rounded corners -->
  <rect x="50" y="95" width="40" height="50" rx="14" fill="#F5EDE0"/>

  <!-- Cap: dominant dome, ~2.6x wider than stem -->
  <ellipse cx="70" cy="82" rx="52" ry="38" fill="#FF4D4D"/>

  <!-- Cap highlight: subtle polish, shifted upper-left -->
  <ellipse cx="55" cy="68" rx="18" ry="10" fill="#FF7070" opacity="0.5"/>

  <!-- Spots: 3 circles, varied size, scattered unevenly -->
  <circle cx="42" cy="72" r="6" fill="#FF8080" opacity="0.7"/>
  <circle cx="68" cy="55" r="5" fill="#FF8080" opacity="0.7"/>
  <circle cx="90" cy="68" r="7" fill="#FF8080" opacity="0.7"/>

  <!-- Eyes: solid black dots on stem, no highlights -->
  <circle cx="60" cy="115" r="4.5" fill="#0a0a0a"/>
  <circle cx="80" cy="115" r="4.5" fill="#0a0a0a"/>

  <!-- Mouth: simple upward arc -->
  <path d="M63,127 Q70,133 77,127" stroke="#0a0a0a" stroke-width="2.5" fill="none" stroke-linecap="round"/>

  <!-- Feet: small ellipses for grounding -->
  <ellipse cx="58" cy="145" rx="10" ry="4" fill="#EBE0D0"/>
  <ellipse cx="82" cy="145" rx="10" ry="4" fill="#EBE0D0"/>
</svg>

Proportions (Scale-Independent Ratios)

These ratios hold at any render size. The size parameter in drawMogu() maps to the viewBox height (170 units).

Invariants (Never Change)

These values are fixed across all Mogus regardless of concept:

Never change stem/feet colors, eye color, or the proportions above.

Expression System

Only eyes and mouth change. No new elements added. Alert is the only expression with eye-whites.

Cap Shapes (8 Reference Shapes)

Shape = structural metaphor. The AI can invent new shapes beyond these.

Each shape function receives (ctx, cx, cy, capRx, capRy), calls ctx.beginPath(), draws the path, and leaves it open for the caller to fill.

Cap Textures (8 Reference Textures)

Texture = surface pattern mapped to concept characteristics.

Each texture function receives (ctx, cx, cy, capRx, capRy, spotColor, baseAlpha). The 7th param baseAlpha (0-1, default 1) is a multiplier for all alpha values inside the texture. This enables ghost/derived actors to render textures at reduced opacity. Textures set ctx.globalAlpha = ownAlpha * baseAlpha, draw the pattern, then restore ctx.globalAlpha = 1.0.

Cap Color Palette

Colors should be saturated but muted -- "as if the mushroom grew that way naturally." Must pair with the cream stem #F5EDE0. No rigid domain-to-color mapping.

Multi-Mogu Rules

When multiple Mogus appear in a single scene:

1. Size = importance. Primary component = largest. Helpers = small.
2. Same cap color = same role. All API services share one blue. All DBs share one brown.
3. Max 3 cap colors per scene. Use shape/texture variation for additional groups.
4. Spatial arrangement: Data flow left-to-right. Hierarchy top-to-bottom. Peers in a row.
5. Same shape/texture = same structure type. All async services get wavy caps.

Absorption Ceremony

The 4-step brand intro sequence. Total duration: 3 seconds at 60fps.

Step 1: Idle (0-0.8s)

• Cap: #FF4D4D (red), classic dome, classic spots
• Expression: neutral
• Y-offset: sinusoidal idle bounce (+-2px, 2.5s period)

Step 2: Notice (0.8-1.5s)

• Expression: curious
• Keywords float in from the right (stagger 0.1s, slide + fade, monospace #aaa)
• Idle bounce continues

Step 3: Swallow (1.5-2.2s)

• Expression: processing
• Cap inflates: capRy increases by 15% (spring easing with overshoot)
• Keywords scale down toward cap center, fade out

Step 4: Ready (2.2-3.0s)

• Expression: proud
• Cap color lerps to final semantic color (ease-out, 0.5s)
• Cap shape morphs to final shape (if different from dome)
• capRy returns to normal (ease-out, 0.3s)
• One final small hop

After the ceremony, the Mogu is the concept and the main visualization begins.

Timing control:

var time = 0; // seconds, incremented each frame by dt

if (time >= 1.5 && time < 2.2) {
  var stepTime = time - 1.5;
  var stepDuration = 0.7;
  var t = Math.min(stepTime / stepDuration, 1);
  var inflateAmount = ease.spring(t, 0.5);
  capRy = baseCapRy * (1 + 0.15 * inflateAmount);
}

Color interpolation (RGB lerp):

function lerpColor(hex1, hex2, t) {
  var r1 = parseInt(hex1.substring(1, 3), 16);
  var g1 = parseInt(hex1.substring(3, 5), 16);
  var b1 = parseInt(hex1.substring(5, 7), 16);
  var r2 = parseInt(hex2.substring(1, 3), 16);
  var g2 = parseInt(hex2.substring(3, 5), 16);
  var b2 = parseInt(hex2.substring(5, 7), 16);
  var r = Math.round(r1 + (r2 - r1) * t);
  var g = Math.round(g1 + (g2 - g1) * t);
  var b = Math.round(b1 + (b2 - b1) * t);
  return '#' + ((1 << 24) + (r << 16) + (g << 8) + b).toString(16).slice(1);
}

Quick Reference Links

• MoguScene engine: components/mogu-engine.js — load this in generated HTML, write only scene code
• Character spec: references/character.md
• Scene archetypes: references/scenes.md
• Interaction patterns: references/interactions.md
• Complete examples: references/examples.md
• Canonical SVG: components/mogu.svg
• Expression variants: components/mogu-expressions.svg
• Low-level drawing code (for reference, not direct use): components/widgets.js