Skip to content

developable-components.md

Latest commit

 

History

History
272 lines (221 loc) · 7.93 KB

developable-components.md

File metadata and controls

272 lines (221 loc) · 7.93 KB
Raw

Developable Components

Purpose

What AI can create new components of, what requires human engineering, and how to make components reusable.

Component Development Levels

Level 1: AI-Generatable (Given Context)

These components can be generated by AI if given enough context. Human must verify correctness.

Component AI Needs AI Can Generate Human Must Verify
CodeBlock Language, code, explanation Syntax-highlighted code Code actually works
Quiz Question, correct answer, distractors Question + options Options are plausible
FillInBlank Text, blanks Text with blanks highlighted Blanks are appropriate
HexDump Binary data, field definitions Hex view with highlights Byte offsets correct
MemoryLayout Variables, types, addresses Stack/heap diagram Addresses correct
Flowchart Process steps, decisions SVG diagram Logic matches spec
ComparisonTable Features, options HTML table Facts correct
Glossary Terms, definitions Term list Definitions accurate
Definition Term, definition, source Term + definition block Definition accurate
KeyTakeaway Concepts, importance Bullet list Points are key
Timeline Events, dates, descriptions Chronological list Dates correct
SpecReference Spec, section, quote Citation block Quote matches spec

Verification method: Check each fact against source material.

Level 2: AI-Assisted (Needs Templates)

These components need human-created templates. AI fills in the content.

Component Template Needed AI Fills In Human Must Verify
DebuggingExercise Bug template, hint template Specific bugs, hints Bugs are realistic
CodeChallenge Test template, stub template Code, tests, solution Tests pass correctly
CodeCompletion Blank template Code with blanks, answers Blanks test understanding
Ordering Item template Steps, correct order Order is correct
Matching Pair template Items, correct pairs Pairs are meaningful
Hotspot Zone template Zones, correct areas Areas are accurate

Verification method: Run the exercise, check all paths work.

Level 3: Human-Engineered (Requires Custom Code)

These components require custom JavaScript engineering. AI cannot generate them.

Component Why Human Needed Engineering Effort
CodeEditor Complex state, syntax highlighting High (CodeMirror integration)
CodeExecution Sandboxed execution environment High (WASM or server)
Simulation Physics/logic engine High (custom engine)
InteractiveDemo Custom interaction logic Medium-High (per demo)
Console REPL environment Medium (readline, eval)
AnimatedDemo Animation framework Medium (CSS/JS animation)

Verification method: Full integration testing.

Reusability Principles

1. Self-Containment

Every component must work without external context:

GOOD:
@component("quiz")
var quiz = Quiz {
    question: "What does EI_CLASS mean?",
    options: [
        { text: "File class (32/64 bit)", correct: true },
        { text: "Endianness", correct: false }
    ],
    explanation: "EI_CLASS at offset 4 identifies..."
}

BAD:
@component("quiz")
var quiz = Quiz {
    question: "What does this field mean?",
    options: [...]  // Which field? Depends on context.
}

2. Context Independence

Components don't reference other components or the course:

GOOD:
@component("definition")
var def = Definition {
    term: "ELF",
    definition: "Executable and Linkable Format"
}

BAD:
@component("definition")
var def = Definition {
    term: "ELF",
    definition: "As we discussed in the previous section..."
}

3. Metadata Completeness

Every component must have:

@component("quiz")
@difficulty 2                    // Cognitive load: 1-5
@timeEstimate 30                 // Seconds to complete
@prerequisites ["bytes"]         // Required knowledge
@learningObjective "Identify EI_CLASS field"
@verificationStatus verified     // verified/unverified/disputed
@source "gABI v1.0, Section 4"  // Authority

4. Composability

Components compose into lessons, not the other way around:

Lesson
├── Paragraph (intro)
├── Definition (term)
├── CodeBlock (example)
├── HexDump (visual)
├── Quiz (check)
├── KeyTakeaway (summary)
└── FillInBlank (practice)

AI Generation Workflow

Step 1: Context Gathering

{
    "topic": "ELF Header",
    "concept": "EI_CLASS field",
    "source": "gABI v1.0, Section 4.1.1",
    "prerequisites": ["bytes", "binary", "file-layout"],
    "learningObjective": "Identify and explain the EI_CLASS field",
    "difficulty": 2,
    "existingComponents": ["paragraph-intro", "hex-dump-identification"]
}

Step 2: Generation

AI generates components in this order:

  1. Paragraph — introduction text
  2. Definition — key terms
  3. CodeBlock — code example
  4. HexDump — visual representation
  5. Quiz — knowledge check
  6. FillInBlank — practice
  7. KeyTakeaway — summary

Step 3: Verification

For each component:

1. Fact check
   - Does the code compile/run?
   - Are byte offsets correct?
   - Are definitions accurate?

2. Pedagogical check
   - Does this teach the concept?
   - Is the difficulty appropriate?
   - Are the distractors plausible?

3. Consistency check
   - Does it use the same terminology?
   - Does it match the source?
   - Does it build on prerequisites?

Step 4: Iteration

If verification fails:

1. Identify what's wrong
2. Gather more context (read source again)
3. Regenerate with better context
4. Re-verify
5. Repeat until correct

Component Registration

New component types must be registered:

{
    "type": "hex-dump",
    "version": "1.0.0",
    "description": "Binary data viewer with field highlighting",
    "category": "code",
    "difficulty": 2,
    "requiredFields": ["data"],
    "optionalFields": ["highlights", "baseAddress", "endian"],
    "htmlTemplate": "hex-dump.html",
    "jsClass": "HexDumpComponent",
    "cssClass": "hex-dump",
    "verificationMethod": "compare-to-reference",
    "aiGeneratable": true,
    "reusable": true
}

Component Library Structure

components/
├── content/                  # Information delivery
│   ├── paragraph/
│   ├── heading/
│   ├── callout/
│   ├── definition/
│   └── key-takeaway/
├── code/                     # Technical content
│   ├── code-block/
│   ├── code-callout/
│   ├── hex-dump/
│   ├── memory-layout/
│   └── file-tree/
├── interactive/              # Learner engagement
│   ├── quiz/
│   ├── fill-in-blank/
│   ├── drag-drop/
│   ├── ordering/
│   └── matching/
├── assessment/               # Evaluation
│   ├── multiple-choice/
│   ├── free-response/
│   ├── debugging-exercise/
│   └── code-challenge/
├── reference/                # Lookup
│   ├── glossary/
│   ├── cheat-sheet/
│   ├── api-reference/
│   └── spec-reference/
└── visualization/            # Visual learning
    ├── flowchart/
    ├── memory-diagram/
    ├── file-format-diagram/
    └── animated-demo/

Each component directory contains:

components/quiz/
├── README.md                 # Description, use cases
├── schema.json               # Data structure definition
├── template.html             # HTML template
├── style.css                 # Component styles
├── component.js              # JS class
├── examples/                 # Example instances
│   ├── basic.json
│   └── with-explanation.json
└── tests/                    # Verification tests
    ├── schema.test.js
    └── rendering.test.js