@elastic/isomer-sdk 0.0.0 → 0.2.0

package/dist/define/primitive_module.d.ts

@@ -0,0 +1,435 @@
+import type { ReactNode } from 'react';
+import { z, type ZodObject, type ZodType } from 'zod';
+import type { ActionEventRef } from '../composition/action_event.js';
+import { type ChildNodeRef, type SurfaceName } from '../composition/body_node_base.js';
+import type { PrimitiveNode } from '../composition/node.js';
+import type { ValidationError } from '../composition/validation_error.js';
+import type { MarkdownContent } from './markdown_content.js';
+import type { PrimitiveExample } from './primitive_example.js';
+import type { PrimitiveIcon } from './primitive_icon.js';
+import type { SlackAssetCollector } from './slack_assets.js';
+import type { SlackBlock } from './slack_blocks.js';
+export type { PrimitiveNode };
+/**
+ * A primitive's entry in the catalog the authoring prompt is built from.
+ *
+ * Written for the model rather than for a developer: `useWhen` and `avoidWhen`
+ * are what steer it away from reaching for the wrong primitive. `name` is the
+ * one host-facing field, and the prompt never prints it.
+ */
+export interface PrimitiveCatalogEntry {
+    type: string;
+    /** Short name a host shows for the primitive, e.g. `Stat group`. Absent means the host derives one from `type`. */
+    name?: string;
+    /** One line on what the primitive is for, in the model's voice. */
+    purpose: string;
+    /** Situations that call for this primitive. Phrase each as a user intent, not a shape. */
+    useWhen: string[];
+    /** Situations that look like a fit but are not, naming the primitive to reach for instead. */
+    avoidWhen: string[];
+    /** A node literal the authoring prompt inlines under this primitive. */
+    example: unknown;
+}
+/** A style a renderer asks for by name, resolved to a class by the host's adapter. */
+export interface StyleHandle {
+    /** Stable lookup key. The adapter's map is keyed on this. */
+    key: string;
+    /** Debug-facing label, which an adapter may fold into a generated class name. */
+    readableName: string;
+}
+/** Dotted path into a pack's theme tokens, e.g. `colors.text.subdued`. */
+export type ThemeTokenPath = string;
+/**
+ * The sdk's own render context, and {@link DefaultPackTypes.context}.
+ *
+ * A pack with real theme tokens or a richer style-handle type declares its
+ * own context in its {@link PackTypes}; {@link StyledRenderContext} is the
+ * sdk's own extension. The bag is what lets a pack narrow without
+ * re-declaring everything that mentions a context.
+ */
+export interface PrimitiveRenderContext {
+    /**
+     * The progressive enhancements this render may assume, by id. A set rather
+     * than a field per feature so adding an enhancement costs no plumbing:
+     * containers forward the whole context, and a renderer asks
+     * `context.enhancements?.has('tableSort')`.
+     *
+     * Empty or absent is the baseline every host can render, so a renderer must
+     * still answer the question on its own. See `docs/rendering.md`.
+     */
+    enhancements?: ReadonlySet<string>;
+    /** Turns on `nodeAnchor` outside an HTML surface render, on the React and `snapshot` surfaces; inside one, the surface decides. */
+    anchors?: boolean;
+    /** Raises an interaction for the host to route. Absent means render non-interactively. */
+    onEvent?: (event: ActionEventRef) => void;
+}
+/**
+ * The render-context argument, optional only when omitting it is sound.
+ *
+ * The sdk's own {@link PrimitiveRenderContext} has no required field, so `{}`
+ * is a complete value and a caller may leave it out. A pack that narrows the
+ * context with a required member makes the argument mandatory.
+ */
+export type ReactContextArg<TContext> = Record<string, never> extends TContext ? [context?: TContext] : [context: TContext];
+/**
+ * {@link PrimitiveRenderContext} plus the CSS-in-JS hooks an HTML style adapter
+ * supplies. A pack that styles differently uses its own `TContext` instead.
+ */
+export interface StyledRenderContext extends PrimitiveRenderContext {
+    /** Resolves handles to a `className`. Absent means the host supplies no styling. */
+    resolveClassName?: (...handles: StyleHandle[]) => string;
+    /** Resolves a theme token to a CSS variable reference. Absent means inline the literal value. */
+    cssVarRef?: (path: ThemeTokenPath) => `var(--${string})`;
+}
+/** Passed to a primitive's style collector so it can vary CSS by layout mode. */
+export interface PrimitiveStyleCollectionContext {
+    /** The render fills its container rather than sitting at a fixed width. */
+    fluid?: boolean;
+}
+/** A pack's collected styles, opaque to the SDK. */
+export type PrimitiveStyleCollector = object;
+/**
+ * The types a pack binds once and writes every primitive against: the palette
+ * its frames supply, the context its `react` renderers receive, the collector
+ * its `collectStyles` hooks mutate, and the Slack payload and collector types.
+ *
+ * Extend {@link DefaultPackTypes} and narrow only what the pack needs:
+ *
+ * ```ts
+ * interface SlidesPackTypes extends DefaultPackTypes {
+ *   theme: SlideTheme;
+ *   context: SlideRenderContext;
+ * }
+ * ```
+ */
+export interface PackTypes {
+    theme: unknown;
+    context: unknown;
+    collector: PrimitiveStyleCollector;
+    slackBlock: unknown;
+    slackCollector: unknown;
+}
+/** {@link PackTypes} as the sdk itself binds them, and the default everywhere. */
+export interface DefaultPackTypes extends PackTypes {
+    theme: unknown;
+    context: PrimitiveRenderContext;
+    collector: PrimitiveStyleCollector;
+    slackBlock: SlackBlock;
+    slackCollector: SlackAssetCollector;
+}
+/**
+ * Each surface's renderer signature: the env bag it receives beyond the node,
+ * and what it returns.
+ *
+ * Written out per surface rather than derived through an indexed access. A bag
+ * is additive: a new extra on a surface is not an arity break. {@link Renderer}
+ * indexes this table for the dispatcher cast; {@link Renderers} does not.
+ */
+export interface SurfaceMap<T extends PackTypes = DefaultPackTypes> {
+    react: {
+        env: {
+            context: T['context'];
+            scope: RenderScope<T>;
+            /**
+             * The frame's resolved palette, when this render is reached through the
+             * `snapshot` surface. A bare `react`/`html` render has no {@link Frame} to
+             * resolve one from, so it is absent there — a pack that needs a
+             * literal color outside `snapshot` still goes through `context`.
+             */
+            theme?: T['theme'];
+        };
+        output: ReactNode;
+    };
+    /**
+     * Identical to `react`, and served by the same renderer: an image backend
+     * lays out the pack's DOM tree and stylesheet rather than a second tree
+     * authored for it. The surface stays separate so a node can be hidden from
+     * snapshots alone, and so a {@link Frame} has something to draw inside.
+     */
+    snapshot: {
+        env: {
+            context: T['context'];
+            scope: RenderScope<T>;
+            /** The frame's resolved palette for this render's mode; see `react.env.theme`. */
+            theme?: T['theme'];
+        };
+        output: ReactNode;
+    };
+    text: {
+        env: {
+            scope: RenderScope<T>;
+        };
+        output: string;
+    };
+    /** Content built with `md`, escaped where it lands; authored Markdown source goes through `md.authored`. */
+    markdown: {
+        env: {
+            scope: RenderScope<T>;
+        };
+        output: MarkdownContent;
+    };
+    /**
+     * Returns one payload or several, so a primitive need not wrap a single
+     * payload in an array.
+     */
+    slack: {
+        env: {
+            collector?: T['slackCollector'];
+            scope: RenderScope<T>;
+        };
+        output: T['slackBlock'] | readonly T['slackBlock'][];
+    };
+}
+/**
+ * The dispatcher a renderer is given so a container can recurse into a child
+ * owned by another pack. Erased to {@link PrimitiveNode}: a heterogeneous
+ * inventory has no single node type to name.
+ *
+ * Passed as `scope` on every renderer's env bag. The dispatcher's own named
+ * methods stay positional.
+ */
+export interface RenderScope<T extends PackTypes = DefaultPackTypes> {
+    readonly definitions: readonly AnyPrimitiveDefinition[];
+    /** Throws for an unknown node type; a missing primitive is a bug, not a degradation. */
+    getDefinition(node: PrimitiveNode): AnyPrimitiveDefinition;
+    /** `undefined` when the node is hidden from `surface`, `sanitize` drops it, or its primitive declares no renderer for `surface`. */
+    renderOn<S extends SurfaceName>(surface: S, node: PrimitiveNode, extras: Omit<SurfaceMap<T>[S]['env'], 'scope'>): SurfaceMap<T>[S]['output'] | undefined;
+    renderReact(node: PrimitiveNode, context?: T['context']): ReactNode;
+    collectStyles(node: PrimitiveNode, styles: PrimitiveStyleCollector, context: PrimitiveStyleCollectionContext): void;
+    renderText(node: PrimitiveNode): string;
+    renderMarkdown(node: PrimitiveNode): string;
+    /** A child as content, for a container building with `md`. */
+    renderMarkdownContent(node: PrimitiveNode): MarkdownContent;
+    /** Empty when the node is hidden from `slack`, `sanitize` drops it, or its renderer returns nothing; a node with no `slack` renderer degrades through its markdown. */
+    renderSlack(node: PrimitiveNode, collector?: T['slackCollector']): readonly T['slackBlock'][];
+    /** `0` when the node is hidden from `snapshot` or its primitive declares no `metrics.snapshotHeight`. */
+    estimateSnapshotHeight(node: PrimitiveNode): number;
+    /** Appends schema failures under `path` to `errors`, each naming `node`'s type. */
+    validate(node: PrimitiveNode, path: string, errors: ValidationError[]): void;
+}
+/**
+ * One surface's renderer for one node type, per {@link SurfaceMap}.
+ *
+ * Indexes the env bag. Do not use this to type the renderers map: the
+ * written-out signatures on {@link Renderers} are what keep the bags checked
+ * per surface.
+ */
+export type Renderer<TNode extends PrimitiveNode, S extends SurfaceName, T extends PackTypes = DefaultPackTypes> = (node: TNode, env: SurfaceMap<T>[S]['env']) => SurfaceMap<T>[S]['output'];
+/**
+ * The surface a pack may declare beyond the mandatory three.
+ *
+ * Only `slack`, and even that stays optional per primitive: the dispatcher
+ * converts the mandatory markdown to Block Kit, so a missing Slack renderer
+ * degrades rather than disappearing. `snapshot` is not here because no primitive
+ * implements it — the surface reuses `react`.
+ */
+export declare const OPTIONAL_SURFACES: readonly ["slack"];
+/** One of the {@link OPTIONAL_SURFACES}. */
+export type OptionalSurface = (typeof OPTIONAL_SURFACES)[number];
+/**
+ * One renderer per surface a primitive implements.
+ *
+ * `react`, `text`, and `markdown` are always required: those three are what
+ * make "every composition degrades" true. `react` serves the `snapshot` surface
+ * too, so targeting images costs a primitive nothing.
+ *
+ * `slack` is declared method-style deliberately: method parameters are checked
+ * bivariantly, which is what lets a pack narrow the collector's node type.
+ */
+export interface Renderers<TNode extends PrimitiveNode, T extends PackTypes = DefaultPackTypes> {
+    react(node: TNode, env: {
+        context: T['context'];
+        scope: RenderScope<T>;
+        /** See {@link SurfaceMap.react}'s `env.theme`. */
+        theme?: T['theme'];
+    }): ReactNode;
+    text(node: TNode, env: {
+        scope: RenderScope<T>;
+    }): string;
+    markdown(node: TNode, env: {
+        scope: RenderScope<T>;
+    }): MarkdownContent;
+    slack?(node: TNode, env: {
+        collector?: T['slackCollector'];
+        scope: RenderScope<T>;
+    }): T['slackBlock'] | readonly T['slackBlock'][];
+}
+/**
+ * Measurements a frame can ask of a node before drawing it.
+ *
+ * `snapshotHeight` is optional. The height estimate is `0` when it is missing, so
+ * a frame that sums node heights sizes short.
+ */
+export interface PrimitiveMetrics<TNode extends PrimitiveNode> {
+    /** The node's drawn height in pixels at the frame's width. */
+    snapshotHeight?: (node: TNode) => number;
+}
+/**
+ * Every primitive's schema is an object schema, because {@link definePrimitive}
+ * extends it with `id` and `surfaces` and the composition builds a
+ * `z.discriminatedUnion('type', …)` over them. Typed as `ZodObject` rather
+ * than `ZodType<unknown>` so a union or intersection schema is a compile
+ * error at the definition, not a runtime failure at the first `.extend()`.
+ * Zod 4 types `z.object().superRefine(…)` as a `ZodObject` and preserves the
+ * refinement through `.extend()`, so top-level refinements are unaffected.
+ */
+export type PrimitiveSchema = ZodObject;
+/**
+ * The child-ref shape a primitive definition's own `children` returns.
+ *
+ * {@link ChildNodeRef} stays erased (`node: unknown`) because
+ * `createChildNodeWalker` mixes children from every primitive type in the
+ * runtime into one map and cannot name a single node type for them. A single
+ * definition has no such excuse: its `children` should not type-check
+ * against `unknown` and let something that is not a {@link PrimitiveNode} —
+ * `null`, for instance — silently disappear from every tree walk.
+ */
+export interface PrimitiveChildRef extends ChildNodeRef {
+    node: PrimitiveNode;
+}
+/**
+ * One primitive: its node type, schema, catalog entry, and a renderer per
+ * surface. The unit of vocabulary, and what {@link definePrimitive} takes.
+ *
+ * `T` is the pack's {@link PackTypes}, bound once with
+ * {@link definePrimitiveFor} so each primitive names only `TNode`.
+ */
+export interface PrimitiveDefinition<TNode extends PrimitiveNode, T extends PackTypes = DefaultPackTypes, TSchema extends PrimitiveSchema = PrimitiveSchema> {
+    /** The node's discriminant, and the key this primitive occupies in an inventory. */
+    type: TNode['type'];
+    /** How the authoring prompt describes this primitive to the model. */
+    catalog: PrimitiveCatalogEntry;
+    /** Host-facing glyph, never shown to the model. Absent means the host supplies its own. */
+    icon?: PrimitiveIcon;
+    /**
+     * Driven by the conformance harness, bare or named; read them with
+     * `exampleNodes` or `primitiveExamples`. The catalog `example` is what the
+     * prompt shows.
+     */
+    examples: readonly (TNode | PrimitiveExample<TNode>)[];
+    /**
+     * This primitive on its own. A container declares
+     * {@link PrimitiveDefinition.schemaFor} as well, and uses
+     * {@link unresolvedBodyNodeSchema} in the child slot here.
+     */
+    schema: TSchema;
+    /**
+     * A container's schema, bound to the body-node union of the composition it is
+     * being built into.
+     *
+     * Declaring the shape and letting each composition supply its own union is
+     * what lets one primitive appear in two runtimes with different inventories:
+     * `z.lazy` memoizes per instance, and an instance built here belongs to
+     * exactly one union.
+     */
+    schemaFor?: (bodyNodeSchema: ZodType<unknown>) => PrimitiveSchema;
+    /** One function per surface; `react` serves `snapshot` as well. */
+    renderers: Renderers<TNode, T>;
+    /** Sizing a frame can ask for before drawing. Absent means it cannot be measured. */
+    metrics?: PrimitiveMetrics<TNode>;
+    /**
+     * Render-time URL trust, the second of the two layers in `validate/url.ts`.
+     *
+     * Returning `null` drops the node. Applied even to an unvalidated node, so a
+     * renderer invoked directly still cannot emit an unsafe URL.
+     */
+    sanitize?: (node: TNode) => TNode | null;
+    /**
+     * Nested nodes, for containers, in the order the `react` renderer draws
+     * them; `findNodeElementPairs` relies on it. Absent means a leaf.
+     */
+    children?: (node: TNode) => readonly PrimitiveChildRef[];
+    /**
+     * True when this node produces surface output of its own, not only via
+     * {@link PrimitiveDefinition.children}. A non-empty `children` result is
+     * otherwise the complete source of rendered content, so a hybrid container
+     * that still owns string fields returns true to keep rendering when every
+     * nested node is hidden from the surface.
+     */
+    hasOwnContent?: (node: TNode) => boolean;
+    /** Contributes this node's CSS by mutating `styles`, once per node per render. */
+    collectStyles?: (node: TNode, env: {
+        styles: T['collector'];
+        context: PrimitiveStyleCollectionContext;
+    }) => void;
+}
+/**
+ * {@link PrimitiveDefinition} with every type parameter erased, and the form an
+ * inventory is stored in.
+ *
+ * A heterogeneous pack has no single `TNode` to be generic over, so the
+ * renderers degrade to `unknown` here.
+ *
+ * Each field carries the same contract as its {@link PrimitiveDefinition}
+ * counterpart; only the types are erased.
+ */
+export interface AnyPrimitiveDefinition {
+    type: string;
+    catalog: PrimitiveCatalogEntry;
+    icon?: PrimitiveIcon;
+    examples: readonly (PrimitiveNode | PrimitiveExample)[];
+    schema: PrimitiveSchema;
+    schemaFor?: (bodyNodeSchema: ZodType<unknown>) => PrimitiveSchema;
+    renderers: Record<'react' | 'text' | 'markdown', unknown> & Partial<Record<'slack', unknown>>;
+    metrics?: {
+        snapshotHeight?: unknown;
+    };
+    sanitize?: unknown;
+    children?: unknown;
+    hasOwnContent?: unknown;
+    collectStyles?: unknown;
+}
+/** Parses `node` against `schema`, appending path-prefixed messages to `errors`. */
+export declare const validateWithSchema: (schema: PrimitiveSchema, node: unknown, path: string, errors: ValidationError[]) => void;
+/** The `id` every node may carry, unique within a composition. */
+export declare const bodyNodeIdSchema: z.ZodString;
+/** The `surfaces` allowlist on a node. Absent means every surface; empty is rejected. */
+export declare const bodyNodeSurfacesSchema: z.ZodArray<z.ZodEnum<{
+    react: "react";
+    snapshot: "snapshot";
+    text: "text";
+    markdown: "markdown";
+    slack: "slack";
+}>>;
+/**
+ * The child slot in a container's standalone {@link PrimitiveDefinition.schema},
+ * where no body-node union is available.
+ *
+ * Deliberately permissive rather than `z.unknown()`: it still rejects a child
+ * that is not a node at all, which is the error worth catching without an
+ * inventory. Anything that depends on *which* types are legal — the validator,
+ * the parser, the JSON Schema projection — goes through
+ * {@link PrimitiveDefinition.schemaFor} and sees the real union.
+ */
+export declare const unresolvedBodyNodeSchema: z.ZodObject<{
+    type: z.ZodString;
+}, z.core.$loose>;
+/**
+ * Declares one primitive, extending its schema with the `id` and `surfaces`
+ * fields every node carries, and closing it to unknown keys so a node is held
+ * to the same rule as the composition root and the JSON Schema an agent reads.
+ * A schema with its own catchall (`z.looseObject`) keeps it.
+ *
+ * A pack normally calls the form {@link definePrimitiveFor} binds to its own
+ * {@link PackTypes}, so each primitive names only `TNode`.
+ */
+export declare const definePrimitive: <TNode extends PrimitiveNode, T extends PackTypes = DefaultPackTypes, TSchema extends PrimitiveSchema = PrimitiveSchema>(definition: PrimitiveDefinition<TNode, T, TSchema>) => PrimitiveDefinition<TNode, T, WithNodeFields<TSchema>>;
+/**
+ * {@link definePrimitive} bound to one pack's {@link PackTypes}.
+ *
+ * ```ts
+ * const define = definePrimitiveFor<SlidesPackTypes>();
+ * export const note = define({ type: 'note', … });
+ * ```
+ */
+export declare const definePrimitiveFor: <T extends PackTypes>() => <TNode extends PrimitiveNode, TSchema extends PrimitiveSchema = PrimitiveSchema>(definition: PrimitiveDefinition<TNode, T, TSchema>) => PrimitiveDefinition<TNode, T, WithNodeFields<TSchema>>;
+/**
+ * `.extend()` on a generic `ZodObject` widens the shape to `any`, so the
+ * return type is rebuilt from `TSchema`'s shape. The brand on a field schema
+ * stays on that same object at runtime.
+ */
+export type WithNodeFields<TSchema extends PrimitiveSchema> = TSchema extends ZodObject<infer Shape> ? ZodObject<Shape & {
+    id: ReturnType<typeof bodyNodeIdSchema.optional>;
+    surfaces: ReturnType<typeof bodyNodeSurfacesSchema.optional>;
+}> : PrimitiveSchema;
+//# sourceMappingURL=primitive_module.d.ts.map

package/dist/define/primitive_module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive_module.d.ts","sourceRoot":"","sources":["../../src/define/primitive_module.ts"],"names":[],"mappings":"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"}

package/dist/define/primitive_module.js

@@ -0,0 +1,112 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { z } from 'zod';
+import { SURFACE_NAMES, } from '../composition/body_node_base.js';
+import { ISOMER_ERROR_CODES, IsomerError } from '../composition/error.js';
+import { formatZodIssues, oneOf } from './zod_format.js';
+import { requiredString } from './zod_helpers.js';
+/**
+ * The surface a pack may declare beyond the mandatory three.
+ *
+ * Only `slack`, and even that stays optional per primitive: the dispatcher
+ * converts the mandatory markdown to Block Kit, so a missing Slack renderer
+ * degrades rather than disappearing. `snapshot` is not here because no primitive
+ * implements it — the surface reuses `react`.
+ */
+export const OPTIONAL_SURFACES = [
+    'slack',
+];
+/** Parses `node` against `schema`, appending path-prefixed messages to `errors`. */
+export const validateWithSchema = (schema, node, path, errors) => {
+    const result = schema.safeParse(node, { reportInput: true });
+    if (!result.success) {
+        errors.push(...formatZodIssues(result.error.issues, path));
+    }
+};
+/** The `id` every node may carry, unique within a composition. */
+export const bodyNodeIdSchema = requiredString('must be a non-empty string');
+/** The `surfaces` allowlist on a node. Absent means every surface; empty is rejected. */
+export const bodyNodeSurfacesSchema = z
+    .array(z.enum(SURFACE_NAMES, {
+    error: () => oneOf(SURFACE_NAMES),
+}))
+    .min(1, { error: 'must contain at least one surface' });
+/**
+ * The child slot in a container's standalone {@link PrimitiveDefinition.schema},
+ * where no body-node union is available.
+ *
+ * Deliberately permissive rather than `z.unknown()`: it still rejects a child
+ * that is not a node at all, which is the error worth catching without an
+ * inventory. Anything that depends on *which* types are legal — the validator,
+ * the parser, the JSON Schema projection — goes through
+ * {@link PrimitiveDefinition.schemaFor} and sees the real union.
+ */
+export const unresolvedBodyNodeSchema = z.looseObject({
+    type: requiredString('must be a non-empty string'),
+});
+/**
+ * Declares one primitive, extending its schema with the `id` and `surfaces`
+ * fields every node carries, and closing it to unknown keys so a node is held
+ * to the same rule as the composition root and the JSON Schema an agent reads.
+ * A schema with its own catchall (`z.looseObject`) keeps it.
+ *
+ * A pack normally calls the form {@link definePrimitiveFor} binds to its own
+ * {@link PackTypes}, so each primitive names only `TNode`.
+ */
+export const definePrimitive = (definition) => {
+    const { schemaFor } = definition;
+    return {
+        ...definition,
+        schema: withNodeFields(definition.schema),
+        // Both forms get the node fields, or a container would accept `id` and
+        // `surfaces` standalone and reject them inside a composition.
+        ...(schemaFor
+            ? {
+                schemaFor: (bodyNodeSchema) => withNodeFields(schemaFor(bodyNodeSchema)),
+            }
+            : {}),
+    };
+};
+/**
+ * {@link definePrimitive} bound to one pack's {@link PackTypes}.
+ *
+ * ```ts
+ * const define = definePrimitiveFor<SlidesPackTypes>();
+ * export const note = define({ type: 'note', … });
+ * ```
+ */
+export const definePrimitiveFor = () => (definition) => definePrimitive(definition);
+// Marks the field schemas `definePrimitive` adds. A schema derived from a
+// defined one shares them by reference, and `Symbol.for` matches across ESM and
+// CommonJS copies of the SDK.
+const NODE_FIELD = Symbol.for('elastic.isomer.node_field');
+const nodeField = (schema) => Object.defineProperty(schema, NODE_FIELD, { value: true });
+const NODE_FIELDS = {
+    id: nodeField(bodyNodeIdSchema.optional()),
+    surfaces: nodeField(bodyNodeSurfacesSchema.optional()),
+};
+const isNodeField = (schema) => {
+    let current = schema;
+    while (current && typeof current === 'object') {
+        if (Object.hasOwn(current, NODE_FIELD))
+            return true;
+        const { def } = current;
+        if (def?.type !== 'optional')
+            return false;
+        current = def.innerType;
+    }
+    return false;
+};
+const withNodeFields = (schema) => {
+    const reserved = Object.keys(NODE_FIELDS).find((field) => Object.hasOwn(schema.shape, field) && !isNodeField(schema.shape[field]));
+    if (reserved) {
+        throw new IsomerError(ISOMER_ERROR_CODES.RESERVED_NODE_FIELD, `definePrimitive: a primitive schema cannot declare \`${reserved}\`; every body node has it.`);
+    }
+    const extended = schema.extend(NODE_FIELDS);
+    return (schema.def.catchall === undefined ? extended.strict() : extended);
+};
+//# sourceMappingURL=primitive_module.js.map

package/dist/define/primitive_module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive_module.js","sourceRoot":"","sources":["../../src/define/primitive_module.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport type { ReactNode } from 'react';\nimport { z, type ZodObject, type ZodType } from 'zod';\n\nimport type { ActionEventRef } from '../composition/action_event';\nimport {\n  type ChildNodeRef,\n  SURFACE_NAMES,\n  type SurfaceName,\n} from '../composition/body_node_base';\nimport { ISOMER_ERROR_CODES, IsomerError } from '../composition/error';\nimport type { PrimitiveNode } from '../composition/node';\nimport type { ValidationError } from '../composition/validation_error';\n\nimport type { MarkdownContent } from './markdown_content';\nimport type { PrimitiveExample } from './primitive_example';\nimport type { PrimitiveIcon } from './primitive_icon';\nimport type { SlackAssetCollector } from './slack_assets';\nimport type { SlackBlock } from './slack_blocks';\nimport { formatZodIssues, oneOf } from './zod_format';\nimport { requiredString } from './zod_helpers';\n\nexport type { PrimitiveNode };\n\n/**\n * A primitive's entry in the catalog the authoring prompt is built from.\n *\n * Written for the model rather than for a developer: `useWhen` and `avoidWhen`\n * are what steer it away from reaching for the wrong primitive. `name` is the\n * one host-facing field, and the prompt never prints it.\n */\nexport interface PrimitiveCatalogEntry {\n  type: string;\n  /** Short name a host shows for the primitive, e.g. `Stat group`. Absent means the host derives one from `type`. */\n  name?: string;\n  /** One line on what the primitive is for, in the model's voice. */\n  purpose: string;\n  /** Situations that call for this primitive. Phrase each as a user intent, not a shape. */\n  useWhen: string[];\n  /** Situations that look like a fit but are not, naming the primitive to reach for instead. */\n  avoidWhen: string[];\n  /** A node literal the authoring prompt inlines under this primitive. */\n  example: unknown;\n}\n\n/** A style a renderer asks for by name, resolved to a class by the host's adapter. */\nexport interface StyleHandle {\n  /** Stable lookup key. The adapter's map is keyed on this. */\n  key: string;\n  /** Debug-facing label, which an adapter may fold into a generated class name. */\n  readableName: string;\n}\n\n/** Dotted path into a pack's theme tokens, e.g. `colors.text.subdued`. */\nexport type ThemeTokenPath = string;\n\n/**\n * The sdk's own render context, and {@link DefaultPackTypes.context}.\n *\n * A pack with real theme tokens or a richer style-handle type declares its\n * own context in its {@link PackTypes}; {@link StyledRenderContext} is the\n * sdk's own extension. The bag is what lets a pack narrow without\n * re-declaring everything that mentions a context.\n */\nexport interface PrimitiveRenderContext {\n  /**\n   * The progressive enhancements this render may assume, by id. A set rather\n   * than a field per feature so adding an enhancement costs no plumbing:\n   * containers forward the whole context, and a renderer asks\n   * `context.enhancements?.has('tableSort')`.\n   *\n   * Empty or absent is the baseline every host can render, so a renderer must\n   * still answer the question on its own. See `docs/rendering.md`.\n   */\n  enhancements?: ReadonlySet<string>;\n  /** Turns on `nodeAnchor` outside an HTML surface render, on the React and `snapshot` surfaces; inside one, the surface decides. */\n  anchors?: boolean;\n  /** Raises an interaction for the host to route. Absent means render non-interactively. */\n  onEvent?: (event: ActionEventRef) => void;\n}\n\n/**\n * The render-context argument, optional only when omitting it is sound.\n *\n * The sdk's own {@link PrimitiveRenderContext} has no required field, so `{}`\n * is a complete value and a caller may leave it out. A pack that narrows the\n * context with a required member makes the argument mandatory.\n */\nexport type ReactContextArg<TContext> =\n  Record<string, never> extends TContext\n    ? [context?: TContext]\n    : [context: TContext];\n\n/**\n * {@link PrimitiveRenderContext} plus the CSS-in-JS hooks an HTML style adapter\n * supplies. A pack that styles differently uses its own `TContext` instead.\n */\nexport interface StyledRenderContext extends PrimitiveRenderContext {\n  /** Resolves handles to a `className`. Absent means the host supplies no styling. */\n  resolveClassName?: (...handles: StyleHandle[]) => string;\n  /** Resolves a theme token to a CSS variable reference. Absent means inline the literal value. */\n  cssVarRef?: (path: ThemeTokenPath) => `var(--${string})`;\n}\n\n/** Passed to a primitive's style collector so it can vary CSS by layout mode. */\nexport interface PrimitiveStyleCollectionContext {\n  /** The render fills its container rather than sitting at a fixed width. */\n  fluid?: boolean;\n}\n\n/** A pack's collected styles, opaque to the SDK. */\nexport type PrimitiveStyleCollector = object;\n\n/**\n * The types a pack binds once and writes every primitive against: the palette\n * its frames supply, the context its `react` renderers receive, the collector\n * its `collectStyles` hooks mutate, and the Slack payload and collector types.\n *\n * Extend {@link DefaultPackTypes} and narrow only what the pack needs:\n *\n * ```ts\n * interface SlidesPackTypes extends DefaultPackTypes {\n *   theme: SlideTheme;\n *   context: SlideRenderContext;\n * }\n * ```\n */\nexport interface PackTypes {\n  theme: unknown;\n  context: unknown;\n  collector: PrimitiveStyleCollector;\n  slackBlock: unknown;\n  slackCollector: unknown;\n}\n\n/** {@link PackTypes} as the sdk itself binds them, and the default everywhere. */\nexport interface DefaultPackTypes extends PackTypes {\n  theme: unknown;\n  context: PrimitiveRenderContext;\n  collector: PrimitiveStyleCollector;\n  slackBlock: SlackBlock;\n  slackCollector: SlackAssetCollector;\n}\n\n/**\n * Each surface's renderer signature: the env bag it receives beyond the node,\n * and what it returns.\n *\n * Written out per surface rather than derived through an indexed access. A bag\n * is additive: a new extra on a surface is not an arity break. {@link Renderer}\n * indexes this table for the dispatcher cast; {@link Renderers} does not.\n */\nexport interface SurfaceMap<T extends PackTypes = DefaultPackTypes> {\n  react: {\n    env: {\n      context: T['context'];\n      scope: RenderScope<T>;\n      /**\n       * The frame's resolved palette, when this render is reached through the\n       * `snapshot` surface. A bare `react`/`html` render has no {@link Frame} to\n       * resolve one from, so it is absent there — a pack that needs a\n       * literal color outside `snapshot` still goes through `context`.\n       */\n      theme?: T['theme'];\n    };\n    output: ReactNode;\n  };\n  /**\n   * Identical to `react`, and served by the same renderer: an image backend\n   * lays out the pack's DOM tree and stylesheet rather than a second tree\n   * authored for it. The surface stays separate so a node can be hidden from\n   * snapshots alone, and so a {@link Frame} has something to draw inside.\n   */\n  snapshot: {\n    env: {\n      context: T['context'];\n      scope: RenderScope<T>;\n      /** The frame's resolved palette for this render's mode; see `react.env.theme`. */\n      theme?: T['theme'];\n    };\n    output: ReactNode;\n  };\n  text: {\n    env: {\n      scope: RenderScope<T>;\n    };\n    output: string;\n  };\n  /** Content built with `md`, escaped where it lands; authored Markdown source goes through `md.authored`. */\n  markdown: {\n    env: {\n      scope: RenderScope<T>;\n    };\n    output: MarkdownContent;\n  };\n  /**\n   * Returns one payload or several, so a primitive need not wrap a single\n   * payload in an array.\n   */\n  slack: {\n    env: {\n      collector?: T['slackCollector'];\n      scope: RenderScope<T>;\n    };\n    output: T['slackBlock'] | readonly T['slackBlock'][];\n  };\n}\n\n/**\n * The dispatcher a renderer is given so a container can recurse into a child\n * owned by another pack. Erased to {@link PrimitiveNode}: a heterogeneous\n * inventory has no single node type to name.\n *\n * Passed as `scope` on every renderer's env bag. The dispatcher's own named\n * methods stay positional.\n */\nexport interface RenderScope<T extends PackTypes = DefaultPackTypes> {\n  readonly definitions: readonly AnyPrimitiveDefinition[];\n  /** Throws for an unknown node type; a missing primitive is a bug, not a degradation. */\n  getDefinition(node: PrimitiveNode): AnyPrimitiveDefinition;\n  /** `undefined` when the node is hidden from `surface`, `sanitize` drops it, or its primitive declares no renderer for `surface`. */\n  renderOn<S extends SurfaceName>(\n    surface: S,\n    node: PrimitiveNode,\n    extras: Omit<SurfaceMap<T>[S]['env'], 'scope'>\n  ): SurfaceMap<T>[S]['output'] | undefined;\n  renderReact(node: PrimitiveNode, context?: T['context']): ReactNode;\n  collectStyles(\n    node: PrimitiveNode,\n    styles: PrimitiveStyleCollector,\n    context: PrimitiveStyleCollectionContext\n  ): void;\n  renderText(node: PrimitiveNode): string;\n  renderMarkdown(node: PrimitiveNode): string;\n  /** A child as content, for a container building with `md`. */\n  renderMarkdownContent(node: PrimitiveNode): MarkdownContent;\n  /** Empty when the node is hidden from `slack`, `sanitize` drops it, or its renderer returns nothing; a node with no `slack` renderer degrades through its markdown. */\n  renderSlack(\n    node: PrimitiveNode,\n    collector?: T['slackCollector']\n  ): readonly T['slackBlock'][];\n  /** `0` when the node is hidden from `snapshot` or its primitive declares no `metrics.snapshotHeight`. */\n  estimateSnapshotHeight(node: PrimitiveNode): number;\n  /** Appends schema failures under `path` to `errors`, each naming `node`'s type. */\n  validate(node: PrimitiveNode, path: string, errors: ValidationError[]): void;\n}\n\n/**\n * One surface's renderer for one node type, per {@link SurfaceMap}.\n *\n * Indexes the env bag. Do not use this to type the renderers map: the\n * written-out signatures on {@link Renderers} are what keep the bags checked\n * per surface.\n */\nexport type Renderer<\n  TNode extends PrimitiveNode,\n  S extends SurfaceName,\n  T extends PackTypes = DefaultPackTypes,\n> = (node: TNode, env: SurfaceMap<T>[S]['env']) => SurfaceMap<T>[S]['output'];\n\n/**\n * The surface a pack may declare beyond the mandatory three.\n *\n * Only `slack`, and even that stays optional per primitive: the dispatcher\n * converts the mandatory markdown to Block Kit, so a missing Slack renderer\n * degrades rather than disappearing. `snapshot` is not here because no primitive\n * implements it — the surface reuses `react`.\n */\nexport const OPTIONAL_SURFACES = [\n  'slack',\n] as const satisfies readonly SurfaceName[];\n\n/** One of the {@link OPTIONAL_SURFACES}. */\nexport type OptionalSurface = (typeof OPTIONAL_SURFACES)[number];\n\n/**\n * One renderer per surface a primitive implements.\n *\n * `react`, `text`, and `markdown` are always required: those three are what\n * make \"every composition degrades\" true. `react` serves the `snapshot` surface\n * too, so targeting images costs a primitive nothing.\n *\n * `slack` is declared method-style deliberately: method parameters are checked\n * bivariantly, which is what lets a pack narrow the collector's node type.\n */\nexport interface Renderers<\n  TNode extends PrimitiveNode,\n  T extends PackTypes = DefaultPackTypes,\n> {\n  react(\n    node: TNode,\n    env: {\n      context: T['context'];\n      scope: RenderScope<T>;\n      /** See {@link SurfaceMap.react}'s `env.theme`. */\n      theme?: T['theme'];\n    }\n  ): ReactNode;\n  text(\n    node: TNode,\n    env: {\n      scope: RenderScope<T>;\n    }\n  ): string;\n  markdown(\n    node: TNode,\n    env: {\n      scope: RenderScope<T>;\n    }\n  ): MarkdownContent;\n  slack?(\n    node: TNode,\n    env: {\n      collector?: T['slackCollector'];\n      scope: RenderScope<T>;\n    }\n  ): T['slackBlock'] | readonly T['slackBlock'][];\n}\n\n/**\n * Measurements a frame can ask of a node before drawing it.\n *\n * `snapshotHeight` is optional. The height estimate is `0` when it is missing, so\n * a frame that sums node heights sizes short.\n */\nexport interface PrimitiveMetrics<TNode extends PrimitiveNode> {\n  /** The node's drawn height in pixels at the frame's width. */\n  snapshotHeight?: (node: TNode) => number;\n}\n\n/**\n * Every primitive's schema is an object schema, because {@link definePrimitive}\n * extends it with `id` and `surfaces` and the composition builds a\n * `z.discriminatedUnion('type', …)` over them. Typed as `ZodObject` rather\n * than `ZodType<unknown>` so a union or intersection schema is a compile\n * error at the definition, not a runtime failure at the first `.extend()`.\n * Zod 4 types `z.object().superRefine(…)` as a `ZodObject` and preserves the\n * refinement through `.extend()`, so top-level refinements are unaffected.\n */\nexport type PrimitiveSchema = ZodObject;\n\n/**\n * The child-ref shape a primitive definition's own `children` returns.\n *\n * {@link ChildNodeRef} stays erased (`node: unknown`) because\n * `createChildNodeWalker` mixes children from every primitive type in the\n * runtime into one map and cannot name a single node type for them. A single\n * definition has no such excuse: its `children` should not type-check\n * against `unknown` and let something that is not a {@link PrimitiveNode} —\n * `null`, for instance — silently disappear from every tree walk.\n */\nexport interface PrimitiveChildRef extends ChildNodeRef {\n  node: PrimitiveNode;\n}\n\n/**\n * One primitive: its node type, schema, catalog entry, and a renderer per\n * surface. The unit of vocabulary, and what {@link definePrimitive} takes.\n *\n * `T` is the pack's {@link PackTypes}, bound once with\n * {@link definePrimitiveFor} so each primitive names only `TNode`.\n */\nexport interface PrimitiveDefinition<\n  TNode extends PrimitiveNode,\n  T extends PackTypes = DefaultPackTypes,\n  TSchema extends PrimitiveSchema = PrimitiveSchema,\n> {\n  /** The node's discriminant, and the key this primitive occupies in an inventory. */\n  type: TNode['type'];\n  /** How the authoring prompt describes this primitive to the model. */\n  catalog: PrimitiveCatalogEntry;\n  /** Host-facing glyph, never shown to the model. Absent means the host supplies its own. */\n  icon?: PrimitiveIcon;\n  /**\n   * Driven by the conformance harness, bare or named; read them with\n   * `exampleNodes` or `primitiveExamples`. The catalog `example` is what the\n   * prompt shows.\n   */\n  examples: readonly (TNode | PrimitiveExample<TNode>)[];\n  /**\n   * This primitive on its own. A container declares\n   * {@link PrimitiveDefinition.schemaFor} as well, and uses\n   * {@link unresolvedBodyNodeSchema} in the child slot here.\n   */\n  schema: TSchema;\n  /**\n   * A container's schema, bound to the body-node union of the composition it is\n   * being built into.\n   *\n   * Declaring the shape and letting each composition supply its own union is\n   * what lets one primitive appear in two runtimes with different inventories:\n   * `z.lazy` memoizes per instance, and an instance built here belongs to\n   * exactly one union.\n   */\n  schemaFor?: (bodyNodeSchema: ZodType<unknown>) => PrimitiveSchema;\n  /** One function per surface; `react` serves `snapshot` as well. */\n  renderers: Renderers<TNode, T>;\n  /** Sizing a frame can ask for before drawing. Absent means it cannot be measured. */\n  metrics?: PrimitiveMetrics<TNode>;\n  /**\n   * Render-time URL trust, the second of the two layers in `validate/url.ts`.\n   *\n   * Returning `null` drops the node. Applied even to an unvalidated node, so a\n   * renderer invoked directly still cannot emit an unsafe URL.\n   */\n  sanitize?: (node: TNode) => TNode | null;\n  /**\n   * Nested nodes, for containers, in the order the `react` renderer draws\n   * them; `findNodeElementPairs` relies on it. Absent means a leaf.\n   */\n  children?: (node: TNode) => readonly PrimitiveChildRef[];\n  /**\n   * True when this node produces surface output of its own, not only via\n   * {@link PrimitiveDefinition.children}. A non-empty `children` result is\n   * otherwise the complete source of rendered content, so a hybrid container\n   * that still owns string fields returns true to keep rendering when every\n   * nested node is hidden from the surface.\n   */\n  hasOwnContent?: (node: TNode) => boolean;\n  /** Contributes this node's CSS by mutating `styles`, once per node per render. */\n  collectStyles?: (\n    node: TNode,\n    env: { styles: T['collector']; context: PrimitiveStyleCollectionContext }\n  ) => void;\n}\n\n/**\n * {@link PrimitiveDefinition} with every type parameter erased, and the form an\n * inventory is stored in.\n *\n * A heterogeneous pack has no single `TNode` to be generic over, so the\n * renderers degrade to `unknown` here.\n *\n * Each field carries the same contract as its {@link PrimitiveDefinition}\n * counterpart; only the types are erased.\n */\nexport interface AnyPrimitiveDefinition {\n  type: string;\n  catalog: PrimitiveCatalogEntry;\n  icon?: PrimitiveIcon;\n  examples: readonly (PrimitiveNode | PrimitiveExample)[];\n  schema: PrimitiveSchema;\n  schemaFor?: (bodyNodeSchema: ZodType<unknown>) => PrimitiveSchema;\n  renderers: Record<'react' | 'text' | 'markdown', unknown> &\n    Partial<Record<'slack', unknown>>;\n  metrics?: {\n    snapshotHeight?: unknown;\n  };\n  sanitize?: unknown;\n  children?: unknown;\n  hasOwnContent?: unknown;\n  collectStyles?: unknown;\n}\n\n/** Parses `node` against `schema`, appending path-prefixed messages to `errors`. */\nexport const validateWithSchema = (\n  schema: PrimitiveSchema,\n  node: unknown,\n  path: string,\n  errors: ValidationError[]\n): void => {\n  const result = schema.safeParse(node, { reportInput: true });\n  if (!result.success) {\n    errors.push(...formatZodIssues(result.error.issues, path));\n  }\n};\n\n/** The `id` every node may carry, unique within a composition. */\nexport const bodyNodeIdSchema = requiredString('must be a non-empty string');\n\n/** The `surfaces` allowlist on a node. Absent means every surface; empty is rejected. */\nexport const bodyNodeSurfacesSchema = z\n  .array(\n    z.enum(SURFACE_NAMES, {\n      error: () => oneOf(SURFACE_NAMES),\n    })\n  )\n  .min(1, { error: 'must contain at least one surface' });\n\n/**\n * The child slot in a container's standalone {@link PrimitiveDefinition.schema},\n * where no body-node union is available.\n *\n * Deliberately permissive rather than `z.unknown()`: it still rejects a child\n * that is not a node at all, which is the error worth catching without an\n * inventory. Anything that depends on *which* types are legal — the validator,\n * the parser, the JSON Schema projection — goes through\n * {@link PrimitiveDefinition.schemaFor} and sees the real union.\n */\nexport const unresolvedBodyNodeSchema = z.looseObject({\n  type: requiredString('must be a non-empty string'),\n});\n\n/**\n * Declares one primitive, extending its schema with the `id` and `surfaces`\n * fields every node carries, and closing it to unknown keys so a node is held\n * to the same rule as the composition root and the JSON Schema an agent reads.\n * A schema with its own catchall (`z.looseObject`) keeps it.\n *\n * A pack normally calls the form {@link definePrimitiveFor} binds to its own\n * {@link PackTypes}, so each primitive names only `TNode`.\n */\nexport const definePrimitive = <\n  TNode extends PrimitiveNode,\n  T extends PackTypes = DefaultPackTypes,\n  TSchema extends PrimitiveSchema = PrimitiveSchema,\n>(\n  definition: PrimitiveDefinition<TNode, T, TSchema>\n): PrimitiveDefinition<TNode, T, WithNodeFields<TSchema>> => {\n  const { schemaFor } = definition;\n  return {\n    ...definition,\n    schema: withNodeFields(definition.schema),\n    // Both forms get the node fields, or a container would accept `id` and\n    // `surfaces` standalone and reject them inside a composition.\n    ...(schemaFor\n      ? {\n          schemaFor: (bodyNodeSchema: ZodType<unknown>) =>\n            withNodeFields(schemaFor(bodyNodeSchema)),\n        }\n      : {}),\n  };\n};\n\n/**\n * {@link definePrimitive} bound to one pack's {@link PackTypes}.\n *\n * ```ts\n * const define = definePrimitiveFor<SlidesPackTypes>();\n * export const note = define({ type: 'note', … });\n * ```\n */\nexport const definePrimitiveFor =\n  <T extends PackTypes>() =>\n  <\n    TNode extends PrimitiveNode,\n    TSchema extends PrimitiveSchema = PrimitiveSchema,\n  >(\n    definition: PrimitiveDefinition<TNode, T, TSchema>\n  ): PrimitiveDefinition<TNode, T, WithNodeFields<TSchema>> =>\n    definePrimitive<TNode, T, TSchema>(definition);\n\n/**\n * `.extend()` on a generic `ZodObject` widens the shape to `any`, so the\n * return type is rebuilt from `TSchema`'s shape. The brand on a field schema\n * stays on that same object at runtime.\n */\nexport type WithNodeFields<TSchema extends PrimitiveSchema> =\n  TSchema extends ZodObject<infer Shape>\n    ? ZodObject<\n        Shape & {\n          id: ReturnType<typeof bodyNodeIdSchema.optional>;\n          surfaces: ReturnType<typeof bodyNodeSurfacesSchema.optional>;\n        }\n      >\n    : PrimitiveSchema;\n\n// Marks the field schemas `definePrimitive` adds. A schema derived from a\n// defined one shares them by reference, and `Symbol.for` matches across ESM and\n// CommonJS copies of the SDK.\nconst NODE_FIELD = Symbol.for('elastic.isomer.node_field');\n\nconst nodeField = <T extends ZodType>(schema: T): T =>\n  Object.defineProperty(schema, NODE_FIELD, { value: true });\n\nconst NODE_FIELDS = {\n  id: nodeField(bodyNodeIdSchema.optional()),\n  surfaces: nodeField(bodyNodeSurfacesSchema.optional()),\n};\n\nconst isNodeField = (schema: unknown): boolean => {\n  let current = schema;\n  while (current && typeof current === 'object') {\n    if (Object.hasOwn(current, NODE_FIELD)) return true;\n    const { def } = current as {\n      def?: { type?: string; innerType?: unknown };\n    };\n    if (def?.type !== 'optional') return false;\n    current = def.innerType;\n  }\n  return false;\n};\n\nconst withNodeFields = <TSchema extends PrimitiveSchema>(\n  schema: TSchema\n): WithNodeFields<TSchema> => {\n  const reserved = Object.keys(NODE_FIELDS).find(\n    (field) =>\n      Object.hasOwn(schema.shape, field) && !isNodeField(schema.shape[field])\n  );\n  if (reserved) {\n    throw new IsomerError(\n      ISOMER_ERROR_CODES.RESERVED_NODE_FIELD,\n      `definePrimitive: a primitive schema cannot declare \\`${reserved}\\`; every body node has it.`\n    );\n  }\n  const extended = schema.extend(NODE_FIELDS);\n  return (\n    schema.def.catchall === undefined ? extended.strict() : extended\n  ) as WithNodeFields<TSchema>;\n};\n"]}

package/dist/define/slack_assets.d.ts

@@ -0,0 +1,28 @@
+import type { PrimitiveNode } from '../composition/node.js';
+/**
+ * One image the host must upload before the message can be posted.
+ *
+ * The renderer is pure, so it emits `ref` as a placeholder and the host swaps
+ * in Slack's file id once the upload lands.
+ */
+export interface SlackAssetRequest<TNode extends PrimitiveNode = PrimitiveNode> {
+    /** Placeholder the render emits, which the host replaces with Slack's file id. */
+    ref: string;
+    /** The node to draw as an image, to be rendered on the `snapshot` surface. */
+    node: TNode;
+    /** Accessible description, required because Slack rejects an image block without one. */
+    altText: string;
+}
+/**
+ * Accumulates the {@link SlackAssetRequest}s a render produced.
+ *
+ * Opt-in: without a collector, a node that cannot draw inline degrades to text
+ * instead, so default output stays safe for callers that cannot upload files.
+ */
+export interface SlackAssetCollector<TNode extends PrimitiveNode = PrimitiveNode> {
+    /** Reserves a placeholder `ref` for `node` and records the request. */
+    allocate(node: TNode, altText: string): string;
+    /** In allocation order, so a host can upload and swap refs in one pass. */
+    readonly requests: readonly SlackAssetRequest<TNode>[];
+}
+//# sourceMappingURL=slack_assets.d.ts.map

package/dist/define/slack_assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack_assets.d.ts","sourceRoot":"","sources":["../../src/define/slack_assets.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAChC,KAAK,SAAS,aAAa,GAAG,aAAa;IAE3C,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,IAAI,EAAE,KAAK,CAAC;IACZ,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAClC,KAAK,SAAS,aAAa,GAAG,aAAa;IAE3C,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;CACxD"}