@zhin.js/plugin-runtime 1.1.7 → 1.1.9

package/lib/admission.d.ts

@@ -7,6 +7,8 @@ export declare class GenerationAdmissionGate {
     constructor();
     get active(): boolean;
     acquire(): (() => void) | undefined;
+    /** Observe the first commit which publishes this generation. */
+    onActivate(listener: () => void): () => void;
     /**
      * Observe retirement of the generation that owns this gate. The callback is
      * synchronous and must not fail; it is intended for closing process-owned
@@ -19,6 +21,7 @@ export declare function createGenerationAdmissionGate(): GenerationAdmissionGate
 /** Resource hook used by CapabilityContext to bind an ingress dependency. */
 export declare const generationAdmissionBinder: unique symbol;
 export interface GenerationAdmissionBindable<T> {
+    /** @internal Runtime lifecycle wiring; never called by plugin authors. */
     [generationAdmissionBinder](gate: GenerationAdmissionGate): T;
 }
 /** Snapshot value hook used to declare lifecycle-owned ingress gates. */

package/lib/admission.js

@@ -6,6 +6,7 @@
 export class GenerationAdmissionGate {
     constructor() {
         admissionState.set(this, { active: false });
+        admissionActivationListeners.set(this, new Set());
         admissionDeactivationListeners.set(this, new Set());
     }
     get active() {
@@ -15,6 +16,18 @@ export class GenerationAdmissionGate {
         const state = admissionState.get(this);
         return state?.active ? state.acquire?.() : undefined;
     }
+    /** Observe the first commit which publishes this generation. */
+    onActivate(listener) {
+        const listeners = admissionActivationListeners.get(this);
+        if (!listeners)
+            throw new Error('Unknown generation admission gate');
+        if (this.active) {
+            listener();
+            return () => undefined;
+        }
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    }
     /**
      * Observe retirement of the generation that owns this gate. The callback is
      * synchronous and must not fail; it is intended for closing process-owned
@@ -50,6 +63,7 @@ export class GenerationAdmissionGate {
 }
 const admissionState = new WeakMap();
 const admissionOwners = new WeakMap();
+const admissionActivationListeners = new WeakMap();
 const admissionDeactivationListeners = new WeakMap();
 export function createGenerationAdmissionGate() {
     return new GenerationAdmissionGate();
@@ -111,6 +125,17 @@ export function replaceGenerationAdmissions(previous, next, owner, acquireNext)
     }
     for (const gate of next) {
         admissionState.set(gate, { active: true, acquire: acquireNext });
+        const listeners = admissionActivationListeners.get(gate);
+        for (const listener of listeners ?? []) {
+            try {
+                listener();
+            }
+            catch {
+                // Admission publication is an infallible pointer switch. Buffered
+                // ingress reports through its own dispatch path.
+            }
+        }
+        listeners?.clear();
     }
 }
 function assertClaimableAdmission(gate, owner) {

package/lib/database-host.d.ts

@@ -128,6 +128,7 @@ export declare function unwrapPluginDatabaseHost(host: DatabaseHost | PluginData
  * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
  * facade cannot accidentally enumerate a descendant's tables.
  */
+/** @public Plugin-facing database facade bound to the current owner. */
 export declare const databaseHostToken: import("./token.js").Token<PluginDatabaseHost>;
 /** Root-only process host for CLI composition and Console administration. */
 export declare const databaseRootHostToken: import("./token.js").Token<DatabaseHost>;

package/lib/database-host.js

@@ -66,6 +66,7 @@ function assertLogicalResourceName(name) {
  * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
  * facade cannot accidentally enumerate a descendant's tables.
  */
+/** @public Plugin-facing database facade bound to the current owner. */
 export const databaseHostToken = createToken('zhin.database.host', 'Plugin Runtime scoped database host');
 /** Root-only process host for CLI composition and Console administration. */
 export const databaseRootHostToken = createToken('zhin.database.root-host', 'Plugin Runtime root database host');

package/lib/html-renderer.d.ts

@@ -1,10 +1,11 @@
 export interface HtmlRenderOptions {
     readonly width?: number;
+    /** 兼容旧调用方；当前实现传 `svg` 也会降级为 png。 */
     readonly format?: 'png' | 'svg';
     readonly backgroundColor?: string;
 }
 export interface HtmlRenderResult {
-    /** PNG 时为 Buffer/Uint8Array，SVG 时为 string。 */
+    /** 当前实现恒为 png：Buffer/Uint8Array。 */
     readonly data: unknown;
     readonly format: 'png' | 'svg';
     readonly width: number;

package/lib/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Generation-owned plugin definitions, capability tokens, and Host resources.
+ * @module @zhin.js/plugin-runtime
+ */
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';

package/lib/index.js

@@ -1,3 +1,7 @@
+/**
+ * Generation-owned plugin definitions, capability tokens, and Host resources.
+ * @module @zhin.js/plugin-runtime
+ */
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';

package/lib/outbound-host.d.ts

@@ -42,6 +42,22 @@ export interface OutboundRecallInput {
     readonly endpointKey: string;
     readonly message: OutboundMessage;
 }
+export type OutboundEndpointOperation = 'recall' | 'edit' | 'reaction' | 'typing';
+export interface OutboundEndpointInput {
+    readonly adapter: string;
+    readonly endpointKey: string;
+}
+export interface OutboundEndpointCapabilities {
+    readonly operations: readonly OutboundEndpointOperation[];
+}
+export interface OutboundEditInput extends OutboundEndpointInput {
+    readonly message: OutboundMessage;
+    readonly content: unknown;
+}
+export interface OutboundTypingInput extends OutboundEndpointInput {
+    readonly conversation: OutboundMessage['conversation'];
+    readonly active?: boolean;
+}
 /** Structured message identity; structurally compatible with IM MessageRef. */
 export interface OutboundMessage {
     readonly conversation: OutboundConversation & Readonly<{
@@ -53,6 +69,10 @@ export interface OutboundMessage {
     readonly id: string;
 }
 export interface OutboundHost {
+    /** Runs related operations against one IM Runtime snapshot captured at ingress. */
+    runWithView?<T>(operation: () => Promise<T>): Promise<T>;
+    /** Exact operations declared by one live Endpoint. */
+    capabilities?(input: OutboundEndpointInput): OutboundEndpointCapabilities | undefined;
     /** Returns platform message id when available (activity-feedback needs it). */
     send(input: OutboundSendInput): Promise<string | null>;
     /** Optional: platform message reactions (icqq group emoji, etc.). */
@@ -60,5 +80,10 @@ export interface OutboundHost {
     removeReaction?(input: OutboundRemoveReactionInput): Promise<void>;
     /** Optional: recall/delete a status message (activity-feedback autoRemove). */
     recall?(input: OutboundRecallInput): Promise<void>;
+    /** Optional: update a previously sent status message. */
+    edit?(input: OutboundEditInput): Promise<string | null>;
+    /** Optional: toggle the platform-native typing indicator. */
+    typing?(input: OutboundTypingInput): Promise<void>;
 }
+/** @public Plugin-facing cross-platform outbound messaging Host. */
 export declare const outboundHostToken: import("./token.js").Token<OutboundHost>;

package/lib/outbound-host.js

@@ -1,2 +1,3 @@
 import { createToken } from './token.js';
+/** @public Plugin-facing cross-platform outbound messaging Host. */
 export const outboundHostToken = createToken('zhin.outbound.host', 'Plugin Runtime outbound push host');

package/lib/plugin.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Canonical plugin definition consumed from `zhin.js`.
+ * @module zhin.js
+ */
 import type { Dispose, DisposeStack } from './dispose.js';
 import type { GenerationHandoffRegistry } from './handoff.js';
 import type { FeatureId, PluginId } from './identity.js';
@@ -27,6 +31,7 @@ export interface PluginSetupContext<TConfig = unknown> {
     /**
      * Registers an in-memory definition through the same validation and
      * projection transaction used by convention-discovered capabilities.
+     * @internal Runtime bridge for feature installers; plugin authors use convention files.
      */
     addFeature<TDefinition>(feature: FeatureId | string, localName: string, definition: TDefinition): void;
 }
@@ -36,4 +41,25 @@ export interface PluginDefinition<TConfig = unknown> {
     readonly requires?: readonly Token<unknown>[];
     setup?(context: PluginSetupContext<TConfig>): void | Dispose | Promise<void | Dispose>;
 }
+/**
+ * Define the canonical `plugin.ts` entry point.
+ * Setup runs against one candidate generation and may return its disposer.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { definePlugin } from 'zhin.js';
+ *
+ * // plugin.ts
+ * export default definePlugin({
+ *   name: 'hello',
+ * });
+ * ```
+ *
+ * Put capabilities in convention files such as `commands/hello.ts`, each with
+ * one default export.
+ */
 export declare function definePlugin<TConfig = unknown>(definition: PluginDefinition<TConfig>): Readonly<PluginDefinition<TConfig>>;
+export { databaseHostToken, type DatabaseHostConsole, type DatabaseHostModel, type DatabaseHostSelection, type DatabaseHostSelectResult, type DatabaseHostTable, type DatabaseHostType, type PluginDatabaseHost, } from './database-host.js';
+export { outboundHostToken, type OutboundConversation, type OutboundEditInput, type OutboundEndpointCapabilities, type OutboundEndpointInput, type OutboundEndpointOperation, type OutboundHost, type OutboundMessage, type OutboundReactionInput, type OutboundRecallInput, type OutboundRemoveReactionInput, type OutboundSendInput, type OutboundTypingInput, } from './outbound-host.js';
+export { scheduleHostToken, type PluginScheduleHost, type ScheduleJobRegistration, } from './schedule-host.js';

package/lib/plugin.js

@@ -1,4 +1,22 @@
 const pluginNamePattern = /^[a-z][a-z0-9-]*$/;
+/**
+ * Define the canonical `plugin.ts` entry point.
+ * Setup runs against one candidate generation and may return its disposer.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { definePlugin } from 'zhin.js';
+ *
+ * // plugin.ts
+ * export default definePlugin({
+ *   name: 'hello',
+ * });
+ * ```
+ *
+ * Put capabilities in convention files such as `commands/hello.ts`, each with
+ * one default export.
+ */
 export function definePlugin(definition) {
     if (!pluginNamePattern.test(definition.name)) {
         throw new TypeError(`Invalid plugin name: ${definition.name}`);
@@ -9,3 +27,7 @@ export function definePlugin(definition) {
         requires: Object.freeze([...(definition.requires ?? [])]),
     });
 }
+// The application facade exposes these Host contracts beside definePlugin.
+export { databaseHostToken, } from './database-host.js';
+export { outboundHostToken, } from './outbound-host.js';
+export { scheduleHostToken, } from './schedule-host.js';

package/lib/schedule-host.d.ts

@@ -37,7 +37,7 @@ export declare function unqualifyPluginScheduleId(owner: PluginId, id: string):
 export declare function createPluginScheduleHost(owner: PluginId, host: ScheduleHost): PluginScheduleHost;
 /** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
 export declare function unwrapPluginScheduleHost(host: ScheduleHost | PluginScheduleHost): ScheduleHost;
-/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+/** @public Plugin-facing token; Runtime injects a facade bound to the current owner. */
 export declare const scheduleHostToken: import("./token.js").Token<PluginScheduleHost>;
 /** Root-only process scheduler for CLI composition and Console administration. */
 export declare const scheduleRootHostToken: import("./token.js").Token<ScheduleHost>;

package/lib/schedule-host.js

@@ -46,7 +46,7 @@ function assertLogicalJobId(id) {
         throw new TypeError(`Invalid plugin schedule id: ${id}`);
     }
 }
-/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+/** @public Plugin-facing token; Runtime injects a facade bound to the current owner. */
 export const scheduleHostToken = createToken('zhin.schedule.host', 'Plugin Runtime scoped solar cron host');
 /** Root-only process scheduler for CLI composition and Console administration. */
 export const scheduleRootHostToken = createToken('zhin.schedule.root-host', 'Plugin Runtime root solar cron host');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",