@meith/plugin-kit 0.21.2 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/plugin-kit",
-  "version": "0.21.2",
+  "version": "0.23.0",
   "description": "The SDK for writing a Meith plugin: typed manifests, hooks, routes, pages and migrations.",
   "license": "MIT",
   "repository": {
@@ -20,8 +20,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@meith/core": "^0.21.2",
-    "@meith/theme-kit": "^0.21.2"
+    "@meith/core": "^0.23.0",
+    "@meith/theme-kit": "^0.23.0"
   },
   "peerDependencies": {
     "react": "^19.2.0"

package/src/host.ts

@@ -2,7 +2,13 @@ import type { ReactNode } from 'react'
 
 import { HOOKS, type HookName } from './hooks'
 import type { HookContext, HookValue } from './payloads'
-import type { HookRegistration, PluginContribution, PluginDefinition } from './plugin'
+import type {
+  HookRegistration,
+  HookRuntime,
+  PluginContribution,
+  PluginDefinition,
+  PluginRuntimeContext,
+} from './plugin'
 import type { PluginRegion, PluginRegionContext } from './regions'
 
 export interface HostLogger {
@@ -17,10 +23,6 @@ export interface PluginFailure {
   readonly threshold: number
 }
 
-/**
- * Where a failure goes once the host has counted it. The host stays
- * synchronous and fire-and-forgets; whoever supplies this owns the write.
- */
 export interface PluginHealthSink {
   readonly failed: (failure: PluginFailure) => void
 }
@@ -30,6 +32,8 @@ export interface DurablyDisabledPlugin {
   readonly reason: string
 }
 
+export type PluginRuntimeProvider = (pluginKey: string) => Promise<PluginRuntimeContext>
+
 export interface PluginHostOptions {
   readonly plugins: readonly PluginDefinition[]
   readonly logger?: HostLogger | undefined
@@ -37,6 +41,7 @@ export interface PluginHostOptions {
   readonly slowCallMs?: number | undefined
   readonly now?: (() => number) | undefined
   readonly health?: PluginHealthSink | undefined
+  readonly runtime?: PluginRuntimeProvider | undefined
 }
 
 export interface PluginHealth {
@@ -52,7 +57,7 @@ export interface PluginHealth {
   readonly lastError: { readonly hook: string; readonly message: string } | null
 }
 
-type StoredHandler = (value: unknown, context: unknown) => unknown
+type StoredHandler = (value: unknown, context: unknown, runtime: HookRuntime) => unknown
 
 interface Entry {
   readonly pluginKey: string
@@ -86,6 +91,7 @@ export class PluginHost {
   readonly #slowCallMs: number
   readonly #now: () => number
   readonly #health: PluginHealthSink
+  readonly #runtime: PluginRuntimeProvider
 
   constructor(options: PluginHostOptions) {
     this.#logger = options.logger ?? { warn: () => {}, error: () => {} }
@@ -93,6 +99,15 @@ export class PluginHost {
     this.#slowCallMs = options.slowCallMs ?? 50
     this.#now = options.now ?? (() => performance.now())
     this.#health = options.health ?? { failed: () => {} }
+    this.#runtime =
+      options.runtime ??
+      ((pluginKey) =>
+        Promise.reject(
+          new Error(
+            `plugin "${pluginKey}": this host was built without a runtime provider, so a hook ` +
+              'handler cannot reach settings, data, grants, users or notifications here.',
+          ),
+        ))
 
     for (const plugin of options.plugins) {
       this.#stats.set(plugin.key, {
@@ -158,7 +173,9 @@ export class PluginHost {
     for (const entry of entries) {
       if (!this.#isEnabled(entry.pluginKey)) continue
 
-      const result = await this.#call(entry.pluginKey, name, () => entry.handler(current, context))
+      const result = await this.#call(entry.pluginKey, name, () =>
+        entry.handler(current, context, this.#runtimeFor(entry.pluginKey)),
+      )
 
       if (result.ok && result.value !== undefined) current = result.value as HookValue<K>
     }
@@ -175,14 +192,24 @@ export class PluginHost {
 
     for (const entry of entries) {
       if (!this.#isEnabled(entry.pluginKey)) continue
-      await this.#call(entry.pluginKey, name, () => entry.handler(value, context))
+      await this.#call(entry.pluginKey, name, () =>
+        entry.handler(value, context, this.#runtimeFor(entry.pluginKey)),
+      )
     }
   }
 
-  renderRegion(
+  #runtimeFor(pluginKey: string): HookRuntime {
+    let pending: Promise<PluginRuntimeContext> | null = null
+    return () => {
+      pending ??= this.#runtime(pluginKey)
+      return pending
+    }
+  }
+
+  async renderRegion(
     region: PluginRegion,
-    context: PluginRegionContext,
-  ): readonly { key: string; node: ReactNode }[] {
+    context: Omit<PluginRegionContext, 'runtime'>,
+  ): Promise<readonly { key: string; node: ReactNode }[]> {
     const entries = this.#contributions.get(region)
     if (entries === undefined) return []
 
@@ -192,7 +219,10 @@ export class PluginHost {
 
       const started = this.#now()
       try {
-        const node = entry.contribution.render(context)
+        const node = await entry.contribution.render({
+          ...context,
+          runtime: this.#runtimeFor(entry.pluginKey),
+        })
         this.#record(entry.pluginKey, region, this.#now() - started)
         if (node !== null && node !== undefined) nodes.push({ key: entry.pluginKey, node })
       } catch (error) {
@@ -234,11 +264,6 @@ export class PluginHost {
     }
   }
 
-  /**
-   * Reconcile against the durable record. The stored rows are the answer,
-   * not a hint: a plugin an operator has cleared comes back without a
-   * restart, and one another instance switched off is off here too.
-   */
   setDurablyDisabled(rows: readonly DurablyDisabledPlugin[]): void {
     const disabled = new Map(rows.map((row) => [row.key, row.reason]))
 

package/src/index.ts

@@ -17,6 +17,7 @@ export {
   type PluginHealthSink,
   PluginHost,
   type PluginHostOptions,
+  type PluginRuntimeProvider,
 } from './host'
 export {
   type PluginNavigationPlacement,
@@ -44,6 +45,7 @@ export {
   type FilterHandler,
   type HookHandler,
   type HookRegistration,
+  type HookRuntime,
   MAX_ROUTE_BODY_BYTES,
   type PluginAdminPage,
   type PluginAdminPageContext,
@@ -107,9 +109,11 @@ export {
   type PluginUsers,
   pluginNotificationKindSpecs,
   pluginNotify,
+  unavailableHookRuntime,
   unavailablePluginData,
   unavailablePluginGrants,
   unavailablePluginNotify,
+  unavailablePluginRuntime,
   unavailablePluginUsers,
 } from './runtime'
 export {

package/src/navigation.ts

@@ -9,7 +9,6 @@ export interface PluginNavigationPlacement {
   readonly key: string
   readonly href: string
   readonly audience: PluginNavigationAudience
-  /** The namespaced key of the sibling item this one sits under by default. */
   readonly parentKey: string | null
   readonly label: string
   readonly labelKey: string | null

package/src/plugin.ts

@@ -1,3 +1,5 @@
+export type { HookRuntime, PluginRuntimeContext } from './runtime'
+
 import type { ReactNode } from 'react'
 
 import type { Translator } from '@meith/theme-kit'
@@ -5,16 +7,18 @@ import type { Translator } from '@meith/theme-kit'
 import { type HOOKS, type HookName, isHookName } from './hooks'
 import type { HookContext, HookValue } from './payloads'
 import { isPluginRegion, type PluginRegion, type PluginRegionContext } from './regions'
-import type { PluginData, PluginGrants, PluginNotify, PluginUsers } from './runtime'
+import type { HookRuntime, PluginRuntimeContext } from './runtime'
 
 export type FilterHandler<K extends HookName> = (
   value: HookValue<K>,
   context: HookContext<K>,
+  runtime: HookRuntime,
 ) => HookValue<K> | Promise<HookValue<K>>
 
 export type EventHandler<K extends HookName> = (
   value: HookValue<K>,
   context: HookContext<K>,
+  runtime: HookRuntime,
 ) => void | Promise<void>
 
 export type HookHandler<K extends HookName> = (typeof HOOKS)[K]['kind'] extends 'filter'
@@ -74,7 +78,7 @@ export interface PluginAdminPage {
 export interface PluginContribution {
   readonly region: PluginRegion
   readonly priority?: number | undefined
-  readonly render: (context: PluginRegionContext) => ReactNode
+  readonly render: (context: PluginRegionContext) => ReactNode | Promise<ReactNode>
 }
 
 export interface PluginViewer {
@@ -153,44 +157,16 @@ type TranslationArgs = Parameters<Translator['t']>[1]
 
 export type PluginNavigationAudience = 'all' | 'guests' | 'members' | 'staff'
 
-/**
- * A board navigation entry a plugin asks for.
- *
- * It is a **request, not a placement**: the host writes it into the board's own
- * navigation table, where an operator renames, reorders, nests, scopes or hides
- * it like any other item. A plugin that appended to the header model instead
- * would put a link where no operator could reach it.
- */
 export interface PluginNavigationItem {
   readonly key: string
   readonly label: string
   readonly labelKey?: string | undefined
   readonly labelArgs?: TranslationArgs | undefined
-  /** A page path of this plugin's own — '' is its index page. */
   readonly path: string
   readonly audience?: PluginNavigationAudience | undefined
-  /**
-   * The `key` of another of this plugin's navigation items to sit under by
-   * default. The board's navigation is one level deep, so the item named here
-   * must itself be top-level. Like `audience`, it only seeds the row — the
-   * operator re-nests it like any other item.
-   */
   readonly under?: string | undefined
 }
 
-export interface PluginRuntimeContext {
-  readonly settings: Readonly<Record<string, string | number | boolean>>
-  readonly logger: {
-    readonly info: (message: string, detail?: Record<string, unknown>) => void
-    readonly warn: (message: string, detail?: Record<string, unknown>) => void
-    readonly error: (message: string, detail?: Record<string, unknown>) => void
-  }
-  readonly grants: PluginGrants
-  readonly data: PluginData
-  readonly users: PluginUsers
-  readonly notify: PluginNotify
-}
-
 export interface PluginNotificationKind {
   readonly key: string
   readonly title: string
@@ -231,12 +207,6 @@ export interface PluginDefinition {
   readonly onUninstall?: ((context: PluginRuntimeContext) => Promise<void> | void) | undefined
 }
 
-/**
- * The rule a plugin key (and, by marketplace-gen.mjs's own mirrored copy, a
- * marketplace listing key) has to satisfy. Exported so
- * scripts/marketplace-gen.test.ts can pin its own copy directly against
- * this one rather than trusting the two stay in sync by comment alone.
- */
 export const KEY_PATTERN = /^[a-z][a-z0-9-]{1,39}$/
 const SETTING_KEY_PATTERN = /^[a-z][a-z0-9_]{1,39}$/
 const MIGRATION_ID_PATTERN = /^\d{4}_[a-z0-9_]{1,60}$/

package/src/regions.ts

@@ -1,3 +1,5 @@
+import type { HookRuntime } from './runtime'
+
 export interface RegionSpec {
   readonly purpose: string
   readonly context: string
@@ -22,6 +24,12 @@ export const PLUGIN_REGIONS = {
     purpose: 'Below a post body, above its actions.',
     context: 'The viewer, the post id and the author id.',
   },
+  'thread.header': {
+    purpose:
+      'Above the first post of a thread, below its title. Runs once per thread page, ' +
+      'so unlike postbit.* it can afford to read from the plugin’s own tables.',
+    context: 'The viewer, the thread id and the thread author’s id.',
+  },
   'profile.panel': {
     purpose: 'A panel on a member’s profile, below the standard fields.',
     context: 'The viewer and the profile’s member id.',
@@ -45,4 +53,5 @@ export interface PluginRegionContext {
   readonly viewer: { readonly userId: number | null; readonly isGuest: boolean }
   readonly subjectId: number | null
   readonly authorId: number | null
+  readonly runtime: HookRuntime
 }

package/src/runtime.ts

@@ -246,3 +246,33 @@ export function pluginNotify(
     },
   }
 }
+
+export interface PluginRuntimeContext {
+  readonly settings: Readonly<Record<string, string | number | boolean>>
+  readonly logger: {
+    readonly info: (message: string, detail?: Record<string, unknown>) => void
+    readonly warn: (message: string, detail?: Record<string, unknown>) => void
+    readonly error: (message: string, detail?: Record<string, unknown>) => void
+  }
+  readonly grants: PluginGrants
+  readonly data: PluginData
+  readonly users: PluginUsers
+  readonly notify: PluginNotify
+}
+
+export type HookRuntime = () => Promise<PluginRuntimeContext>
+
+export function unavailablePluginRuntime(reason: string): PluginRuntimeContext {
+  return {
+    settings: {},
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+    grants: unavailablePluginGrants(reason),
+    data: unavailablePluginData(reason),
+    users: unavailablePluginUsers(reason),
+    notify: unavailablePluginNotify(reason),
+  }
+}
+
+export function unavailableHookRuntime(reason: string): HookRuntime {
+  return () => Promise.resolve(unavailablePluginRuntime(reason))
+}

package/src/settings.ts

@@ -47,11 +47,6 @@ export function parsePluginSetting(setting: PluginSetting, raw: string): PluginS
   return raw
 }
 
-/**
- * Matches a candidate select value against a setting's declared options —
- * trimmed and case-insensitively — and returns the *option's own* casing.
- * See "Settings" in docs/plugin-api.md.
- */
 function matchSelectOption(
   options: readonly { readonly value: string }[],
   candidate: PluginSettingValue | null,