@soundbase/plugin-contract

The compatibility boundary between SoundBase and a plugin process: the manifest schema (spec/soundbase-plugin.schema.json, the normative artifact for plugin authors), the OpenAPI 3.1 documents for the core plugin API (spec/core.openapi.yaml) and its modules — SpectrumAnalyzer (spec/spectrum-analyzer.openapi.yaml), ChannelMonitoring (spec/channel-monitoring.openapi.yaml) and PropertyControl (spec/property-control.openapi.yaml) — the core state-key table (spec/state-keys.json), and the shared constants and normalisers both sides depend on. It has no opinion about how a plugin is implemented — the host, the plugin shell and third-party tooling all validate against the same schema.

import { validateManifest, HANDSHAKE_PREFIX } from '@soundbase/plugin-contract';

const result = validateManifest(JSON.parse(await readFile(path, 'utf8')));
if (!result.ok) throw new Error(result.errors.join('; '));
console.log(result.manifest.id, HANDSHAKE_PREFIX);

validateManifest is a zod mirror of the JSON schema; a test in this package runs every manifest fixture through both and asserts identical verdicts. Unknown properties are tolerated everywhere, so a manifest written for a newer host still loads on an older one.

State patches and layouts

ChannelMonitoring plugins push device state as SoundBase's own patch envelope. createStatePatch(manifest, key, value, operation?) derives the patch's scope, operation and entity kind — from spec/state-keys.json for a core key, from the manifest's stateKeys for an extension key — and throws on anything else, so a bad emission fails in the plugin rather than being dropped by the host. normalizeLayout(layout) is the matching normaliser for a product's rendering layout. The shell runs both before emitting and the host runs both before reducing, the way normalizeWarnings is run today. spec/state-keys.json and LAYOUT_METRICS are the host's own tables, so a patch or layout this package accepts is one the host accepts.