Skip to content

mirkosertic/Megahub / .claude/skills/blockly

blockly

Verified

Blockly visual programming context for the Megahub project. Use when adding, modifying, or debugging custom Blockly blocks, the Lua code generator, the toolbox, block colors, or the BLOCKS.md documentation generation script.

FileKindSize
SKILL.mdskill md10.6 KB
---
name: blockly
description: Blockly visual programming context for the Megahub project. Use when adding, modifying, or debugging custom Blockly blocks, the Lua code generator, the toolbox, block colors, or the BLOCKS.md documentation generation script.
---

# Blockly Integration — Megahub IDE

## Overview

- **Blockly 12.3.1** with the built-in **Lua code generator** (`blockly/lua`)
- Custom Web Component `<custom-blockly>` in `frontend/src/components/blockly/component.js`
- Each custom block is a **self-contained JS file** with definition + Lua generator + color
- All 25 custom blocks auto-register; `BLOCKS.md` is auto-generated via Puppeteer

---

## File Structure

```
frontend/src/components/blockly/
  component.js          Main component — init, toolbox, workspace, Lua generation
  component.html        Minimal web component template
  colors.js             Color hue constants for all categories (0–360)
  mh_*.js               20 Megahub core blocks (motors, GPIO, threads, debug)
  lego_*.js             2 LEGO Powered Up blocks
  ui_*.js               1 UI display block
```

---

## Block Definition Pattern

Every block is one file. All fields are required unless noted:

```javascript
export const definition = {
    category: 'Category Name',      // Groups this block in the toolbox
    colour: colorConstant,          // Import from colors.js — never hardcode
    blockdefinition: {              // Standard Blockly JSON definition
        type: 'mh_block_name',      // Must match filename (minus .js)
        message0: 'label %1 %2',    // %N = input/field placeholders
        args0: [ /* inputs */ ],
        previousStatement: null,    // Include for statement blocks
        nextStatement: null,        // Include for statement blocks
        // OR: output: null         // For value blocks that return a value
        tooltip: 'Description for BLOCKS.md and hover UI',
        helpUrl: ''
    },
    generator: (block, generator) => {
        // Return string + "\n" for statement blocks
        // Return [ "code", precedence ] for value blocks
    },
    inputsForToolbox: { /* optional shadow defaults */ }
};
```

### Statement block generator pattern
```javascript
generator: (block, generator) => {
    const val = generator.valueToCode(block, 'VALUE', 0);
    const stmt = generator.statementToCode(block, 'DO');
    const field = block.getFieldValue('FIELD_NAME');
    return `myFunction(${val}, ${field})\n`;
}
```

### Value block generator pattern
```javascript
generator: (block, generator) => {
    const val = block.getFieldValue('VALUE');
    return [ val, 0 ];   // [ code, precedence ]
}
```

---

## Naming Conventions

| Prefix | Category | Example |
|--------|----------|---------|
| `mh_` | Megahub core | `mh_set_motor_speed`, `mh_wait`, `mh_startthread` |
| `lego_` | LEGO Powered Up | `lego_get_mode_dataset`, `lego_select_mode` |
| `ui_` | User interface | `ui_show_value` |

- All lowercase, underscores only
- Block type ID **must match** the JS filename (e.g., `mh_wait.js` → `type: 'mh_wait'`)

---

## Color System (`colors.js`)

Colors are Blockly hue values (0–360). Always import — never hardcode a number.

| Constant | Hue | Category |
|----------|-----|----------|
| `colorControlFlow` | 20 | Control flow |
| `colorLogic` | 40 | Logic |
| `colorMath` | 60 | Math |
| `colorText` | 80 | Text |
| `colorLists` | 100 | Lists |
| `colorIO` | 120 | I/O |
| `colorLego` | 140 | LEGO© |
| `colorGamepad` | 160 | Gamepad |
| `colorFastLED` | 180 | FastLED |
| `colorIMU` | 200 | IMU |
| `colorUI` | 220 | UI |
| `colorAlgorithms` | 230 | Algorithms |
| `colorDebug` | 240 | Debug |

---

## Adding a New Block

1. **Create** `frontend/src/components/blockly/mh_myblock.js` using the pattern above
2. **Import and register** in **all three** files:
   - `frontend/src/components/blockly/component.js` — add import + entry in `customBlocks`
   - `frontend/scripts/block-renderer.js` — add import + entry in `customBlocks`
   - `frontend/scripts/generate-block-docs-simple.js` — add dynamic import in `blockModules` + entry in `customBlocks`
3. **Toolbox**: automatic — `generateToolbox()` groups by `category` field
4. **Write unit tests** — REQUIRED for every new block (see below)
5. **Test** in dev mode: `npm run dev` or `npm test`
6. **Regenerate docs** — REQUIRED after every block add/modify/remove:
   ```bash
   cd frontend
   npm run generate-docs
   ```
   This regenerates `BLOCKS.md` and all PNG images in `docs/blocks/`. Never skip this step.

---

## Unit Tests — REQUIRED for Every New Block

Every new block file **must** have a corresponding test file. This is a hard requirement.

**Location:** `frontend/test/blockly/{block_type}.test.js`

**Test file must cover:**
1. **Generator output** — correct Lua string emitted for representative inputs
2. **Field values** — all dropdown options generate the correct Lua variant
3. **Statement vs. value form** (for dual-mode blocks like `mh_startthread` pattern) — both forms generate correct output
4. **Edge cases** — empty inputs, zero values, boundary field options

**Minimal test pattern:**
```javascript
import { describe, it, expect } from 'vitest';
// Import the block definition
import { definition } from '../../../../src/components/blockly/mh_myblock.js';

describe('mh_myblock generator', () => {
    it('generates correct Lua for basic case', () => {
        const mockBlock = {
            getFieldValue: (name) => name === 'MY_FIELD' ? 'VALUE' : '',
            outputConnection: null,
        };
        const mockGenerator = {
            valueToCode: (_b, _name, _prec) => '42',
        };
        const result = definition.generator(mockBlock, mockGenerator);
        expect(result).toBe('myFunction(42, "VALUE")\n');
    });
});
```

**Run tests:**
```bash
cd frontend
npm test
```

**When to create tests:** Immediately after creating the block file, before registering it in `component.js`. Tests run in CI — a block without tests is incomplete.

The `component.js` registration loop handles everything:
```javascript
// Blockly block definition
Blockly.Blocks[type].init = function() { this.jsonInit(def.blockdefinition); }
// Lua generator
luaGenerator.forBlock[type] = (block) => def.generator(block, luaGenerator);
```

---

## Lua Code Generation

The workspace generates Lua code on every change:

```javascript
// In component.js — called on workspace change events
generateLUAPreview() {
    const code = luaGenerator.workspaceToCode(this.workspace);
    // code is the complete Lua script
}
```

Generated Lua script structure (from `mh_init` and `mh_startthread` blocks):
```lua
hub.init(function()
    -- initialization block contents
end)

hub.startthread('Thread Name', blockId, stackSize, false, function()
    -- thread loop contents
end)
```

---

## BLOCKS.md Auto-Generation

`BLOCKS.md` is **automatically generated** — never edit it manually.

**Command:**
```bash
cd frontend
npm run generate-docs
```

**How it works** (`frontend/scripts/generate-block-docs-simple.js`):
1. Runs `vite build` to produce a renderer bundle
2. Launches **Puppeteer** (headless Chrome)
3. Loads `block-renderer.html` which runs Blockly in the browser
4. For each block: renders to SVG → screenshot to PNG at 2× DPI
5. Saves PNGs to `docs/blocks/{category}/{blocktype}.png`
6. Generates Markdown with: block image, tooltip description, type, message template, inputs table, fields table
7. Appends a statistics summary (block counts by type and category)

**Output structure:**
```
docs/blocks/
  control flow/mh_init.png
  lego©/lego_get_mode_dataset.png
  ...
BLOCKS.md   ← regenerated in full
```

**When to regenerate**: after adding, removing, or changing any block definition, tooltip, inputs, or fields. The `tooltip` field in `blockdefinition` becomes the description in BLOCKS.md — keep it informative.

---

## Stateful Algorithm Block Pattern

All stateful algorithm blocks in the **Algorithms** category follow an **explicit handle pattern**. This is a hard convention — never use `block.id` as an implicit state key.

### Pattern: Init + Compute (same as PID and DR)

A stateful algorithm requires **two** Blockly blocks:

1. **Init block** (`mh_alg_*_init.js`) — creates a filter/controller instance, returns a handle string. The user stores this in a variable.
2. **Compute block** (`mh_alg_*.js`) — takes the handle as first input, plus algorithm parameters.

### Firmware side (`libluaalg.cpp`)

```cpp
// State map keyed by handle string ("ma_0", "ma_1", ...)
static std::map<std::string, MyState> myStates;
static int myHandleCounter = 0;

// Init: creates instance, returns handle
int alg_init_my(lua_State* L) {
    std::string handle = "my_" + std::to_string(myHandleCounter++);
    myStates[handle] = MyState{};
    lua_pushstring(L, handle.c_str());
    return 1;
}

// Compute: looks up by handle
int alg_my(lua_State* L) {
    const char* handle = luaL_checkstring(L, 1);
    auto it = myStates.find(handle);
    if (it == myStates.end()) {
        WARN("alg_my: handle '%s' not found", handle);
        lua_pushnumber(L, 0.0);
        return 1;
    }
    // ... use it->second ...
}

// Clear all: called in alg_library() at init
int alg_clear_all_my(lua_State* L) {
    myStates.clear();
    myHandleCounter = 0;
    return 0;
}
```

Register all three in `alg_library()`, and call `alg_clear_all_my` at the top of `alg_library()`.

### Blockly side

**Init block** — no inputs, output is a handle value:
```javascript
generator: (block, generator) => {
    return [`alg.initMy()`, 0];
},
```

**Compute block** — HANDLE is first input, uses `variables_get` shadow:
```javascript
inputsForToolbox: {
    HANDLE: {
        shadow: { type: 'variables_get', fields: { VAR: { name: 'myFilter' } } },
    },
    // ... other inputs ...
},
generator: (block, generator) => {
    const handle = generator.valueToCode(block, 'HANDLE', 0) || '"my_0"';
    // ...
    return [`alg.my(${handle}, ...)`, 0];
},
```

### Registration

Both blocks must be added to all three registration files:
- `frontend/src/components/blockly/component.js`
- `frontend/scripts/block-renderer.js`
- `frontend/scripts/generate-block-docs-simple.js`

### Stateless algorithms (`alg.map`)

Stateless algorithms (no persistent state) need only one block, no handle, no init, no clearAll. Register only the single block file.

---

## Toolbox Toolbox Shadow Defaults (`inputsForToolbox`)

To pre-populate inputs in the toolbox with useful defaults, add `inputsForToolbox`:

```javascript
inputsForToolbox: {
    VALUE: {
        shadow: {
            type: 'math_number',
            fields: { NUM: 500 }
        }
    }
}
```

The `generateToolbox()` function reads this and adds `<shadow>` elements automatically.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall