function definePlugin<const S extends SettingsSchema>(plugin: VrcnextPlugin<S>): VrcnextPlugin<S>;

interface VrcnextPlugin<S> {
  readonly id: PluginId;               // must equal "id" in plugin.json
  readonly settings?: S;
  activate(ctx: PluginContext<S>): void | Promise<void>;
  deactivate?(): void | Promise<void>;
}

type Permission = 'host:events' | 'host:actions' | 'host:intercept' | 'network' | 'notifications'
  | 'native' | 'osc' | 'gamelog' | 'vrchat' | 'context-menu' | 'routes' | 'clipboard';
type PermissionTone = 'low' | 'medium' | 'high';
interface PermissionInfo { readonly description: string; readonly tone: PermissionTone }

const PERMISSIONS: Readonly<Record<Permission, PermissionInfo>>;
const PERMISSION_NAMES: readonly Permission[];
function isPermission(value: unknown): value is Permission;
function permissionInfo(permission: Permission): PermissionInfo;

class PermissionError extends Error {
  readonly permission: Permission;
  readonly target: string | undefined;   // host, action, event or service/method; undefined for a category
}

interface PermissionsApi {
  has(permission: Permission): boolean;              // cheap; safe per event
  request(permission: Permission): Promise<boolean>; // optionalPermissions only; rejects otherwise
}

const MANIFEST_FILENAME = 'plugin.json';
const MANIFEST_LIMITS = { descriptionChars: 200, tags: 8 };
const PLUGIN_TAGS: readonly string[];                 // suggested tags; any string is accepted
const PLUGIN_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,39}$/;

type PluginId;                                        // branded string
function isPluginId(value: string): value is PluginId;
function parsePluginId(value: string): PluginId | undefined;

interface PluginSummary {
  readonly id: PluginId; readonly name: string; readonly version: string;
  readonly description: string; readonly tags: readonly PluginTag[];
  readonly permissions: readonly Permission[];
  readonly optionalPermissions: readonly Permission[];
  readonly actions: readonly string[]; readonly events: readonly string[];
  readonly hosts: readonly string[];
}
interface PluginManifest extends PluginSummary {
  readonly apiVersion: string; readonly author?: string; readonly homepage?: string;
  readonly dependencies?: readonly PluginId[];        // activation order
}
function parsePluginManifest(raw: unknown): ManifestParseResult;   // { manifest | undefined, errors }

type Version = readonly [major: number, minor: number, patch: number];
function parseVersion(text: string): Version | undefined;
function isVersion(text: string): boolean;
function compareVersions(a: Version, b: Version): -1 | 0 | 1;
function parseRange(text: string): ((version: Version) => boolean) | undefined;
function isRange(text: string): boolean;
function satisfies(version: string, range: string): boolean;   // malformed input never satisfies

type TimeInput = string | number | Date;
interface Timestamped { readonly timestamp: TimeInput }

function timeAgo(iso: string, now?: number): string;   // "just now", "3 minutes ago", "2 hours ago", "5 days ago"
function formatDuration(ms: number): string;           // "45 minutes", "3 hours", "5 days", "4 months", "2 years"
function newestFirst<T extends Timestamped>(items: readonly T[] | undefined): readonly T[];

interface SpokenLanguage {
  readonly tag: string;      // language_deu
  readonly label: string;    // Deutsch
  readonly flag?: string;    // 🇩🇪 — absent where no country stands for the language
}

const LANGUAGE_LABELS: Readonly<Record<string, string>>;
const LANGUAGE_FLAGS: Readonly<Record<string, string>>;

function spokenLanguages(tags: readonly string[] | undefined): readonly SpokenLanguage[];
function languageLabels(tags: readonly string[] | undefined): readonly string[];
function languageFlags(tags: readonly string[] | undefined): readonly string[];
function languageFlag(tag: string): string | undefined;

type TemplateValue = string | number | boolean | null | undefined | TemplateValue[] | { [key: string]: TemplateValue };
function renderTemplate(template: string, values: Record<string, TemplateValue>, options?: { dropEmptyLines?: boolean }): string;
function validateTemplate(template: string): TemplateError | undefined;
function templatePlaceholders(template: string): readonly string[];
class TemplateError extends Error {}

type SettingSpec =
  | BooleanSetting | NumberSetting | StringSetting | ColorSetting | TimeSetting
  | SelectSetting<V> | MultiSelectSetting<V>
  | UserSetting | WorldSetting | AvatarSetting | GroupSetting | InstanceSetting   // EntitySetting
  | EmbedSetting | ObjectSetting<F> | ListSetting<I> | CustomSetting<T>;

interface SettingBase {
  readonly label: string;
  readonly description?: string;
  readonly hidden?: SettingPredicate;     // boolean, or (values) => boolean
  readonly disabled?: SettingPredicate;
}

interface SettingsStore<S> {
  readonly values: SettingsValues<S>;
  get<K extends keyof S>(key: K): SettingsValues<S>[K];
  set<K extends keyof S>(key: K, value: SettingsValues<S>[K]): Promise<void>;
  reset(): Promise<void>;
  onChange(listener: (values: SettingsValues<S>) => void): () => void;
}

interface CustomSettingHost<T> {
  readonly value: T;
  setValue(next: T): Promise<void>;          // rejects when `coerce` refuses
  setError(message: string | undefined): void;
  onChange(listener: (value: T) => void): () => void;
}

function renderEmbed(template: EmbedTemplate, values: TemplateValues,
  options?: { at?: Date; onError?: (error: Error) => void }): DiscordEmbed | undefined;
function discordWebhookPayload(embed: DiscordEmbed,
  options?: { username?: string; content?: string }): DiscordWebhookPayload;
function parseEmbedColor(text: string): number | undefined;

function isDiscordWebhookUrl(url: string): boolean;
function webhookFailure(status: number): string;
function postWebhook(options: {
  http: HttpApi; logger: Logger; url: string;
  payload: DiscordWebhookPayload; label?: string;
}): Promise<{ ok: boolean; status?: number; error?: string }>;

type DiscordTimeStyle = 't' | 'T' | 'd' | 'D' | 'f' | 'F' | 'R';

function discordCode(name: string): string;                                   // `Club Neon`
function discordTimestamp(at: TimeInput, style?: DiscordTimeStyle): string;    // <t:1790510400:R>

interface VrchatApi {
  self(): VrcSelf | undefined;                                          // synchronous, and the fullest object here

  friends(o?: VrcLookupOptions): Promise<readonly VrcUserSummary[]>;
  favoriteFriends(o?): Promise<readonly VrcUserSummary[]>;
  favoriteFriendGroups(o?): Promise<readonly VrcFavoriteGroup[]>;       // { name, displayName, userIds, users }
  moderationCounts(o?): Promise<VrcModerationCounts>;                   // { blocked, muted, hiddenAvatar, interactOff, muteChat }
  recentPlayers(o?): Promise<readonly VrcUserSummary[]>;
  favoriteWorlds(o?): Promise<readonly VrcWorldSummary[]>;
  recentWorlds(o?): Promise<readonly VrcWorldSummary[]>;
  ownAvatars(o?): Promise<readonly VrcAvatarSummary[]>;
  favoriteAvatars(o?): Promise<readonly VrcAvatarSummary[]>;
  recentAvatars(o?): Promise<readonly VrcAvatarSummary[]>;
  myGroups(o?): Promise<readonly VrcGroupSummary[]>;
  currentInstance(o?): Promise<VrcInstance | undefined>;
  friendInstances(o?): Promise<readonly VrcFriendInstance[]>;

  user(id: string, o?): Promise<VrcUser | undefined>;
  userBasic(id: string, o?): Promise<VrcUserSummary | undefined>;
  userGroups(id: string, o?): Promise<readonly VrcGroupSummary[]>;
  userTimeline(id: string, o?): Promise<readonly VrcTimelineEvent[]>;
  instanceAvatar(userId: string, o?): Promise<{ avatarId: string; avatarName: string } | undefined>;
  avatar(id: string, o?): Promise<VrcAvatar | undefined>;
  world(id: string, o?): Promise<VrcWorld | undefined>;
  group(id: string, o?): Promise<VrcGroup | undefined>;

  searchUsers(query: string, o?: VrcSearchOptions): Promise<VrcSearchPage<VrcUserSummary>>;
  searchWorlds(query: string, o?: VrcSearchOptions & { sort?: string }): Promise<VrcSearchPage<VrcWorldSummary>>;
  searchGroups(query: string, o?): Promise<VrcSearchPage<VrcGroupSummary>>;
  searchAvatars(query: string, o?): Promise<VrcSearchPage<VrcAvatarSummary>>;

  originalImageUrl(subject: ImageSubject, o?): Promise<string>;         // '' when VRCNext never cached it
}

type ImageSubject =
  | { kind: 'user';   id: string; variant?: 'avatar' | 'pfp' | 'banner' }
  | { kind: 'avatar'; id: string }
  | { kind: 'group';  id: string; variant?: 'icon' | 'banner' }
  | { kind: 'world';  id: string };

interface VrcLookupOptions { readonly cached?: boolean; readonly signal?: AbortSignal }
interface VrcSearchOptions { readonly offset?: number; readonly signal?: AbortSignal }

const fromLookup = publicImageUrl(avatar?.thumbnailImageUrl);
const url = fromLookup !== ''
  ? fromLookup                                                    // VRCNext fetched it anyway
  : await ctx.vrchat.originalImageUrl({ kind: 'avatar', id });     // one lookup in VRCNext's database

function parseLocation(location: string): ParsedLocation;
function isGroupInstance(type: string): boolean;
function instanceTypeLabel(type: string): string;

interface ParsedLocation {
  readonly worldId: string;      // '' when the location is not an instance
  readonly instanceId: string;
  readonly key: string;          // 'wrld_…:12345' — identifies the instance across visits
  readonly instanceType: InstanceType | '';
  readonly groupId: string;      // group instances
  readonly ownerId: string;      // friends / friends+ / hidden / private instances
  readonly region: string;
}

interface EventBus {
  on<T extends string>(type: T, listener: EventListener<T>): () => void;
  once<T extends string>(type: T, listener: EventListener<T>): () => void;
  onAny(listener: (envelope: HostEnvelope) => void): () => void;   // needs "*"; never receives vrcPrefillLogin
  next<T extends string>(type: T, signal?: AbortSignal): Promise<EventPayload<T>>;
}

interface Bridge {
  send(action: ActionName, args?: ActionArgs): void;
  request<T extends string>(action: ActionName, args: ActionArgs | undefined,
    options: RequestOptions & { readonly expect: T }): Promise<EventPayload<T>>;
  interceptOutbound(fn: (action: ActionName, raw: string) => boolean | undefined): () => void;
}
interface RequestOptions { readonly expect: string; readonly timeoutMs?: number; readonly signal?: AbortSignal }

interface HttpApi {
  /** The only fetch a plugin has. Asks about each host once; carries the plugin's abort signal. */
  fetch(url: string | URL, init?: RequestInit): Promise<Response>;
}
interface ClipboardApi {
  writeText(text: string): Promise<void>;
  readText(): Promise<string>;
}

interface UiApi {
  addNavTab(options: NavTabOptions): PanelHandle;
  addDashboardCard(options: DashboardCardOptions): PanelHandle;
  addSettingsCard(options: SettingsCardOptions): PanelHandle;   // options.section files it under your own section
  addSettingsSection(options: SettingsSectionOptions): SettingsSectionHandle;
  addSettingsDivider(): PanelHandle;
  addSidebarGroup(options: SidebarGroupOptions): PanelHandle;
  injectCss(css: string): PanelHandle;
  toast(options: ToastOptions): void;
  pickEntity(options: EntityPickOptions): Promise<readonly string[] | undefined>;   // the settings picker, on demand
  readonly kit: UiKit;
  createPanelLayout(): HTMLElement;
  createCard(title: string, icon: IconName): HTMLElement;
  createToggleRow(label: string, checked: boolean, onChange: (next: boolean) => void): HTMLElement;
}

interface PanelHandle extends Disposable {
  readonly element: HTMLElement;
  readonly visible: boolean;           // is the user looking at this panel?
}
interface NavTabOptions {
  readonly label: string;
  readonly icon: IconName;
  render(container: HTMLElement): void | Promise<void>;   // once, lazily, on first open
  readonly group?: string;
  onVisibility?(visible: boolean): void;                  // every switch, including to VRCNext's own tabs
}
interface SettingsSectionHandle extends PanelHandle {
  readonly sectionId: string;          // the data-section VRCNext switches on: "<plugin id>.<id>"
  readonly active: boolean;
  attach(block: HTMLElement): void;    // a card or container; removed with the section
  open(block?: HTMLElement): void;     // Settings tab → this section, scrolled to block
}
interface SidebarShortcut { id: string; label: string; icon: IconName; activate(): void }

type UiChild = Node | string | false | null | undefined;   // falsy children are dropped
type UiBadgeTone = 'ok' | 'warn' | 'err' | 'accent' | 'cyan' | 'neutral';

interface UiKit {
  layout(...children: readonly UiChild[]): HTMLElement;
  grid(children: readonly UiChild[], options?: { min?: number }): HTMLElement;
  pair(first: UiChild, second: UiChild): HTMLElement;
  card(options: { title?: string; icon?: IconName; children?: readonly UiChild[]; span?: number }): HTMLElement;
  statusCard(options: { tone: 'online' | 'warn' | 'offline'; label: string; action?: Node }): HTMLElement;
  section(label: string, children: readonly UiChild[]): DocumentFragment;

  row(options: { label: string; value?: UiChild; detail?: string }): HTMLElement;
  toggleRow(options: { label: string; value: boolean; onChange: (next: boolean) => void; detail?: string }): HTMLElement;
  buttonRow(...children: readonly UiChild[]): HTMLElement;
  button(options: { label: string; icon?: IconName; onClick: () => void; active?: boolean; disabled?: boolean; round?: boolean }): HTMLButtonElement;
  textField(options: { value: string; placeholder?: string; onCommit: (next: string) => void }): HTMLInputElement;
  textArea(options: { value: string; placeholder?: string; rows?: number; onCommit: (next: string) => void }): HTMLTextAreaElement;
  dropdown(options: { options: readonly { value: string; label: string }[]; selected: string; onChange: (next: string) => void }): HTMLSelectElement;
  slider(options: UiSliderOptions): HTMLElement;          // value readout, optional labelled markers
  chips(options: UiChipsOptions): HTMLElement;            // toggle buttons; the pressed ones are chosen
  timeField(options: UiTypedFieldOptions): HTMLInputElement;
  colorField(options: UiTypedFieldOptions): HTMLInputElement;
  listItem(options: UiListItemOptions): HTMLElement;      // VRCNext's compact profile row

  badge(tone: UiBadgeTone, text: string): HTMLElement;
  stat(options: { label: string; value: string; tone?: UiBadgeTone }): HTMLElement;
  description(text: string): HTMLElement;
  sectionLabel(text: string): HTMLElement;
  valueText(text: string): HTMLElement;
  emptyState(text: string): HTMLElement;

  setChildren(parent: Node, children: readonly UiChild[]): void;
}

interface NotificationsApi {
  toast(options: ToastOptions): void;
  notifToast(options: NotifToastOptions): void;
  desktop(options: DesktopNotifyOptions): void;   // tray + SteamVR overlay; Windows only
  readonly desktopAvailable: boolean;
  confirm(options: ConfirmOptions): Promise<boolean>;
}

interface ContextMenuApi {
  contribute(provider: ContextMenuProvider): () => void;
  contributeFor(selector: string, provider: ContextMenuProvider): () => void;
  open(x: number, y: number, entries: readonly ContextMenuEntry[]): void;
}

interface OscApi {
  readonly available: boolean;   // false on Linux — VRCNext filters every osc* action
  connect(): void;
  disconnect(): void;
  send(name: string, kind: 'bool', value: boolean): void;
  send(name: string, kind: 'int' | 'float', value: number): void;
  sendRaw(address: string, kind: 'bool', value: boolean): void;
  sendRaw(address: string, kind: 'int' | 'float', value: number): void;
  onParam(listener: (event: OscParamEvent) => void): () => void;
  onAvatarChange(listener: (event: OscAvatarChangeEvent) => void): () => void;
}

interface NativeApi {
  targets(): Promise<readonly NativeTarget[]>;
  notify(options: NativeNotifyOptions): Promise<NativeNotifyResult>;
  call(service: string, method: string, params?: unknown): Promise<unknown>;
}

interface NativeTarget {
  readonly name: string;                            // 'wayvr', 'freedesktop', …
  readonly description: string;
  readonly health: 'up' | 'unknown' | 'down';
  readonly honours: readonly string[];              // which fields this target actually uses
}

interface NativeNotifyOptions extends NativeNotifyFields {
  readonly title: string;                           // required
  readonly sinks?: readonly string[];               // omit for every target
  readonly overrides?: Readonly<Record<string, NativeNotifyOverride>>;
}

// Shared by a request and its per-target overrides.
interface NativeNotifyFields {
  readonly content?: string;
  readonly timeoutSecs?: number;
  readonly icon?: string;
  readonly useBase64Icon?: boolean;
  readonly sourceApp?: string;
  readonly sound?: boolean;
  readonly volume?: number;
  readonly audioPath?: string;
  readonly height?: number;      // VR overlays only
  readonly opacity?: number;     // VR overlays only
  readonly urgency?: NativeUrgency;  // 'low' | 'normal' | 'critical'; desktop daemons only
  readonly alwaysShow?: boolean; // VR overlays only
}

interface NativeNotifyResult {
  readonly ok: boolean;          // true if at least one target accepted
  readonly delivered: readonly string[];
  readonly failed: readonly { readonly sink: string; readonly error: string }[];
}

interface GameLogApi {
  on(listener: (entry: GameLogEntry) => void): () => void;
  onType(type: string, listener: (entry: GameLogEntry) => void): () => void;
  history(signal?: AbortSignal): Promise<readonly GameLogEntry[]>;
}

type SqlValue = string | number | boolean | null | { readonly blobBytes: number };
type SqlDatabase = 'vrcnext' | 'avatars';

interface SqlApi {
  query(database: SqlDatabase, sql: string, params?: readonly SqlValue[]): Promise<SqlResult>;
  rows(database: SqlDatabase, sql: string, params?: readonly SqlValue[]): Promise<readonly SqlRow[]>;
  value(database: SqlDatabase, sql: string, params?: readonly SqlValue[]): Promise<SqlValue | undefined>;
  databases(): Promise<readonly SqlDatabaseInfo[]>;
}

const meets = await ctx.sql.value(
  'vrcnext',
  'SELECT meet_again_count FROM user_tracking WHERE user_id = ?1',
  [userId],
);

interface RouterApi {
  readonly base: URL;
  route(method: string, pattern: string, handler: RouteHandler): () => void;
  get(pattern: string, handler: RouteHandler): () => void;
  post(pattern: string, handler: RouteHandler): () => void;
  fetch(input: string | URL, init?: RequestInit): Promise<Response>;
}

interface DeepLinkApi {
  on(listener: (event: DeepLinkEvent) => boolean | undefined): () => void;
  onPrefix(prefix: DeepLinkPrefix, listener: (event: DeepLinkEvent) => boolean | undefined): () => void;
}