Package Model

Package directory

An installed package has one stable directory identity:

com.example.package/
├── plugin.toml
└── dist/
    └── plugin.iife.js

plugin.toml declares the package identity and entry path. The JavaScript entry registers the public definition. If the entry is missing or fails the declared checksum, the package remains unavailable.

Root unit

plugin(id) creates the root unit. Its identifier should be stable and globally distinguishable, normally with reverse-domain notation.

plugin("com.example.package")
  .name("Example package")
  .version("0.1.0")
  .register();

Changing the identifier creates a different package from the user’s perspective. Preserve it across updates.

Members

A package may contain member units when one distribution provides several related operations. A member receives an identifier relative to its parent and may read parameters already defined by that parent.

plugin("com.example.language")
  .params({ amount: param.number({ default: 0 }) })
  .member("tone", (member) =>
    member.hooks({
      stage: "post_pitch",
      postPitch(ctx) {
        return ctx.f0;
      },
    }),
  )
  .register();

Use a member when the operation is meaningfully part of the same package and shares its release identity. Use another package when it should be installed, enabled, ordered, or versioned independently.

Roles and stages

Declaration	Condition	Result
language	The package defines pronunciation planning or finalization.	Its advertised languages become selectable per voice while the package is enabled.
hook with post_pitch	The package modifies a rendered F0 contour.	It joins the ordered post-pitch processor chain.
Import or export endpoint	The package declares a supported score format.	Registration is unavailable in the current release.

Registration

Call .register() once after the complete definition is assembled. If required identity, parameter, or operation data is invalid, registration fails and the package does not become available.