@crowi/plugin-api 1.0.0-alpha.3 → 1.0.0-alpha.4

package/dist/index.d.mts

@@ -206,6 +206,66 @@ interface PluginLogger {
     error(message: string, ...args: unknown[]): void;
 }
 
+/**
+ * Domain events emitted by core. The full event payload shapes live in
+ * `@crowi/server`; this contract publishes only the event names so the
+ * type signature of `EventBus.on` stays type-safe at the plugin layer.
+ *
+ * `pluginHooks` are the v2.0 internal-use-only events. Community
+ * plugins should NOT subscribe — the surface is reserved while we
+ * stabilise it.
+ */
+interface PluginEvents {
+    'page:created': {
+        pageId: string;
+        path: string;
+    };
+    'page:updated': {
+        pageId: string;
+        path: string;
+    };
+    'page:deleted': {
+        pageId: string;
+        path: string;
+    };
+    'page:renamed': {
+        pageId: string;
+        oldPath: string;
+        newPath: string;
+    };
+    'comment:added': {
+        pageId: string;
+        commentId: string;
+    };
+    'comment:removed': {
+        pageId: string;
+        commentId: string;
+    };
+    'user:registered': {
+        userId: string;
+    };
+    'user:activated': {
+        userId: string;
+    };
+}
+interface EventBus {
+    on<K extends keyof PluginEvents>(event: K, listener: (payload: PluginEvents[K]) => void | Promise<void>): void;
+}
+
+/**
+ * HTML-emitting helper for renderer plugins.
+ *
+ * A renderer plugin that builds HTML from author-controlled or external
+ * strings (an OGP title, a math error message, …) must escape them, and
+ * that escape is a security primitive — a hardening change has to reach
+ * every plugin at once, not whichever local copies someone remembers.
+ * This is the SDK's single copy (`@crowi/plugin-renderer-katex` and
+ * `@crowi/plugin-renderer-link-card` each carried an identical local one
+ * before it was hoisted here).
+ */
+/** Escape `&` `<` `>` `"` `'` for interpolation into HTML text or double/single-quoted attribute values. */
+declare function escapeHtml(s: string): string;
+
 /**
  * Metadata accompanying a `put`. The runtime always provides
  * `contentType`; drivers are free to store additional fields under
@@ -564,52 +624,6 @@ interface MailSenderRegistry {
     register(driverName: string, driver: MailSender): void;
 }
 
-/**
- * Domain events emitted by core. The full event payload shapes live in
- * `@crowi/server`; this contract publishes only the event names so the
- * type signature of `EventBus.on` stays type-safe at the plugin layer.
- *
- * `pluginHooks` are the v2.0 internal-use-only events. Community
- * plugins should NOT subscribe — the surface is reserved while we
- * stabilise it.
- */
-interface PluginEvents {
-    'page:created': {
-        pageId: string;
-        path: string;
-    };
-    'page:updated': {
-        pageId: string;
-        path: string;
-    };
-    'page:deleted': {
-        pageId: string;
-        path: string;
-    };
-    'page:renamed': {
-        pageId: string;
-        oldPath: string;
-        newPath: string;
-    };
-    'comment:added': {
-        pageId: string;
-        commentId: string;
-    };
-    'comment:removed': {
-        pageId: string;
-        commentId: string;
-    };
-    'user:registered': {
-        userId: string;
-    };
-    'user:activated': {
-        userId: string;
-    };
-}
-interface EventBus {
-    on<K extends keyof PluginEvents>(event: K, listener: (payload: PluginEvents[K]) => void | Promise<void>): void;
-}
-
 /**
  * Renderer extension contract — type-only. Plugins contribute parse /
  * transform behaviour to the server-side markdown pipeline through
@@ -691,9 +705,64 @@ interface CodeBlockRenderer {
      * strip comments, etc.
      */
     computeEmbedKey?(info: CodeBlockInfo): string;
+    /**
+     * Opt into a CPU-bounded admission control pool (`render-admission.ts`,
+     * `packages/api/src/renderer/core/render-admission.ts`). When present,
+     * `cachedRenderOrPending` (`packages/api/src/renderer/cache/index.ts`)
+     * and `renderCodeBlockForPreview` acquire a ticket from the named pool
+     * (keyed per `pluginName`) immediately around the `render()` call and
+     * release it on completion; when absent (the default — PlantUML /
+     * KaTeX / emoji and existing embed/URL-expansion plugins), `render()`
+     * is called directly with no admission gate, matching today's
+     * behaviour. See spec §6 for the full design (global / per-user
+     * concurrency caps + priority queue).
+     */
+    admissionControl?: AdmissionControlConfig;
+    /**
+     * Opt into server-rendering during editor live preview
+     * (`POST /pages/preview`, which runs with no `pageId`). Default
+     * `'source'` (omitted) leaves the fenced block untouched in preview —
+     * today's behaviour for every existing `CodeBlockRenderer`. Plugins
+     * that declare `'server-render'` MUST be no-I/O and deterministic:
+     * `makePreviewCodeBlockDispatch` calls them outside the persisted-
+     * cache path (`packages/api/src/renderer/core/code-block-dispatch.ts`).
+     */
+    previewPolicy?: 'source' | 'server-render';
     /** Render a single code block. */
     render(info: CodeBlockInfo, ctx: RenderContext): EmbedFragment | RenderResult | Promise<EmbedFragment | RenderResult>;
 }
+/**
+ * Per-`pluginName` admission-control pool declaration (§6). Shared by
+ * `CodeBlockRenderer` and `EmbedRenderer` — `EmbedRenderer` carries it so
+ * `code-block-dispatch.ts`'s `codeBlockAsEmbedRenderer` adaptor can copy
+ * `CodeBlockRenderer.admissionControl` straight through to the
+ * `EmbedRenderer` shape `cachedRenderOrPending` actually consumes.
+ */
+interface AdmissionControlConfig {
+    /** Process-wide concurrent `render()` calls in flight for this plugin. */
+    maxConcurrentGlobal: number;
+    /** Concurrent `render()` calls in flight for a single `actor` (kind:'user' only). */
+    maxConcurrentPerUser: number;
+    /** Max jobs allowed to wait for a slot before new requests are rejected outright. */
+    queueDepth: number;
+}
+/**
+ * Who is driving this render call. Threaded through `RenderContext` so
+ * admission control (§6) can apply a per-user concurrency cap. Today
+ * every real call site is authenticated (`createJwtAuth` has no
+ * anonymous fallback), so `'user'` is the only variant actually
+ * produced — `'anonymous'` / `'system'` are reserved for future
+ * unauthenticated-read and offline-tooling call sites and must not be
+ * synthesised speculatively.
+ */
+type RenderActor = {
+    kind: 'user';
+    userId: string;
+} | {
+    kind: 'anonymous';
+} | {
+    kind: 'system';
+};
 interface CodeBlockInfo {
     /** The language tag from the fence (the `ts` in ```` ```ts ````). */
     lang: string;
@@ -737,6 +806,41 @@ interface EmbedRenderer {
      * volatility (`?utm_*`) or (b) include external state (Accept-Language).
      */
     computeEmbedKey?(input: EmbedInput): string;
+    /**
+     * Opt into admission control (§6). See `CodeBlockRenderer.admissionControl`
+     * for the full rationale — declared here too because `cachedRenderOrPending`
+     * (`packages/api/src/renderer/cache/index.ts`) is written against the
+     * `EmbedRenderer` shape (`code-block-dispatch.ts`'s
+     * `codeBlockAsEmbedRenderer` adaptor copies a `CodeBlockRenderer`'s
+     * declaration through unchanged). Native `EmbedRenderer` plugins
+     * (embed-tags / URL-inline-expansion) can also opt in if a future one
+     * turns out to be CPU-bound.
+     */
+    admissionControl?: AdmissionControlConfig;
+    /**
+     * Optional per-dispatch cache-bypass predicate
+     * (feature-renderer-plugin-boundary Phase 3). Checked by the generic
+     * embed-tag dispatcher (`packages/api/src/renderer/core/embed-tags.ts`)
+     * BEFORE it touches `CacheStorage` at all for this dispatch — no
+     * `get`, no `set`. When it returns `true`, the dispatcher calls
+     * `render()` directly (via the same `normalizeRenderResult` error
+     * normalisation the preview path uses) and never persists the
+     * result.
+     *
+     * This exists because a renderer whose behaviour is gated by a
+     * runtime policy toggle (e.g. link-card's admin
+     * `security:linkCardEnabled` switch) cannot enforce a literal
+     * zero-cache-access guarantee by checking the toggle only inside
+     * `render()` — a cache HIT from before the toggle flipped would
+     * short-circuit `render()` entirely and keep serving pre-toggle
+     * output (and, symmetrically, writing a toggled-off result to the
+     * cache would keep serving it for up to that entry's TTL after the
+     * toggle flips back). Declaring the check here instead makes the
+     * dispatcher skip the cache outright for that one call. Absent (the
+     * default) or returning `false` goes through the normal cached path
+     * unchanged.
+     */
+    shouldBypassCache?(input: EmbedInput): boolean;
     /** Render a single embed. */
     render(input: EmbedInput, ctx: RenderContext): RenderResult | Promise<RenderResult>;
     /**
@@ -790,19 +894,43 @@ interface RenderResult {
     ttlSec?: number;
     /**
      * When the render failed (network / auth / not_found / rate_limit /
-     * timeout / unknown), plugins should set `error` instead of building
-     * an html error frame. The core caches the error using `RENDER_ERROR_TTL`
-     * and substitutes a fixed placeholder when re-rendering the page.
+     * timeout / unknown / blocked), plugins should set `error` instead of
+     * building an html error frame. The core caches the error using
+     * `RENDER_ERROR_TTL` and, absent `errorHtml`, substitutes a fixed
+     * placeholder when re-rendering the page.
      */
     error?: RenderError;
+    /**
+     * Optional failure-display HTML, paired with `error`. When `error` is
+     * set and `errorHtml` is present, the core shows `errorHtml` instead of
+     * the generic `errorPlaceholder()` — e.g. a link-card plugin can keep
+     * its URL clickable even when the OGP fetch failed. Same trust
+     * contract as `html`: **pre-sanitised, the core does not re-escape it**.
+     *
+     * Deliberately a separate field rather than "non-empty `html` + `error`
+     * means show `html`" — that shape makes a plugin's stray/forgotten
+     * `html` leak into the error display by accident. An explicit opt-in
+     * field means a plugin that hasn't been updated for `errorHtml` keeps
+     * the current safe-by-default behaviour (placeholder).
+     *
+     * Ignored when `error` is unset.
+     */
+    errorHtml?: string;
 }
 /**
  * Error categories cached with their own per-code TTLs. See
  * `packages/api/src/renderer/cache/index.ts:RENDER_ERROR_TTL` for the
- * concrete numbers.
+ * concrete numbers. `blocked` is a policy-level permanent rejection
+ * (SSRF block, disallowed scheme, disallowed content-type) — distinct
+ * from `not_found` semantically but sharing its 1h persistent-failure
+ * TTL. `busy` is a transient renderer-admission rejection (e.g. a
+ * shared fetch/render concurrency semaphore's wait queue was full, or a
+ * queued request's wait deadline elapsed) — never a property of the
+ * embed's target, so it shares a short transient TTL with
+ * `network`/`timeout` rather than `blocked`'s persistent one.
  */
 interface RenderError {
-    code: 'auth' | 'rate_limit' | 'not_found' | 'network' | 'timeout' | 'unknown';
+    code: 'auth' | 'rate_limit' | 'not_found' | 'network' | 'timeout' | 'unknown' | 'blocked' | 'busy';
     /** Free-form text for log/debug — NOT inlined into the user-facing placeholder. */
     message?: string;
     /**
@@ -895,6 +1023,17 @@ interface CacheEntry {
     result: RenderResult;
     fetchedAt: Date;
     expiresAt: Date;
+    /**
+     * Present ⇔ this is a stale-if-error entry keeping a prior success on
+     * screen (see `packages/api/src/renderer/cache/index.ts:
+     * STALE_IF_ERROR_MAX_AGE_SEC`): the value is that ORIGINAL success's
+     * timestamp, carried forward unchanged across consecutive failed
+     * retries — never the failed attempt's `fetchedAt`. Success entries do
+     * not carry it (their `fetchedAt` IS the last-good time; readers use
+     * that directly, which also covers, value-identically, entries written
+     * while this field was still being set on success).
+     */
+    lastGoodFetchedAt?: Date;
 }
 /**
  * MongoDB-backed cache surface. Phase 4 ships exactly one
@@ -987,6 +1126,25 @@ interface RenderContext {
      * encrypted-config-backed implementation.
      */
     auth?: AuthContext;
+    /**
+     * Who is driving this render. Required so admission control (§6) can
+     * apply its per-user concurrency cap end-to-end — every entry point
+     * (`Renderer.run`/`runMetadata`/`runRender`, `packages/api/src/renderer/
+     * index.ts`) requires callers to supply this. See `RenderActor`'s doc
+     * comment for which variant real call sites actually produce today.
+     */
+    actor: RenderActor;
+    /**
+     * Optional cancellation signal, propagated from the originating HTTP
+     * request (`c.req.raw.signal` on `POST /pages/preview`). A waiting
+     * (not-yet-running) admission-control job is removed from its queue
+     * the instant this fires; an already-running child-process render is
+     * NOT force-killed (§6 — the cost of killing/respawning a worker
+     * outweighs letting an already-cheap render finish and discarding the
+     * result). Absent on the save / read call sites, which have no
+     * request to cancel against.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The registry handed to every plugin's `registerRenderer(scope, ctx)`.
@@ -1002,6 +1160,10 @@ interface RenderContext {
  *
  * Phase 4 stubs (warn-noop):
  *   - `addCodeBlockRenderer` (Phase 6 lights this up)
+ *
+ * feature-renderer-plugin-boundary Phase 1 adds `addStylesheet(path)` —
+ * the boot-time CSS-manifest extension point (see that method's own doc
+ * comment).
  */
 interface RendererRegistry {
     /**
@@ -1040,6 +1202,30 @@ interface RendererRegistry {
      * preserved; the first match that returns `'replaced'` wins.
      */
     addUrlInlineExpander(rule: UrlInlineExpansionRule): void;
+    /**
+     * Declare a static CSS asset the plugin needs the browser to load
+     * (e.g. KaTeX's ~30KB math stylesheet). `path` MUST be an
+     * API-relative absolute path confined to the plugin's own
+     * `registerRoutes` namespace — `/api/v2/plugins/<this plugin's
+     * name>/<…>` — the same prefix `PluginRouterScope.route(...)` mounts
+     * that plugin's HTTP routes under. A URL scheme, protocol-relative
+     * `//host`, backslash, `..` traversal segment, or a path outside the
+     * plugin's own namespace all throw synchronously (boot-time reject —
+     * this is not an operator-configurable external URL; see spec
+     * §2.1's "不採用案").
+     *
+     * The call only stages the path in a per-plugin pending set: it is
+     * published to the public `GET /api/v2/app/info` `rendererStylesheets`
+     * manifest ONLY after this plugin's OWN `registerRoutes(scope, ctx)`
+     * completes without throwing (so the manifest never advertises a path
+     * whose route failed to mount). A plugin with no `registerRoutes` at
+     * all, or whose `registerRoutes` throws, never gets its pending
+     * stylesheets committed — dropped wholesale, not partially. Query /
+     * fragment are allowed; duplicate calls with the same path are a
+     * no-op. Call this from `registerRenderer`, not `registerRoutes` —
+     * commit timing depends on this method having already run.
+     */
+    addStylesheet(path: string): void;
 }
 
 /**
@@ -1387,4 +1573,4 @@ interface ActionAnnotation {
  */
 declare function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null;
 
-export { ACTION_FIELD_MARKER, type AppInfo, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };
+export { ACTION_FIELD_MARKER, type AdmissionControlConfig, type AppInfo, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderActor, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, escapeHtml, getActionAnnotation, isSensitiveField };

package/dist/index.d.ts

@@ -206,6 +206,66 @@ interface PluginLogger {
     error(message: string, ...args: unknown[]): void;
 }
 
+/**
+ * Domain events emitted by core. The full event payload shapes live in
+ * `@crowi/server`; this contract publishes only the event names so the
+ * type signature of `EventBus.on` stays type-safe at the plugin layer.
+ *
+ * `pluginHooks` are the v2.0 internal-use-only events. Community
+ * plugins should NOT subscribe — the surface is reserved while we
+ * stabilise it.
+ */
+interface PluginEvents {
+    'page:created': {
+        pageId: string;
+        path: string;
+    };
+    'page:updated': {
+        pageId: string;
+        path: string;
+    };
+    'page:deleted': {
+        pageId: string;
+        path: string;
+    };
+    'page:renamed': {
+        pageId: string;
+        oldPath: string;
+        newPath: string;
+    };
+    'comment:added': {
+        pageId: string;
+        commentId: string;
+    };
+    'comment:removed': {
+        pageId: string;
+        commentId: string;
+    };
+    'user:registered': {
+        userId: string;
+    };
+    'user:activated': {
+        userId: string;
+    };
+}
+interface EventBus {
+    on<K extends keyof PluginEvents>(event: K, listener: (payload: PluginEvents[K]) => void | Promise<void>): void;
+}
+
+/**
+ * HTML-emitting helper for renderer plugins.
+ *
+ * A renderer plugin that builds HTML from author-controlled or external
+ * strings (an OGP title, a math error message, …) must escape them, and
+ * that escape is a security primitive — a hardening change has to reach
+ * every plugin at once, not whichever local copies someone remembers.
+ * This is the SDK's single copy (`@crowi/plugin-renderer-katex` and
+ * `@crowi/plugin-renderer-link-card` each carried an identical local one
+ * before it was hoisted here).
+ */
+/** Escape `&` `<` `>` `"` `'` for interpolation into HTML text or double/single-quoted attribute values. */
+declare function escapeHtml(s: string): string;
+
 /**
  * Metadata accompanying a `put`. The runtime always provides
  * `contentType`; drivers are free to store additional fields under
@@ -564,52 +624,6 @@ interface MailSenderRegistry {
     register(driverName: string, driver: MailSender): void;
 }
 
-/**
- * Domain events emitted by core. The full event payload shapes live in
- * `@crowi/server`; this contract publishes only the event names so the
- * type signature of `EventBus.on` stays type-safe at the plugin layer.
- *
- * `pluginHooks` are the v2.0 internal-use-only events. Community
- * plugins should NOT subscribe — the surface is reserved while we
- * stabilise it.
- */
-interface PluginEvents {
-    'page:created': {
-        pageId: string;
-        path: string;
-    };
-    'page:updated': {
-        pageId: string;
-        path: string;
-    };
-    'page:deleted': {
-        pageId: string;
-        path: string;
-    };
-    'page:renamed': {
-        pageId: string;
-        oldPath: string;
-        newPath: string;
-    };
-    'comment:added': {
-        pageId: string;
-        commentId: string;
-    };
-    'comment:removed': {
-        pageId: string;
-        commentId: string;
-    };
-    'user:registered': {
-        userId: string;
-    };
-    'user:activated': {
-        userId: string;
-    };
-}
-interface EventBus {
-    on<K extends keyof PluginEvents>(event: K, listener: (payload: PluginEvents[K]) => void | Promise<void>): void;
-}
-
 /**
  * Renderer extension contract — type-only. Plugins contribute parse /
  * transform behaviour to the server-side markdown pipeline through
@@ -691,9 +705,64 @@ interface CodeBlockRenderer {
      * strip comments, etc.
      */
     computeEmbedKey?(info: CodeBlockInfo): string;
+    /**
+     * Opt into a CPU-bounded admission control pool (`render-admission.ts`,
+     * `packages/api/src/renderer/core/render-admission.ts`). When present,
+     * `cachedRenderOrPending` (`packages/api/src/renderer/cache/index.ts`)
+     * and `renderCodeBlockForPreview` acquire a ticket from the named pool
+     * (keyed per `pluginName`) immediately around the `render()` call and
+     * release it on completion; when absent (the default — PlantUML /
+     * KaTeX / emoji and existing embed/URL-expansion plugins), `render()`
+     * is called directly with no admission gate, matching today's
+     * behaviour. See spec §6 for the full design (global / per-user
+     * concurrency caps + priority queue).
+     */
+    admissionControl?: AdmissionControlConfig;
+    /**
+     * Opt into server-rendering during editor live preview
+     * (`POST /pages/preview`, which runs with no `pageId`). Default
+     * `'source'` (omitted) leaves the fenced block untouched in preview —
+     * today's behaviour for every existing `CodeBlockRenderer`. Plugins
+     * that declare `'server-render'` MUST be no-I/O and deterministic:
+     * `makePreviewCodeBlockDispatch` calls them outside the persisted-
+     * cache path (`packages/api/src/renderer/core/code-block-dispatch.ts`).
+     */
+    previewPolicy?: 'source' | 'server-render';
     /** Render a single code block. */
     render(info: CodeBlockInfo, ctx: RenderContext): EmbedFragment | RenderResult | Promise<EmbedFragment | RenderResult>;
 }
+/**
+ * Per-`pluginName` admission-control pool declaration (§6). Shared by
+ * `CodeBlockRenderer` and `EmbedRenderer` — `EmbedRenderer` carries it so
+ * `code-block-dispatch.ts`'s `codeBlockAsEmbedRenderer` adaptor can copy
+ * `CodeBlockRenderer.admissionControl` straight through to the
+ * `EmbedRenderer` shape `cachedRenderOrPending` actually consumes.
+ */
+interface AdmissionControlConfig {
+    /** Process-wide concurrent `render()` calls in flight for this plugin. */
+    maxConcurrentGlobal: number;
+    /** Concurrent `render()` calls in flight for a single `actor` (kind:'user' only). */
+    maxConcurrentPerUser: number;
+    /** Max jobs allowed to wait for a slot before new requests are rejected outright. */
+    queueDepth: number;
+}
+/**
+ * Who is driving this render call. Threaded through `RenderContext` so
+ * admission control (§6) can apply a per-user concurrency cap. Today
+ * every real call site is authenticated (`createJwtAuth` has no
+ * anonymous fallback), so `'user'` is the only variant actually
+ * produced — `'anonymous'` / `'system'` are reserved for future
+ * unauthenticated-read and offline-tooling call sites and must not be
+ * synthesised speculatively.
+ */
+type RenderActor = {
+    kind: 'user';
+    userId: string;
+} | {
+    kind: 'anonymous';
+} | {
+    kind: 'system';
+};
 interface CodeBlockInfo {
     /** The language tag from the fence (the `ts` in ```` ```ts ````). */
     lang: string;
@@ -737,6 +806,41 @@ interface EmbedRenderer {
      * volatility (`?utm_*`) or (b) include external state (Accept-Language).
      */
     computeEmbedKey?(input: EmbedInput): string;
+    /**
+     * Opt into admission control (§6). See `CodeBlockRenderer.admissionControl`
+     * for the full rationale — declared here too because `cachedRenderOrPending`
+     * (`packages/api/src/renderer/cache/index.ts`) is written against the
+     * `EmbedRenderer` shape (`code-block-dispatch.ts`'s
+     * `codeBlockAsEmbedRenderer` adaptor copies a `CodeBlockRenderer`'s
+     * declaration through unchanged). Native `EmbedRenderer` plugins
+     * (embed-tags / URL-inline-expansion) can also opt in if a future one
+     * turns out to be CPU-bound.
+     */
+    admissionControl?: AdmissionControlConfig;
+    /**
+     * Optional per-dispatch cache-bypass predicate
+     * (feature-renderer-plugin-boundary Phase 3). Checked by the generic
+     * embed-tag dispatcher (`packages/api/src/renderer/core/embed-tags.ts`)
+     * BEFORE it touches `CacheStorage` at all for this dispatch — no
+     * `get`, no `set`. When it returns `true`, the dispatcher calls
+     * `render()` directly (via the same `normalizeRenderResult` error
+     * normalisation the preview path uses) and never persists the
+     * result.
+     *
+     * This exists because a renderer whose behaviour is gated by a
+     * runtime policy toggle (e.g. link-card's admin
+     * `security:linkCardEnabled` switch) cannot enforce a literal
+     * zero-cache-access guarantee by checking the toggle only inside
+     * `render()` — a cache HIT from before the toggle flipped would
+     * short-circuit `render()` entirely and keep serving pre-toggle
+     * output (and, symmetrically, writing a toggled-off result to the
+     * cache would keep serving it for up to that entry's TTL after the
+     * toggle flips back). Declaring the check here instead makes the
+     * dispatcher skip the cache outright for that one call. Absent (the
+     * default) or returning `false` goes through the normal cached path
+     * unchanged.
+     */
+    shouldBypassCache?(input: EmbedInput): boolean;
     /** Render a single embed. */
     render(input: EmbedInput, ctx: RenderContext): RenderResult | Promise<RenderResult>;
     /**
@@ -790,19 +894,43 @@ interface RenderResult {
     ttlSec?: number;
     /**
      * When the render failed (network / auth / not_found / rate_limit /
-     * timeout / unknown), plugins should set `error` instead of building
-     * an html error frame. The core caches the error using `RENDER_ERROR_TTL`
-     * and substitutes a fixed placeholder when re-rendering the page.
+     * timeout / unknown / blocked), plugins should set `error` instead of
+     * building an html error frame. The core caches the error using
+     * `RENDER_ERROR_TTL` and, absent `errorHtml`, substitutes a fixed
+     * placeholder when re-rendering the page.
      */
     error?: RenderError;
+    /**
+     * Optional failure-display HTML, paired with `error`. When `error` is
+     * set and `errorHtml` is present, the core shows `errorHtml` instead of
+     * the generic `errorPlaceholder()` — e.g. a link-card plugin can keep
+     * its URL clickable even when the OGP fetch failed. Same trust
+     * contract as `html`: **pre-sanitised, the core does not re-escape it**.
+     *
+     * Deliberately a separate field rather than "non-empty `html` + `error`
+     * means show `html`" — that shape makes a plugin's stray/forgotten
+     * `html` leak into the error display by accident. An explicit opt-in
+     * field means a plugin that hasn't been updated for `errorHtml` keeps
+     * the current safe-by-default behaviour (placeholder).
+     *
+     * Ignored when `error` is unset.
+     */
+    errorHtml?: string;
 }
 /**
  * Error categories cached with their own per-code TTLs. See
  * `packages/api/src/renderer/cache/index.ts:RENDER_ERROR_TTL` for the
- * concrete numbers.
+ * concrete numbers. `blocked` is a policy-level permanent rejection
+ * (SSRF block, disallowed scheme, disallowed content-type) — distinct
+ * from `not_found` semantically but sharing its 1h persistent-failure
+ * TTL. `busy` is a transient renderer-admission rejection (e.g. a
+ * shared fetch/render concurrency semaphore's wait queue was full, or a
+ * queued request's wait deadline elapsed) — never a property of the
+ * embed's target, so it shares a short transient TTL with
+ * `network`/`timeout` rather than `blocked`'s persistent one.
  */
 interface RenderError {
-    code: 'auth' | 'rate_limit' | 'not_found' | 'network' | 'timeout' | 'unknown';
+    code: 'auth' | 'rate_limit' | 'not_found' | 'network' | 'timeout' | 'unknown' | 'blocked' | 'busy';
     /** Free-form text for log/debug — NOT inlined into the user-facing placeholder. */
     message?: string;
     /**
@@ -895,6 +1023,17 @@ interface CacheEntry {
     result: RenderResult;
     fetchedAt: Date;
     expiresAt: Date;
+    /**
+     * Present ⇔ this is a stale-if-error entry keeping a prior success on
+     * screen (see `packages/api/src/renderer/cache/index.ts:
+     * STALE_IF_ERROR_MAX_AGE_SEC`): the value is that ORIGINAL success's
+     * timestamp, carried forward unchanged across consecutive failed
+     * retries — never the failed attempt's `fetchedAt`. Success entries do
+     * not carry it (their `fetchedAt` IS the last-good time; readers use
+     * that directly, which also covers, value-identically, entries written
+     * while this field was still being set on success).
+     */
+    lastGoodFetchedAt?: Date;
 }
 /**
  * MongoDB-backed cache surface. Phase 4 ships exactly one
@@ -987,6 +1126,25 @@ interface RenderContext {
      * encrypted-config-backed implementation.
      */
     auth?: AuthContext;
+    /**
+     * Who is driving this render. Required so admission control (§6) can
+     * apply its per-user concurrency cap end-to-end — every entry point
+     * (`Renderer.run`/`runMetadata`/`runRender`, `packages/api/src/renderer/
+     * index.ts`) requires callers to supply this. See `RenderActor`'s doc
+     * comment for which variant real call sites actually produce today.
+     */
+    actor: RenderActor;
+    /**
+     * Optional cancellation signal, propagated from the originating HTTP
+     * request (`c.req.raw.signal` on `POST /pages/preview`). A waiting
+     * (not-yet-running) admission-control job is removed from its queue
+     * the instant this fires; an already-running child-process render is
+     * NOT force-killed (§6 — the cost of killing/respawning a worker
+     * outweighs letting an already-cheap render finish and discarding the
+     * result). Absent on the save / read call sites, which have no
+     * request to cancel against.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The registry handed to every plugin's `registerRenderer(scope, ctx)`.
@@ -1002,6 +1160,10 @@ interface RenderContext {
  *
  * Phase 4 stubs (warn-noop):
  *   - `addCodeBlockRenderer` (Phase 6 lights this up)
+ *
+ * feature-renderer-plugin-boundary Phase 1 adds `addStylesheet(path)` —
+ * the boot-time CSS-manifest extension point (see that method's own doc
+ * comment).
  */
 interface RendererRegistry {
     /**
@@ -1040,6 +1202,30 @@ interface RendererRegistry {
      * preserved; the first match that returns `'replaced'` wins.
      */
     addUrlInlineExpander(rule: UrlInlineExpansionRule): void;
+    /**
+     * Declare a static CSS asset the plugin needs the browser to load
+     * (e.g. KaTeX's ~30KB math stylesheet). `path` MUST be an
+     * API-relative absolute path confined to the plugin's own
+     * `registerRoutes` namespace — `/api/v2/plugins/<this plugin's
+     * name>/<…>` — the same prefix `PluginRouterScope.route(...)` mounts
+     * that plugin's HTTP routes under. A URL scheme, protocol-relative
+     * `//host`, backslash, `..` traversal segment, or a path outside the
+     * plugin's own namespace all throw synchronously (boot-time reject —
+     * this is not an operator-configurable external URL; see spec
+     * §2.1's "不採用案").
+     *
+     * The call only stages the path in a per-plugin pending set: it is
+     * published to the public `GET /api/v2/app/info` `rendererStylesheets`
+     * manifest ONLY after this plugin's OWN `registerRoutes(scope, ctx)`
+     * completes without throwing (so the manifest never advertises a path
+     * whose route failed to mount). A plugin with no `registerRoutes` at
+     * all, or whose `registerRoutes` throws, never gets its pending
+     * stylesheets committed — dropped wholesale, not partially. Query /
+     * fragment are allowed; duplicate calls with the same path are a
+     * no-op. Call this from `registerRenderer`, not `registerRoutes` —
+     * commit timing depends on this method having already run.
+     */
+    addStylesheet(path: string): void;
 }
 
 /**
@@ -1387,4 +1573,4 @@ interface ActionAnnotation {
  */
 declare function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null;
 
-export { ACTION_FIELD_MARKER, type AppInfo, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, getActionAnnotation, isSensitiveField };
+export { ACTION_FIELD_MARKER, type AdmissionControlConfig, type AppInfo, type AuthContext, type AuthDriver, type AuthProfile, type AuthRegistry, type AuthVerifyResult, type CacheEntry, type CacheKey, type CacheStorage, type CodeBlockInfo, type CodeBlockRenderer, type CrowiPlugin, type EmailMessage, type EmbedFragment, type EmbedInput, type EmbedRenderer, type EventBus, type InlineExpansion, type MailSender, type MailSenderRegistry, type NodeRenderer, type NotificationPayload, type NotifierDriver, type NotifierRegistry, type PageMetadataAccessor, type PluginContext, type PluginEvents, type PluginLogger, type PluginRouteHandler, type PluginRouteMethod, type PluginRouteOptions, type PluginRouterScope, type RenderActor, type RenderContext, type RenderError, type RenderPhase, type RenderResult, type RendererRegistry, type Reservation, SENSITIVE_FIELD_MARKER, type ScopedCacheStorage, type SearchDriver, type SearchHit, type SearchHits, type SearchPageType, type SearchQuery, type SearchQueryGrants, type SearchQueryViewer, type SearchRegistry, type SearchableDoc, type StateCell, type StorageDriver, type StoragePutMeta, type StoragePutResult, type StorageRegistry, type UrlInlineExpansionRule, escapeHtml, getActionAnnotation, isSensitiveField };

package/dist/index.js

@@ -22,11 +22,32 @@ var index_exports = {};
 __export(index_exports, {
   ACTION_FIELD_MARKER: () => ACTION_FIELD_MARKER,
   SENSITIVE_FIELD_MARKER: () => SENSITIVE_FIELD_MARKER,
+  escapeHtml: () => escapeHtml,
   getActionAnnotation: () => getActionAnnotation,
   isSensitiveField: () => isSensitiveField
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/html.ts
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => {
+    switch (c) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      case "'":
+        return "&#39;";
+      default:
+        return c;
+    }
+  });
+}
+
 // src/schema-markers.ts
 var SENSITIVE_FIELD_MARKER = "@sensitive";
 var ACTION_FIELD_MARKER = "@action";
@@ -49,6 +70,7 @@ function getActionAnnotation(field) {
 0 && (module.exports = {
   ACTION_FIELD_MARKER,
   SENSITIVE_FIELD_MARKER,
+  escapeHtml,
   getActionAnnotation,
   isSensitiveField
 });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * @crowi/plugin-api — type-only contract for Crowi 2.0 plugins.\n *\n * Plugins author against this package. The runtime (@crowi/server) loads\n * plugins listed in `crowi.config.json`, calls each plugin's\n * `register*` callbacks, and routes all the side effects (storage,\n * search, auth, notifications) through the typed registries declared\n * here.\n *\n * For the design rationale see `docs/rfcs/0001-plugin-architecture.md`\n * in the Crowi monorepo.\n */\n\nexport type { CrowiPlugin } from './plugin';\n\nexport type { PluginContext, AppInfo, PageMetadataAccessor, PluginLogger, StateCell } from './context';\n\nexport type { StorageDriver, StorageRegistry, StoragePutMeta, StoragePutResult } from './registries/storage';\n\nexport type {\n  SearchDriver,\n  SearchRegistry,\n  SearchableDoc,\n  SearchQuery,\n  SearchQueryViewer,\n  SearchQueryGrants,\n  SearchPageType,\n  SearchHits,\n  SearchHit,\n} from './registries/search';\n\nexport type { AuthDriver, AuthRegistry, AuthProfile, AuthVerifyResult } from './registries/auth';\n\nexport type { NotifierDriver, NotifierRegistry, NotificationPayload } from './registries/notifier';\n\nexport type { MailSender, MailSenderRegistry, EmailMessage } from './registries/mail';\n\nexport type {\n  RendererRegistry,\n  NodeRenderer,\n  CodeBlockRenderer,\n  CodeBlockInfo,\n  EmbedRenderer,\n  EmbedInput,\n  EmbedFragment,\n  UrlInlineExpansionRule,\n  InlineExpansion,\n  RenderContext,\n  RenderPhase,\n  RenderResult,\n  RenderError,\n  Reservation,\n  CacheStorage,\n  ScopedCacheStorage,\n  CacheKey,\n  CacheEntry,\n  AuthContext,\n} from './renderer';\n\nexport type { EventBus, PluginEvents } from './events';\n\nexport type { PluginRouterScope, PluginRouteHandler, PluginRouteMethod, PluginRouteOptions } from './routes';\n\nexport { SENSITIVE_FIELD_MARKER, ACTION_FIELD_MARKER, isSensitiveField, getActionAnnotation } from './schema-markers';\n","import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: PluginRouteMethod;\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACwBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AA6BO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,mCAAmC;AAC5D,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/html.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * @crowi/plugin-api — type-only contract for Crowi 2.0 plugins.\n *\n * Plugins author against this package. The runtime (@crowi/server) loads\n * plugins listed in `crowi.config.json`, calls each plugin's\n * `register*` callbacks, and routes all the side effects (storage,\n * search, auth, notifications) through the typed registries declared\n * here.\n *\n * For the design rationale see `docs/rfcs/0001-plugin-architecture.md`\n * in the Crowi monorepo.\n */\n\nexport type { AppInfo, PageMetadataAccessor, PluginContext, PluginLogger, StateCell } from './context';\nexport type { EventBus, PluginEvents } from './events';\nexport { escapeHtml } from './html';\nexport type { CrowiPlugin } from './plugin';\n\nexport type { AuthDriver, AuthProfile, AuthRegistry, AuthVerifyResult } from './registries/auth';\nexport type { EmailMessage, MailSender, MailSenderRegistry } from './registries/mail';\nexport type { NotificationPayload, NotifierDriver, NotifierRegistry } from './registries/notifier';\nexport type {\n  SearchableDoc,\n  SearchDriver,\n  SearchHit,\n  SearchHits,\n  SearchPageType,\n  SearchQuery,\n  SearchQueryGrants,\n  SearchQueryViewer,\n  SearchRegistry,\n} from './registries/search';\nexport type { StorageDriver, StoragePutMeta, StoragePutResult, StorageRegistry } from './registries/storage';\nexport type {\n  AdmissionControlConfig,\n  AuthContext,\n  CacheEntry,\n  CacheKey,\n  CacheStorage,\n  CodeBlockInfo,\n  CodeBlockRenderer,\n  EmbedFragment,\n  EmbedInput,\n  EmbedRenderer,\n  InlineExpansion,\n  NodeRenderer,\n  RenderActor,\n  RenderContext,\n  RenderError,\n  RendererRegistry,\n  RenderPhase,\n  RenderResult,\n  Reservation,\n  ScopedCacheStorage,\n  UrlInlineExpansionRule,\n} from './renderer';\nexport type { PluginRouteHandler, PluginRouteMethod, PluginRouteOptions, PluginRouterScope } from './routes';\nexport { ACTION_FIELD_MARKER, getActionAnnotation, isSensitiveField, SENSITIVE_FIELD_MARKER } from './schema-markers';\n","/**\n * HTML-emitting helper for renderer plugins.\n *\n * A renderer plugin that builds HTML from author-controlled or external\n * strings (an OGP title, a math error message, …) must escape them, and\n * that escape is a security primitive — a hardening change has to reach\n * every plugin at once, not whichever local copies someone remembers.\n * This is the SDK's single copy (`@crowi/plugin-renderer-katex` and\n * `@crowi/plugin-renderer-link-card` each carried an identical local one\n * before it was hoisted here).\n */\n\n/** Escape `&` `<` `>` `\"` `'` for interpolation into HTML text or double/single-quoted attribute values. */\nexport function escapeHtml(s: string): string {\n  return s.replace(/[&<>\"']/g, (c) => {\n    switch (c) {\n      case '&':\n        return '&amp;';\n      case '<':\n        return '&lt;';\n      case '>':\n        return '&gt;';\n      case '\"':\n        return '&quot;';\n      case \"'\":\n        return '&#39;';\n      default:\n        return c;\n    }\n  });\n}\n","import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: PluginRouteMethod;\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACaO,SAAS,WAAW,GAAmB;AAC5C,SAAO,EAAE,QAAQ,YAAY,CAAC,MAAM;AAClC,YAAQ,GAAG;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT;AACE,eAAO;AAAA,IACX;AAAA,EACF,CAAC;AACH;;;ACNO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AA6BO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,mCAAmC;AAC5D,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}

package/dist/index.mjs

@@ -1,3 +1,23 @@
+// src/html.ts
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => {
+    switch (c) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      case "'":
+        return "&#39;";
+      default:
+        return c;
+    }
+  });
+}
+
 // src/schema-markers.ts
 var SENSITIVE_FIELD_MARKER = "@sensitive";
 var ACTION_FIELD_MARKER = "@action";
@@ -19,6 +39,7 @@ function getActionAnnotation(field) {
 export {
   ACTION_FIELD_MARKER,
   SENSITIVE_FIELD_MARKER,
+  escapeHtml,
   getActionAnnotation,
   isSensitiveField
 };

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schema-markers.ts"],"sourcesContent":["import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: PluginRouteMethod;\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";AAwBO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AA6BO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,mCAAmC;AAC5D,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}
+{"version":3,"sources":["../src/html.ts","../src/schema-markers.ts"],"sourcesContent":["/**\n * HTML-emitting helper for renderer plugins.\n *\n * A renderer plugin that builds HTML from author-controlled or external\n * strings (an OGP title, a math error message, …) must escape them, and\n * that escape is a security primitive — a hardening change has to reach\n * every plugin at once, not whichever local copies someone remembers.\n * This is the SDK's single copy (`@crowi/plugin-renderer-katex` and\n * `@crowi/plugin-renderer-link-card` each carried an identical local one\n * before it was hoisted here).\n */\n\n/** Escape `&` `<` `>` `\"` `'` for interpolation into HTML text or double/single-quoted attribute values. */\nexport function escapeHtml(s: string): string {\n  return s.replace(/[&<>\"']/g, (c) => {\n    switch (c) {\n      case '&':\n        return '&amp;';\n      case '<':\n        return '&lt;';\n      case '>':\n        return '&gt;';\n      case '\"':\n        return '&quot;';\n      case \"'\":\n        return '&#39;';\n      default:\n        return c;\n    }\n  });\n}\n","import type { z } from 'zod/v3';\n\nimport type { PluginRouteMethod } from './routes';\n\n/**\n * `configSchema` description-string markers.\n *\n * The admin UI walks the schema and looks at each field's\n * `description` (set via `z.string().describe('@sensitive ...')`). A\n * description starting with one of these marker tokens unlocks special\n * UI behaviour without forcing every field to declare a custom Zod\n * type.\n */\n\n/**\n * Marker that flags a config field as sensitive (encrypted at rest).\n * Usage:\n *\n *   z.string().describe('@sensitive AWS secret access key')\n *\n * The runtime auto-encrypts on write and decrypts on read, using the\n * same KeyProvider as core sensitive Config. The admin UI renders the\n * field via `<SecretField>` (saved badge / clear pending / undo).\n */\nexport const SENSITIVE_FIELD_MARKER = '@sensitive';\n\n/**\n * Marker that adds an action button next to a config field. Usage:\n *\n *   z.string().describe('@action \"Test connection\" POST /test')\n *\n * The admin form renders a button with the given label that calls the\n * plugin's contributed endpoint at the given verb / path (relative to\n * `/api/v2/plugins/<name>/`). Useful for \"Test connection\",\n * \"Authorise with Google\", etc. without forcing every plugin to ship\n * its own React component.\n */\nexport const ACTION_FIELD_MARKER = '@action';\n\n/**\n * True if the schema field is marked `@sensitive`.\n *\n * `field` is `z.ZodTypeAny` (intentionally loose); call sites pass the\n * value type from `configSchema.shape[key]`.\n */\nexport function isSensitiveField(field: z.ZodTypeAny): boolean {\n  const description = field.description;\n  return typeof description === 'string' && description.trimStart().startsWith(SENSITIVE_FIELD_MARKER);\n}\n\n/**\n * Parsed `@action` annotation extracted from a field's `description`.\n */\nexport interface ActionAnnotation {\n  /** Visible button label, e.g. \"Test connection\". */\n  label: string;\n  /** HTTP verb of the plugin endpoint to call. */\n  method: PluginRouteMethod;\n  /** Path relative to `/api/v2/plugins/<name>/`, with leading slash. */\n  path: string;\n}\n\n/**\n * Parse an `@action` annotation off a field, or return null if absent.\n *\n * Format: `@action \"<label>\" <METHOD> <path>`\n *   e.g. `@action \"Test connection\" POST /test`\n *\n * The label may include spaces when wrapped in double quotes; the method\n * must be one of `PluginRouteMethod` (`GET` / `POST` — the only verbs a\n * plugin route can actually be mounted on, see `routes.ts`); the path\n * begins with `/`. A description that starts with the `@action` marker\n * but declares an unsupported verb (e.g. `PUT` / `DELETE`) fails to match\n * and returns `null` here — callers that walk a plugin's `configSchema`\n * (e.g. `PluginManager.activate()`) are expected to warn on that case at\n * boot, since it would otherwise be a silent dead button.\n */\nexport function getActionAnnotation(field: z.ZodTypeAny): ActionAnnotation | null {\n  const description = field.description;\n  if (typeof description !== 'string') return null;\n  const trimmed = description.trimStart();\n  if (!trimmed.startsWith(ACTION_FIELD_MARKER)) return null;\n\n  const rest = trimmed.slice(ACTION_FIELD_MARKER.length).trimStart();\n  // `\"<label>\" <METHOD> <path>`\n  const match = rest.match(/^\"([^\"]+)\"\\s+(GET|POST)\\s+(\\/\\S*)/);\n  if (!match) return null;\n\n  const [, label, method, path] = match;\n  return { label, method: method as ActionAnnotation['method'], path };\n}\n"],"mappings":";AAaO,SAAS,WAAW,GAAmB;AAC5C,SAAO,EAAE,QAAQ,YAAY,CAAC,MAAM;AAClC,YAAQ,GAAG;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT,KAAK;AACH,eAAO;AAAA,MACT;AACE,eAAO;AAAA,IACX;AAAA,EACF,CAAC;AACH;;;ACNO,IAAM,yBAAyB;AAa/B,IAAM,sBAAsB;AAQ5B,SAAS,iBAAiB,OAA8B;AAC7D,QAAM,cAAc,MAAM;AAC1B,SAAO,OAAO,gBAAgB,YAAY,YAAY,UAAU,EAAE,WAAW,sBAAsB;AACrG;AA6BO,SAAS,oBAAoB,OAA8C;AAChF,QAAM,cAAc,MAAM;AAC1B,MAAI,OAAO,gBAAgB,SAAU,QAAO;AAC5C,QAAM,UAAU,YAAY,UAAU;AACtC,MAAI,CAAC,QAAQ,WAAW,mBAAmB,EAAG,QAAO;AAErD,QAAM,OAAO,QAAQ,MAAM,oBAAoB,MAAM,EAAE,UAAU;AAEjE,QAAM,QAAQ,KAAK,MAAM,mCAAmC;AAC5D,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,CAAC,EAAE,OAAO,QAAQ,IAAI,IAAI;AAChC,SAAO,EAAE,OAAO,QAA8C,KAAK;AACrE;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowi/plugin-api",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "Type-only contract for Crowi 2.0 plugins. See docs/rfcs/0001-plugin-architecture.md.",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
   "devDependencies": {
     "@types/jest": "^29.5.14",
     "@types/node": "^24",
-    "hono": "^4.12.25",
+    "hono": "^4.12.31",
     "jest": "^29.7.0",
     "ts-jest": "^29.3.4",
     "tsup": "^8.3.5",