Chalk Integration

Plugins are first-class Chalk elements. Once imported, a plugin element uses exactly the same syntax as any built-in element and can be combined with parameter sliders, cue animations, and other detail-panel elements.

Importing a Plugin

Declare the plugin at the top of your Chalk file with the @plugin directive:

@plugin(src: plugins.internote.dev/particle-sim)

The src attribute is the plugin's registry URL. The element name is derived from the last path segment of the URL — here, particle-sim. You can then use particle-sim anywhere in the file as an element.

You can import multiple plugins in one file:

@plugin(src: plugins.internote.dev/particle-sim)
@plugin(src: plugins.internote.dev/circuit-builder)

Attribute Syntax

Plugin element attributes follow the same Chalk syntax as built-in elements. Use semicolons to separate attributes inline, or newlines in a multi-line block:

particle-sim(particles: 150; gravity: 2.5; loop: true; size: (600, 400))

particle-sim(
    particles: 150
    gravity: 2.5
    loop: true
    size: (600, 400)
)

Attribute types follow what the manifest declares:

• number — numeric literal: gravity: 2.5
• string — bare value: label: Click me
• boolean — true or false: loop: true
• dimensions — tuple: size: (600, 400)
• colour — colour name: colour: teal

The Chalk parser validates all attributes against the manifest schema and reports errors inline in the editor.

Body and Detail Blocks

Plugin elements support both a body block {} and a detail block []. These are semantic categories — the same distinction as anywhere else in Chalk. Body is the primary content; detail is the complementary or supporting content. A timeline plugin might use body for the date markers and detail for each date's image and explanation.

timeline{
    1969-07-20
    1986-01-28
    2003-02-01
}[
    event{ Apollo 11 lands on the Moon }(date: 1969-07-20; image: apollo.jpg)
    event{ Space Shuttle Challenger disaster }(date: 1986-01-28; image: challenger.jpg)
    event{ Space Shuttle Columbia disaster }(date: 2003-02-01; image: columbia.jpg)
](size: (700, 400))

Both blocks are passed to the plugin at load time as structured data — InitContext.body and InitContext.detail respectively. The plugin decides how to render them.

The child element types allowed in body and detail are declared in the manifest under chalk.childElements. Elements not in the whitelist are rejected by the Chalk parser. Other plugins can be referenced in the whitelist by their registry URL — see Manifest Reference for the full schema.

Body content also contributes to the element's content hash, which is the key used for interaction storage.

Placing Plugins in Scenes

Plugin elements go in the detail panel [] of a scene, the same position as diagram{} and parameter{} elements:

scene{
    Observe how particles settle into stable orbits when gravity is low.
}[
    particle-sim(particles: 80; gravity: 0.5; size: (600, 400))
]

Combining with Parameter Sliders

Number attributes can reference a parameter{} variable. When the educator places a parameter{} in the same detail panel and the student moves the slider, the runtime resolves the new value and sends it to the plugin.

scene{
    Use the sliders to explore how gravity and particle count affect the system.
}[
    parameter{
        Particle Count
    }(var: n; range: [10, 500]; step: 10; default: 100)

    parameter{
        Gravity
    }(var: g; range: [0.0, 10.0]; step: 0.5; default: 1.0)

    particle-sim(
        particles: n
        gravity: g
        size: (600, 400)
    )
]

Parameter variable names must be single lowercase letters — the same constraint that applies to all Chalk parameter variables. The plugin receives the resolved numeric value, not the variable name.

Combining with Cue Animations

Plugin elements support cue{} wrapping. The cue fades the plugin frame in or out at the specified time:

scene{
    The simulation begins after the introduction completes.
}[
    diagram{
        curve(expression: x^2; colour: blue)
    }(x domain: [-4, 4]; y domain: [-1, 10])

    cue{
        particle-sim(particles: 100; gravity: 1.0; size: (400, 300))
    }(in: 1500)
](autoplay: true)

The cue fade is applied to the plugin frame as a CSS transition — the plugin does not need to do anything special to support it. Additionally, the SDK delivers the full animation timeline state to your plugin (elapsed time, pause status, cut index), so your rendering can synchronise with the cue timing from inside. See SDK: Animation for details.

Cut-Based Scenes

In step-through scenes (where the student presses a forward arrow to advance through cuts), the SDK delivers the current cut index to your plugin. The educator's Chalk controls how many cuts there are; the plugin uses the index to choose what to display:

scene{
    Step through each phase of the simulation.
}[
    cue{
        particle-sim(particles: 10; gravity: 0.5; size: (600, 400))
    }

    cue{
        particle-sim(particles: 10; gravity: 0.5; size: (600, 400))
    }

    cue{
        particle-sim(particles: 10; gravity: 0.5; size: (600, 400))
    }
]

In this example, the plugin receives cutIndex: 0, cutIndex: 1, and cutIndex: 2 as the student steps forward. The plugin's animation.onState handler can switch internal state accordingly.

Version Pinning

By default, importing a plugin URL loads its latest approved version. To pin to a specific version:

@plugin(src: plugins.internote.dev/particle-sim@1.2.0)

Pinning is recommended for internotes that should remain stable over time, such as published courses or archived lesson materials.

Local Development URLs

During development, reference your local manifest by file path. The dev CLI prints the exact path to use when you run npm run dev:

@plugin(src: /Users/jackhgns/projects/my-plugin/manifest.json)