菜单
Scaffold a v4 nanoTracker pedal whose UI is a custom HTML/JS surface (mixer fader strip, XY pad, oscilloscope, step sequencer, …). Builds on scaffold-pedal, adds the webview control + bidirectional bridge wiring + single-file HTML constraints so the iframe loads without errors.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Scaffold a nanoTracker control-source plugin — a MIDI emitter triggered by tracker rows. Step sequencers, virtual keyboards, drum machines, arpeggiators, chord triggers, LFO-to-CC. Plugins with manifest.type "control-source" emit TrackerMidiEvents over cables instead of producing audio.
Scaffold a nanoTracker control-source plugin — a MIDI emitter triggered by tracker rows. Step sequencers, virtual keyboards, drum machines, arpeggiators, chord triggers, LFO-to-CC. Plugins with manifest.type "control-source" emit TrackerMidiEvents over cables instead of producing audio.
Scaffold a nanoTracker control-source plugin — a MIDI emitter triggered by tracker rows. Step sequencers, virtual keyboards, drum machines, arpeggiators, chord triggers, LFO-to-CC. Plugins with manifest.type "control-source" emit TrackerMidiEvents over cables instead of producing audio.
Add a per-plugin theme colour override to a nanoTracker plugin (instrument or pedal) via ui.themeOverride. Eleven canonical colour keys cascade to the plugin's window chrome and (for webview controls) re-post to the iframe as a themeChange event. Composable add-on; the plugin manifest already exists.
Add a sandboxed webview UI control to an existing nanoTracker plugin (instrument OR pedal). Covers the single-file HTML constraint, the host↔iframe message bridge, optional iframe→host write channel, theme cascade, and the v3.5 audio route-back. Composable — assumes the rest of the plugin manifest already exists.
Walk a legacy v1–v3 nanoTracker FX plugin (mixer-module shape) through the v4 pedal rewrite. Covers the manifest changes, capability additions, port block, connection rewrites, and what host-side auto-migration does for end-users with the pre-v4 plugin already installed.
| name | scaffold-webview-pedal |
| description | Scaffold a v4 nanoTracker pedal whose UI is a custom HTML/JS surface (mixer fader strip, XY pad, oscilloscope, step sequencer, …). Builds on scaffold-pedal, adds the webview control + bidirectional bridge wiring + single-file HTML constraints so the iframe loads without errors. |
Use this when the user wants a pedal whose control surface can't be built from the host's standard knob / slider / XY-pad / envelope controls — a custom mixer fader strip, an interactive scope, a step sequencer, a piano-roll, a DOOM screen.
If a few knobs would do the job, use scaffold-pedal instead — the
host's auto-rendered knob grid is simpler and theme-aware out of
the box.
The webview is layered ON TOP of a pedal manifest. Do
scaffold-pedal for the audio side (ports, DSP, parameters), then
come back here for the UI surface.
"requires": ["pedal-v4", "portsV4", "graph", "webview-ui", "webview-writes"],
"ui": {
"layout": "flex",
"controls": [
{
"type": "webview",
"source": "web/ui.html",
"aspectRatio": "4/3",
"acceptsParamWrites": true
}
]
}
Per-control accept flags (acceptsParamWrites, acceptsPresetWrites,
acceptsNotes, acceptsHostCommands) gate which iframe → host
message classes the bridge will accept. Only declare what you use —
the validator catches the mismatch with requires[].
web/ui.html MUST be a single self-contained file:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
/* Theme-aware: pick up host CSS vars cascaded through themeChange */
body {
margin: 0;
background: var(--color-bg, #111);
color: var(--color-text, #ddd);
font: 11px "Kode Mono", monospace;
}
/* ... your styles ... */
</style>
</head>
<body>
<!-- your UI markup -->
<script>
(function(){
// Ready handshake — flush the host's queued event stream
window.parent.postMessage({ type: "__nt_ready" }, "*");
// Send paramWrite messages when your UI changes a value
function setParam(key, value) {
window.parent.postMessage({ type: "paramWrite", key, value }, "*");
}
// Receive events from the host
window.addEventListener("message", (e) => {
const ev = e.data;
if (!ev || typeof ev !== "object") return;
switch (ev.type) {
case "themeChange":
// Re-apply the host's theme palette as CSS custom properties
for (const [k, v] of Object.entries(ev.theme)) {
const cssVar = "--color-" + k.replace(/[A-Z]/g, m => "-" + m.toLowerCase());
document.documentElement.style.setProperty(cssVar, v);
}
break;
case "param":
// Host -> iframe param update (knob driven elsewhere, automation, etc)
// Update your UI to match.
break;
case "presetList":
// Factory preset catalogue (v4) — render a preset browser
break;
case "noteOn":
case "noteOff":
case "trackerEffect":
// Tracker activity for visualisers
break;
case "__nt_error":
console.warn("[plugin]", ev.where, ev.message);
break;
}
});
})();
</script>
</body>
</html>
The loader REJECTS webview HTML that references sibling assets:
<script src="./bundle.js"><link rel="stylesheet" href="style.css">import "./util.js" inside an inline scriptnew Worker("worker.js") (use a blob URL instead)fetch("./data.bin") (base64-inline as a const)Allowed: inline <script> / <style>, data: URIs, blob: URLs
created at runtime, https:// URLs, fragment anchors,
javascript: URLs.
For React / Svelte / Vue projects, use vite-plugin-singlefile. For
pure JS, esbuild --bundle --minify + manual inline. For binary
assets, base64 the bytes:
const MY_WASM = "AGFzbQEAAAAB..."; // base64
const bytes = Uint8Array.from(atob(MY_WASM), c => c.charCodeAt(0));
const { instance } = await WebAssembly.instantiate(bytes, imports);
"requires": ["pedal-v4", "portsV4", "graph", "webview-ui", "webview-writes", "themeOverride"],
"ui": {
"themeOverride": {
"primary": "#ff7a00",
"bg": "#140800"
},
"controls": [
{ "type": "webview", "source": "web/ui.html", "acceptsParamWrites": true }
]
}
The override cascades to the pedal window chrome AND is re-posted to
the iframe as a themeChange event after the ready handshake — your
iframe stays in sync.
If your iframe generates its own audio (e.g. a JS synth or a WASM emulator like the DOOM example), route it back into the tracker's output chain instead of the iframe's own AudioContext:
{
"type": "webview",
"source": "web/ui.html",
"acceptsAudioFrames": true
}
Then in the iframe, after receiving __nt_audioInit:
window.parent.postMessage({
type: "__nt_audio",
left: /* Float32Array */,
right: /* Float32Array, optional */
}, "*");
See docs/12-webview-audio.md for
the protocol.
node tools/ntvalidate.mjs <plugin-dir>
node tools/ntpack.mjs <plugin-dir> --out <name>.ntsfx
ntvalidate runs the single-file scan on your HTML and catches
sibling-asset references at pack time.
acceptsParamWrites: true —
the host validator drops the message. Set both the per-control
flag AND the top-level webview-writes capability.__nt_ready handshake — the host queues
events until ready; if your script never sends ready, events flush
on the iframe's load event (works but is later than ideal).allow-scripts allow-same-origin, but the
src is a blob: URL with an opaque origin). It can't reach the
parent — by design.<script src> — single-file constraint, see step
4. Inline everything.paramWrite for a non-existent parameter — host
drops with __nt_error back. Listen for __nt_error during
development to catch typos fast.var(--color-...)
— the iframe loses theme cascade and looks broken under
user-applied themes.node tools/ntvalidate.mjs <plugin-dir> — single-file check
passesnode tools/ntpack.mjs <plugin-dir> --out <name>.ntsfx succeeds__nt_error if it doesn't)themeChange event../../docs/09-webview.md — webview
control + bidirectional bridge full reference../../docs/10-wasm-in-webview.md
— DOOM-running-inside-a-plugin walkthrough../../docs/12-webview-audio.md
— acceptsAudioFrames protocol../../docs/reference/event-bus.md
— every host → iframe event../../examples/v40-mixer-pedal/web/ui.html
— production-quality fader strip with paramWrite + theme
cascade../../templates/webview/ — minimal
starter