Manifest and frontend contract¶

Yukon validates every manifest before returning it to a user and stages frontend registrations until activate(context) succeeds.

Manifest fields¶

Field	Contract
`id`	3–64 lowercase letters, digits, or underscores; starts with a letter.
`title`	Short customer-facing product name.
`version`	Valid semantic application version.
`api_version`	Use `"2"` for new work. API `"1"` remains accepted.
`description`	Plain-language purpose shown in settings.
`publisher`	Reviewed legal or trading name.
`maturity`	`stable`, `beta`, or `experimental`; omitted means stable.
`entrypoint`	Same-origin `.js` or `.mjs` file below `/assets`.
`required_roles`	Roles allowed to discover the frontend.
`navigation`	Ordered, namespaced destinations owned by the extension.

An empty required_roles list makes the frontend discoverable to every role. Declare explicit roles unless universal discovery is intentional. Role filtering controls discovery only; it never replaces server permissions.

Own one route namespace¶

A third-party ID owns the matching dashed route prefix. For example, acme_inventory owns /acme-inventory and paths beneath it. Route names must begin with the extension ID, such as acme_inventory.home.

Navigation order is an integer from 0 through 1000. A destination can use the workspace or modules section and may contain one level of children. Keep navigation shallow and task-oriented.

Load only same-origin code¶

Serve the entrypoint below /assets.
Include the application version in the URL for clear cache behavior.
Do not use traversal or load executable code from a CDN, tenant setting, or provider URL.
Export one repeat-safe activate(context) function.
Register routes before activation resolves.

If activation fails, Yukon discards the staged registrations so the core shell can continue to boot.

Use the host surface¶

Use context.ui instead of loading a second Vue runtime for a no-build module. Use context.navigate(path) for same-origin Yukon navigation and context.api.call() for the extension's own whitelisted methods or an individually documented Yukon method.

Feature-detect form controllers:

class ContactController {
  onLoad(form) {
    // Use only the documented form handle to adapt the page.
  }
}

export function activate(context) {
  if (context.forms) {
    context.forms.register('Contact', ContactController)
  }
}

Do not treat types that are present in an SDK declaration as proof that a host surface is available. Feature detection and the compatibility matrix are the runtime contract.

Extension pages must preserve the Yukon shell and provide loading, empty, error, permission-denied, keyboard, focus, narrow-screen, and retry states.