@north-light/crouter-api 0.3.205 → 0.3.207

package/dist/api/dto/messages.d.ts

@@ -1,4 +1,14 @@
 import type { InboxTierDTO, IsoTime, NodeIdDTO } from './common.js';
+/** One runtime card supplied by a caller: the runtime renders and escapes it
+ *  exactly once, so a caller cannot emit a malformed card or smuggle markup
+ *  into one. `kind` must be namespaced (contain `:`) — bare kinds are
+ *  crouter's own closed vocabulary. */
+export interface RuntimeCardRequest {
+    kind: string;
+    facts?: Record<string, string | number>;
+    /** Data, not markup. */
+    body?: string;
+}
 /** `POST /v1/nodes/{id}/messages` body. */
 export interface SendMessageRequest {
     body: string;
@@ -12,10 +22,19 @@ export interface SendMessageRequest {
     /** Clear a latched target's finalization latch before an immediate delivery
      *  or `--fresh` revive (`--reopen`). Immediate only. */
     reopen?: boolean;
-    /** Hidden ambient context upserted onto the target's sidecar and delivered as
-     *  a `<situational-context>` block, never visible chat (`--situational-context`).
-     *  Immediate only; valid alone (no body). */
+    /** Hidden ambient context upserted onto the target's sidecar as a
+     *  `situational` card, never visible chat (`--situational-context`).
+     *  Immediate only; valid alone (no body). Prose only — its body is NOT
+     *  escaped; a caller with untrusted text uses `situational_card`. */
     situational_context?: string;
+    /** A runtime card that REPLACES the target's situational sidecar, delivered
+     *  ahead of the body in the same turn and re-stated by the session-start
+     *  bearings after a context refresh. Mutually exclusive with
+     *  `situational_context`; valid alone (no body) on the durable path. */
+    situational_card?: RuntimeCardRequest;
+    /** One-shot runtime cards for this turn only — never persisted. Delivered in
+     *  array order, after `situational_card` and ahead of the body. */
+    context_cards?: RuntimeCardRequest[];
     /** Raw JSON-schema string granting a one-off `submit` tool before delivery
      *  (`--output-schema`). Immediate only. */
     output_schema?: string;
@@ -24,7 +43,10 @@ export interface SendMessageRequest {
      *  instead of the durable inbox; a dormant or mid-revive target falls back to
      *  the durable inbox + revive (watcher delivers post-boot). Plain immediate
      *  body only — rejected with fresh/reopen/situational_context/
-     *  output_schema or tier 'deferred'. Absent → durable inbox (unchanged). */
+     *  output_schema or tier 'deferred'. Runtime cards ARE accepted: a
+     *  card-bearing send is an ordinary human send that happens to carry context,
+     *  and the live deliver frame places the cards ahead of the body in one turn.
+     *  Absent → durable inbox (unchanged). */
     delivery?: 'interactive';
 }
 /** Result of an immediate message send. */

package/dist/shared/generated-context.d.ts

@@ -71,10 +71,21 @@ export interface CardKindDefinition {
 }
 /** The closed crouter vocabulary, plus custom-role aliases for the same cards. */
 export declare const KIND_TABLE: Readonly<Record<string, CardKindDefinition>>;
+/** Contribute presentation for namespaced kinds this process will render.
+ *  Idempotent and last-write-wins, so a re-imported module cannot fail a boot.
+ *  A process that never registers is not degraded: an unregistered kind still
+ *  parses and only falls back to the generic label and summary. */
+export declare function registerCardKinds(kinds: Readonly<Record<string, CardKindDefinition>>): void;
 /** Plain text from a generated message's string or text-block content. */
 export declare function generatedContextText(message: GeneratedContextMessageLike): string;
 /** Wrap a user-role runtime message in its whole-message card envelope. */
 export declare function formatCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
+/** Wrap a card whose body is DATA, not markup — the only escape on the API
+ *  path, so a caller can neither emit a malformed card nor smuggle markup into
+ *  one. `formatCard` keeps its raw body for the trusted crouter producers that
+ *  deliberately nest markup (bearings blocks, the inbox `<from>`/`<entry>`
+ *  grammar `parseInboxBody` depends on). */
+export declare function formatDataCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
 /** Parse a runtime envelope, with pre-envelope customType compatibility. */
 export declare function parseCard(message: GeneratedContextMessageLike): GeneratedCard | null;
 /** Format a complete inbox card from report bodies resolved by the caller. */

package/dist/shared/generated-context.js

@@ -114,6 +114,21 @@ const GENERIC_CARD = {
     summary: () => 'runtime context',
     expandable: true,
 };
+/** Kinds contributed by a product or plugin, in whatever process renders them. */
+const KIND_REGISTRY = {};
+/** Contribute presentation for namespaced kinds this process will render.
+ *  Idempotent and last-write-wins, so a re-imported module cannot fail a boot.
+ *  A process that never registers is not degraded: an unregistered kind still
+ *  parses and only falls back to the generic label and summary. */
+export function registerCardKinds(kinds) {
+    for (const [kind, definition] of Object.entries(kinds)) {
+        // Bare kinds are crouter core's closed vocabulary. A product claiming one
+        // is a programming error at boot, not a runtime condition to tolerate.
+        if (!kind.includes(':'))
+            throw new Error(`Runtime card kind must be namespaced (contain ':'): ${kind}`);
+        KIND_REGISTRY[kind] = definition;
+    }
+}
 const XML_ATTRIBUTE_NAME = /^[A-Za-z_:][A-Za-z0-9_:.-]*$/;
 const ATTRIBUTE_RE = /\s+([A-Za-z_:][A-Za-z0-9_:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/gy;
 function escapeXmlAttribute(value) {
@@ -187,6 +202,14 @@ export function formatCard(kind, facts, body) {
         throw new Error('Runtime card facts cannot replace kind');
     return `<runtime${formatAttributes({ kind, ...facts })}>${body}</runtime>`;
 }
+/** Wrap a card whose body is DATA, not markup — the only escape on the API
+ *  path, so a caller can neither emit a malformed card nor smuggle markup into
+ *  one. `formatCard` keeps its raw body for the trusted crouter producers that
+ *  deliberately nest markup (bearings blocks, the inbox `<from>`/`<entry>`
+ *  grammar `parseInboxBody` depends on). */
+export function formatDataCard(kind, facts, body) {
+    return formatCard(kind, facts, escapeXmlText(body));
+}
 function parseInboxBody(body) {
     const senders = [];
     const fromRe = /<from\b([^>]*)>([\s\S]*?)<\/from>/g;
@@ -225,7 +248,7 @@ function parseInboxBody(body) {
     return senders;
 }
 function cardFor(kind, facts, body, senders) {
-    const definition = KIND_TABLE[kind] ?? GENERIC_CARD;
+    const definition = KIND_TABLE[kind] ?? KIND_REGISTRY[kind] ?? GENERIC_CARD;
     return {
         kind,
         facts,
@@ -244,9 +267,13 @@ function parseEnvelope(text) {
     const attributes = parseAttributes(opening[1] ?? '');
     if (attributes?.kind === undefined)
         return null;
-    const body = text.slice(opening[0].length, -'</runtime>'.length);
+    const raw = text.slice(opening[0].length, -'</runtime>'.length);
     const { kind, ...factValues } = attributes;
     const facts = Object.freeze(factValues);
+    // A namespaced kind can only have been produced through the API path, whose
+    // renderer is `formatDataCard`, so its body is escaped by construction and
+    // decodes here. A bare kind's body is raw markup written by a core producer.
+    const body = kind.includes(':') ? unescapeXmlAttribute(raw) : raw;
     return cardFor(kind, facts, body, kind === 'inbox' ? parseInboxBody(body) : []);
 }
 /** Parse a runtime envelope, with pre-envelope customType compatibility. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter-api",
-  "version": "0.3.205",
+  "version": "0.3.207",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, and the CrtrClient. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",
@@ -11,6 +11,12 @@
       "import": "./dist/api/index.js",
       "require": "./dist/api/index.js",
       "default": "./dist/api/index.js"
+    },
+    "./cards": {
+      "types": "./dist/shared/generated-context.d.ts",
+      "import": "./dist/shared/generated-context.js",
+      "require": "./dist/shared/generated-context.js",
+      "default": "./dist/shared/generated-context.js"
     }
   },
   "files": [