@elastic/isomer-sdk 0.0.0 → 0.1.0

package/dist/author/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/author/prompt.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 { oneLine } from '../composition/one_line';\nimport type { PrimitiveCatalogEntry } from '../define/primitive_module';\nimport type { PrimitiveGroup } from '../pack/primitive_pack';\n\ntype JsonSchema = Record<string, unknown>;\n\n/** Which authoring job the prompt frames for the model. */\nexport type AuthoringProfileId =\n  'general' | 'registered-view-router' | 'compose-from-primitives';\n\n/** Every {@link AuthoringProfileId}. */\nexport const AUTHORING_PROFILE_IDS: readonly AuthoringProfileId[] = [\n  'general',\n  'registered-view-router',\n  'compose-from-primitives',\n];\n\n/**\n * A registered view, declared structurally so this module does not import the\n * runtime. {@link RegisteredViewSummary} must stay assignable to this.\n */\nexport interface AuthoringViewSummary {\n  id: string;\n  title: string;\n  description?: string;\n  /** Natural-language queries the view answers, printed so the model can route by them. */\n  answers: readonly string[];\n  /** JSON Schema for the view's input, printed inline when present. */\n  inputSchema?: JsonSchema;\n}\n\n/** The pack-supplied material {@link buildAuthoringPrompt} assembles. */\nexport interface AuthoringPromptContext {\n  guide: string;\n  /** Absent or empty drops the `## Rules` section. */\n  rules?: string;\n  /** JSON Schema for a whole composition. Absent, or under the router profile, it is not inlined. */\n  schema?: JsonSchema;\n  /** Rendered as a bullet per entry, with its `useWhen`, `avoidWhen`, and `example`. */\n  primitives: readonly PrimitiveCatalogEntry[];\n  /** `'index'` lists each primitive's type and purpose only, for a host that serves the rest on request. */\n  catalog?: 'full' | 'index';\n  /** Headings an index sorts primitives under; a type in none is listed under \"Other\". */\n  groups?: readonly PrimitiveGroup[];\n  /**\n   * Extra host-supplied compositions beyond each primitive's catalog example.\n   * Trimmed to the profile's budget. An empty list drops `## Examples`.\n   */\n  examples: readonly unknown[];\n  /** Registered views the model can request by id. An empty list drops the section. */\n  views?: readonly AuthoringViewSummary[];\n  /** Defaults to `'# View authoring'`. */\n  heading?: string;\n  /** Replaces the profile's own framing sentence. */\n  intro?: string;\n}\n\nconst COMPOSE_INTRO_WITHOUT_SCHEMA =\n  'You compose views from scratch. Build a single JSON object that answers the question using only the primitives in the catalog below.';\n\nconst INDEX_INTRO =\n  'Each primitive is listed by type and purpose. Before using one, request its catalog entry and JSON Schema by type; compose only from primitives whose details you have.';\n\nconst PROFILE_INTROS: Record<AuthoringProfileId, string> = {\n  general:\n    'You author views: compact, host-portable operational displays expressed as a single JSON object. Route to a registered view when one answers the question; otherwise compose a view from the primitive catalog below.',\n  'registered-view-router':\n    'You route questions to registered views. Prefer an existing registered view whose answers index matches the question; request it by id with its input. Only fall back to composing a view when no registered view fits, using the catalog below.',\n  'compose-from-primitives':\n    'You compose views from scratch. Build a single JSON object that answers the question using only the primitives in the catalog below, and validate your output mentally against the JSON Schema before responding.',\n};\n\n/** Host-supplied composition examples kept after each primitive already shows its shape. */\nconst PROFILE_EXAMPLE_LIMITS: Record<AuthoringProfileId, number> = {\n  general: 1,\n  'registered-view-router': 0,\n  'compose-from-primitives': 1,\n};\n\nconst PROFILE_INCLUDES_SCHEMA: Record<AuthoringProfileId, boolean> = {\n  general: true,\n  'registered-view-router': false,\n  'compose-from-primitives': true,\n};\n\n/** Minified JSON with U+2028 and U+2029 escaped, so it always prints on one line. */\nconst compactJson = (value: unknown): string =>\n  String(JSON.stringify(value)).replace(\n    /[\\u2028\\u2029]/g,\n    (separator) => `\\\\u${separator.charCodeAt(0).toString(16)}`\n  );\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/** Host examples show composition, not provenance. */\nconst withoutMeta = (value: unknown): unknown => {\n  if (!isRecord(value) || !('meta' in value)) {\n    return value;\n  }\n  const rest = { ...value };\n  delete rest.meta;\n  return rest;\n};\n\n/** `text` as a Markdown code span, fenced longer than any backtick run inside it. */\nconst codeSpan = (text: string): string => {\n  const longestRun = Math.max(\n    0,\n    ...(text.match(/`+/g) ?? []).map(({ length }) => length)\n  );\n  const fence = '`'.repeat(longestRun + 1);\n  const pad = /^`|`$/.test(text) ? ' ' : '';\n  return `${fence}${pad}${text}${pad}${fence}`;\n};\n\n/** A lookup key as a code span, JSON-quoted when it would not survive printing bare. */\nconst keySpan = (key: string): string =>\n  codeSpan(\n    key !== '' && key.trim() === key && !/[\\p{Cc}\\p{Cs}\\u2028\\u2029]/u.test(key)\n      ? key\n      : compactJson(key)\n  );\n\n/** One primitive's catalog bullet: its purpose, `useWhen`, `avoidWhen`, and example. */\nexport const formatPrimitiveEntry = (entry: PrimitiveCatalogEntry): string => {\n  const lines = [`- ${keySpan(entry.type)} — ${oneLine(entry.purpose)}`];\n  if (entry.useWhen.length > 0) {\n    lines.push(`  - Use when: ${oneLine(entry.useWhen.join(' '))}`);\n  }\n  if (entry.avoidWhen.length > 0) {\n    lines.push(`  - Avoid when: ${oneLine(entry.avoidWhen.join(' '))}`);\n  }\n  lines.push(`  - Example: ${codeSpan(compactJson(entry.example))}`);\n  return lines.join('\\n');\n};\n\nconst renderCatalog = (primitives: readonly PrimitiveCatalogEntry[]): string =>\n  primitives.map(formatPrimitiveEntry).join('\\n');\n\nconst renderIndex = (\n  primitives: readonly PrimitiveCatalogEntry[],\n  groups: readonly PrimitiveGroup[] = []\n): string => {\n  const byType = new Map(primitives.map((entry) => [entry.type, entry]));\n  const grouped = new Set(groups.flatMap(({ types }) => types));\n  const sections = [\n    ...groups.map(({ title, types }) => ({\n      title,\n      entries: types.flatMap((type) => byType.get(type) ?? []),\n    })),\n    {\n      title: 'Other',\n      entries: primitives.filter(({ type }) => !grouped.has(type)),\n    },\n  ];\n  return [\n    INDEX_INTRO,\n    ...sections\n      .filter(({ entries }) => entries.length > 0)\n      .map(\n        ({ title, entries }) =>\n          `### ${oneLine(title)}\\n\\n${entries\n            .map(\n              ({ type, purpose }) => `- ${keySpan(type)} — ${oneLine(purpose)}`\n            )\n            .join('\\n')}`\n      ),\n  ].join('\\n\\n');\n};\n\nconst renderViews = (views: readonly AuthoringViewSummary[]): string =>\n  views\n    .map((view) => {\n      const lines = [`- ${keySpan(view.id)} — ${oneLine(view.title)}`];\n      if (view.description !== undefined && view.description.length > 0) {\n        lines.push(`  - ${oneLine(view.description)}`);\n      }\n      if (view.answers.length > 0) {\n        lines.push(`  - Answers: ${oneLine(view.answers.join('; '))}`);\n      }\n      if (view.inputSchema !== undefined) {\n        lines.push(`  - Input: ${codeSpan(compactJson(view.inputSchema))}`);\n      }\n      return lines.join('\\n');\n    })\n    .join('\\n');\n\nconst renderExamples = (examples: readonly unknown[]): string =>\n  examples\n    .map(\n      (example) => `\\`\\`\\`json\\n${compactJson(withoutMeta(example))}\\n\\`\\`\\``\n    )\n    .join('\\n\\n');\n\n/**\n * Assembles `context` into the prompt for `profile`, trimming the examples to\n * that profile's budget.\n *\n * The copy says \"view\" throughout because that is the wire discriminator and\n * the word models are trained and prompted on; pass `heading` and `intro` to\n * override it per host.\n */\nexport const buildAuthoringPrompt = (\n  profile: AuthoringProfileId,\n  context: AuthoringPromptContext\n): string => {\n  const examples = context.examples\n    .slice(0, PROFILE_EXAMPLE_LIMITS[profile])\n    .map(withoutMeta);\n  const views = context.views ?? [];\n  const schema = PROFILE_INCLUDES_SCHEMA[profile] ? context.schema : undefined;\n  const intro =\n    profile === 'compose-from-primitives' && schema === undefined\n      ? COMPOSE_INTRO_WITHOUT_SCHEMA\n      : PROFILE_INTROS[profile];\n  const sections = [\n    context.heading ?? '# View authoring',\n    context.intro ?? intro,\n    `## Guide\\n\\n${context.guide}`,\n  ];\n  if (context.rules !== undefined && context.rules.length > 0) {\n    sections.push(`## Rules\\n\\n${context.rules}`);\n  }\n  if (views.length > 0) {\n    sections.push(`## Registered views\\n\\n${renderViews(views)}`);\n  }\n  const catalog =\n    context.catalog === 'index'\n      ? renderIndex(context.primitives, context.groups)\n      : renderCatalog(context.primitives);\n  sections.push(`## Primitive catalog\\n\\n${catalog}`);\n  if (schema !== undefined) {\n    sections.push(\n      `## JSON Schema\\n\\n\\`\\`\\`json\\n${compactJson(schema)}\\n\\`\\`\\``\n    );\n  }\n  if (examples.length > 0) {\n    sections.push(`## Examples\\n\\n${renderExamples(examples)}`);\n  }\n  return sections.join('\\n\\n');\n};\n"]}

package/dist/cjs/author/authored_fields.js

@@ -0,0 +1,189 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAuthoredSpec = exports.fromTextChildren = exports.authoredText = exports.authoredProps = exports.authoredChild = void 0;
+exports.fromChildren = fromChildren;
+const error_1 = require("../composition/error");
+/**
+ * Child-element type a schema field is filled from.
+ *
+ * `Symbol.for`: ESM and CJS builds must agree, same as `authorType`.
+ */
+exports.authoredChild = Symbol.for('elastic.isomer.authored_child');
+/** Phantom props type for the child component. Not set at runtime. */
+exports.authoredProps = Symbol.for('elastic.isomer.authored_props');
+/** Set when a field is filled from text children. */
+exports.authoredText = Symbol.for('elastic.isomer.authored_text');
+const authoredToItem = Symbol.for('elastic.isomer.authored_to_item');
+const authoredTextField = Symbol.for('elastic.isomer.authored_text_field');
+const authoredCollapse = Symbol.for('elastic.isomer.authored_collapse');
+const BRANDS = [
+    exports.authoredChild,
+    authoredTextField,
+    authoredToItem,
+    exports.authoredText,
+    authoredCollapse,
+];
+// Applies a complete branding. Branding an instance again is allowed only with
+// the same configuration, absent options included, since both fields share it.
+const brand = (caller, schema, config) => {
+    const record = schema;
+    if (BRANDS.some((key) => Object.hasOwn(schema, key))) {
+        if (BRANDS.every((key) => record[key] === config[key]))
+            return;
+        throw new error_1.IsomerError(error_1.ISOMER_ERROR_CODES.AUTHORED_SCHEMA_REUSED, `${caller}: this schema instance is already branded another way; pass each field its own schema.`);
+    }
+    for (const key of BRANDS) {
+        if (config[key] !== undefined) {
+            Object.defineProperty(schema, key, {
+                value: config[key],
+                enumerable: false,
+            });
+        }
+    }
+};
+function fromChildren(childType, schema, options) {
+    brand('fromChildren', schema, {
+        [exports.authoredChild]: childType,
+        [authoredTextField]: options?.text,
+        [authoredToItem]: options?.toItem,
+    });
+    return schema;
+}
+/**
+ * Brands `schema` as text children.
+ *
+ * Whitespace collapses unless `collapseWhitespace` is `false`.
+ */
+const fromTextChildren = (schema, options) => {
+    brand('fromTextChildren', schema, {
+        [exports.authoredText]: true,
+        [authoredCollapse]: options?.collapseWhitespace === false ? false : undefined,
+    });
+    return schema;
+};
+exports.fromTextChildren = fromTextChildren;
+const zodDefType = (schema) => schema._zod?.def?.type;
+const WRAPPER_TYPES = new Set(['optional', 'nullable', 'default', 'readonly']);
+const innerSchema = (schema) => {
+    const def = schema._zod?.def;
+    return def?.type && WRAPPER_TYPES.has(def.type) ? def.innerType : undefined;
+};
+// The schema holding `brand`: `schema` or one it wraps.
+const brandHolder = (schema, key) => {
+    let current = schema;
+    while (current && !Object.hasOwn(current, key)) {
+        current = innerSchema(current);
+    }
+    return current;
+};
+// Whether any wrapper layer of `schema` accepts `undefined`.
+const optionalThrough = (schema) => {
+    for (let current = schema; current; current = innerSchema(current)) {
+        if (isOptionalSchema(current))
+            return true;
+    }
+    return false;
+};
+const unwrapAll = (schema) => {
+    let current = schema;
+    for (let inner = innerSchema(current); inner; inner = innerSchema(current)) {
+        current = inner;
+    }
+    return current;
+};
+/** `undefined` is a valid value, so children may be omitted. */
+const isOptionalSchema = (schema) => {
+    const type = zodDefType(schema);
+    return type === 'optional' || type === 'default';
+};
+const schemaSignature = (schema, seen = new Set()) => {
+    if (seen.has(schema)) {
+        return 'cycle';
+    }
+    seen.add(schema);
+    const type = zodDefType(schema) ?? '?';
+    if (type === 'object' && 'shape' in schema) {
+        const shape = schema.shape;
+        const fields = Object.keys(shape)
+            .sort()
+            .map((key) => `${key}:${schemaSignature(shape[key], seen)}`);
+        return `{${fields.join(',')}}`;
+    }
+    if (type === 'array' && 'element' in schema) {
+        return `[${schemaSignature(schema.element, seen)}]`;
+    }
+    const inner = innerSchema(schema);
+    if (inner) {
+        return `${type}(${schemaSignature(inner, seen)})`;
+    }
+    return type;
+};
+const arrayElement = (schema) => {
+    const inner = unwrapAll(schema);
+    if (zodDefType(inner) === 'array' && 'element' in inner) {
+        return inner.element;
+    }
+    return inner;
+};
+const readChild = (field, schema) => {
+    const holder = brandHolder(schema, exports.authoredChild);
+    const childType = holder?.[exports.authoredChild];
+    if (!holder || typeof childType !== 'string') {
+        return undefined;
+    }
+    const textField = holder[authoredTextField];
+    const toItem = holder[authoredToItem];
+    const child = {
+        field,
+        childType,
+        itemSchema: arrayElement(holder),
+        optional: optionalThrough(schema),
+        signature: schemaSignature(arrayElement(holder)),
+    };
+    if (typeof textField === 'string') {
+        child.textField = textField;
+    }
+    if (typeof toItem === 'function') {
+        child.toItem = toItem;
+    }
+    return child;
+};
+const readText = (field, schema) => {
+    const holder = brandHolder(schema, exports.authoredText);
+    if (!holder) {
+        return undefined;
+    }
+    return {
+        field,
+        collapseWhitespace: holder[authoredCollapse] !== false,
+        optional: optionalThrough(schema),
+    };
+};
+/** Top-level branded fields on an object schema. Nested brands stay on the item schema. */
+const readAuthoredSpec = (schema) => {
+    if (zodDefType(schema) !== 'object' || !('shape' in schema)) {
+        return { children: [], text: [] };
+    }
+    const children = [];
+    const text = [];
+    for (const [field, fieldSchema] of Object.entries(schema.shape)) {
+        const child = readChild(field, fieldSchema);
+        if (child) {
+            children.push(child);
+            continue;
+        }
+        const textField = readText(field, fieldSchema);
+        if (textField) {
+            text.push(textField);
+        }
+    }
+    return { children, text };
+};
+exports.readAuthoredSpec = readAuthoredSpec;
+//# sourceMappingURL=authored_fields.js.map

package/dist/cjs/author/authored_fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authored_fields.js","sourceRoot":"","sources":["../../../src/author/authored_fields.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 type { ZodType } from 'zod';\n\nimport { ISOMER_ERROR_CODES, IsomerError } from '../composition/error';\nimport type { PrimitiveNode } from '../define/primitive_module';\n\n/**\n * Child-element type a schema field is filled from.\n *\n * `Symbol.for`: ESM and CJS builds must agree, same as `authorType`.\n */\nexport const authoredChild = Symbol.for('elastic.isomer.authored_child');\n\n/** Phantom props type for the child component. Not set at runtime. */\nexport const authoredProps = Symbol.for('elastic.isomer.authored_props');\n\n/** Set when a field is filled from text children. */\nexport const authoredText = Symbol.for('elastic.isomer.authored_text');\n\nconst authoredToItem = Symbol.for('elastic.isomer.authored_to_item');\nconst authoredTextField = Symbol.for('elastic.isomer.authored_text_field');\nconst authoredCollapse = Symbol.for('elastic.isomer.authored_collapse');\n\n/**\n * A field filled from child elements of `TName`.\n *\n * Phantom: `z.infer` still reads the underlying schema. The shim reads `TName`\n * and `TProps` off the field type, and the symbols off the schema value.\n */\nexport interface AuthoredChildBrand<TName extends string, TProps> {\n  readonly [authoredChild]: TName;\n  readonly [authoredProps]: TProps;\n}\n\n/** A field filled from text children. */\nexport interface AuthoredTextBrand {\n  readonly [authoredText]: true;\n}\n\n/** What {@link fromChildren}'s `toItem` receives. */\nexport interface AuthorChildContext {\n  /** Nested elements, parsed as body nodes. */\n  parseChildren: (children: ReactNode) => PrimitiveNode[];\n}\n\ntype ArrayItem<TSchema extends ZodType> =\n  NonNullable<zOutput<TSchema>> extends readonly (infer Item)[]\n    ? Item\n    : NonNullable<zOutput<TSchema>>;\n\ntype zOutput<TSchema> = TSchema extends { _zod: { output: infer Output } }\n  ? Output\n  : never;\n\n/** `TText` is optional on the child props because leftover text fills it. */\ntype ChildProps<TItem, TText extends string | undefined> = [TText] extends [\n  string,\n]\n  ? Omit<TItem, TText> &\n      Partial<Pick<TItem, Extract<TText, keyof TItem>>> & {\n        children?: ReactNode;\n      }\n  : TItem & { children?: ReactNode };\n\nconst BRANDS = [\n  authoredChild,\n  authoredTextField,\n  authoredToItem,\n  authoredText,\n  authoredCollapse,\n] as const;\n\n// Applies a complete branding. Branding an instance again is allowed only with\n// the same configuration, absent options included, since both fields share it.\nconst brand = (\n  caller: 'fromChildren' | 'fromTextChildren',\n  schema: object,\n  config: Partial<Record<(typeof BRANDS)[number], unknown>>\n): void => {\n  const record = schema as Record<symbol, unknown>;\n  if (BRANDS.some((key) => Object.hasOwn(schema, key))) {\n    if (BRANDS.every((key) => record[key] === config[key])) return;\n    throw new IsomerError(\n      ISOMER_ERROR_CODES.AUTHORED_SCHEMA_REUSED,\n      `${caller}: this schema instance is already branded another way; pass each field its own schema.`\n    );\n  }\n  for (const key of BRANDS) {\n    if (config[key] !== undefined) {\n      Object.defineProperty(schema, key, {\n        value: config[key],\n        enumerable: false,\n      });\n    }\n  }\n};\n\n/**\n * Brands `schema` as JSX children of `childType`.\n *\n * `options.text` copies leftover text onto that field. `options.toItem` replaces\n * the default prop copy; its props annotation is the child component's props.\n * The brand is read through `.optional()`, `.nullable()`, `.default()`, and\n * `.readonly()`; any other method clones without it, so call it on `schema`\n * before passing it in.\n */\nexport function fromChildren<\n  const TName extends string,\n  TSchema extends ZodType,\n>(\n  childType: TName,\n  schema: TSchema\n): TSchema &\n  AuthoredChildBrand<TName, ChildProps<ArrayItem<TSchema>, undefined>>;\nexport function fromChildren<\n  const TName extends string,\n  TSchema extends ZodType,\n  const TText extends string,\n>(\n  childType: TName,\n  schema: TSchema,\n  options: { text: TText }\n): TSchema & AuthoredChildBrand<TName, ChildProps<ArrayItem<TSchema>, TText>>;\nexport function fromChildren<\n  const TName extends string,\n  TSchema extends ZodType,\n  TProps,\n>(\n  childType: TName,\n  schema: TSchema,\n  options: {\n    text?: string;\n    toItem(props: TProps, context: AuthorChildContext): unknown;\n  }\n): TSchema & AuthoredChildBrand<TName, TProps>;\nexport function fromChildren(\n  childType: string,\n  schema: ZodType,\n  options?: {\n    text?: string;\n    toItem?: (this: void, props: never, context: AuthorChildContext) => unknown;\n  }\n): ZodType {\n  brand('fromChildren', schema, {\n    [authoredChild]: childType,\n    [authoredTextField]: options?.text,\n    [authoredToItem]: options?.toItem,\n  });\n  return schema;\n}\n\n/**\n * Brands `schema` as text children.\n *\n * Whitespace collapses unless `collapseWhitespace` is `false`.\n */\nexport const fromTextChildren = <TSchema extends ZodType>(\n  schema: TSchema,\n  options?: { collapseWhitespace?: boolean }\n): TSchema & AuthoredTextBrand => {\n  brand('fromTextChildren', schema, {\n    [authoredText]: true,\n    [authoredCollapse]:\n      options?.collapseWhitespace === false ? false : undefined,\n  });\n  return schema as TSchema & AuthoredTextBrand;\n};\n\n/** One {@link fromChildren} field as the shim reads it. */\nexport interface AuthoredChildField {\n  field: string;\n  childType: string;\n  /** Field leftover text children fill. */\n  textField?: string;\n  /** Replaces the default prop copy. */\n  toItem?: (props: object, context: AuthorChildContext) => unknown;\n  /** The array element schema, or the field schema itself when it is not an array. */\n  itemSchema: ZodType;\n  /** Whether the field accepts `undefined`, so children may be omitted. */\n  optional: boolean;\n  /** Structural fingerprint of `itemSchema`; every field branding one child type must share it. */\n  signature: string;\n}\n\n/** One {@link fromTextChildren} field as the shim reads it. */\nexport interface AuthoredTextField {\n  field: string;\n  /** `true` unless the brand was given `collapseWhitespace: false`. */\n  collapseWhitespace: boolean;\n  /** Whether the field accepts `undefined`, so text children may be omitted. */\n  optional: boolean;\n}\n\n/** The branded fields found on one object schema. */\nexport interface AuthoredSpec {\n  children: AuthoredChildField[];\n  text: AuthoredTextField[];\n}\n\nconst zodDefType = (schema: object): string | undefined =>\n  (schema as { _zod?: { def?: { type?: string } } })._zod?.def?.type;\n\nconst WRAPPER_TYPES = new Set(['optional', 'nullable', 'default', 'readonly']);\n\ninterface WrapperDef {\n  type?: string;\n  innerType?: ZodType;\n}\n\nconst innerSchema = (schema: ZodType): ZodType | undefined => {\n  const def: WrapperDef | undefined = (\n    schema as { _zod?: { def?: WrapperDef } }\n  )._zod?.def;\n  return def?.type && WRAPPER_TYPES.has(def.type) ? def.innerType : undefined;\n};\n\n// The schema holding `brand`: `schema` or one it wraps.\nconst brandHolder = (schema: ZodType, key: symbol): ZodType | undefined => {\n  let current: ZodType | undefined = schema;\n  while (current && !Object.hasOwn(current, key)) {\n    current = innerSchema(current);\n  }\n  return current;\n};\n\n// Whether any wrapper layer of `schema` accepts `undefined`.\nconst optionalThrough = (schema: ZodType): boolean => {\n  for (\n    let current: ZodType | undefined = schema;\n    current;\n    current = innerSchema(current)\n  ) {\n    if (isOptionalSchema(current)) return true;\n  }\n  return false;\n};\n\nconst unwrapAll = (schema: ZodType): ZodType => {\n  let current = schema;\n  for (let inner = innerSchema(current); inner; inner = innerSchema(current)) {\n    current = inner;\n  }\n  return current;\n};\n\n/** `undefined` is a valid value, so children may be omitted. */\nconst isOptionalSchema = (schema: ZodType): boolean => {\n  const type = zodDefType(schema);\n  return type === 'optional' || type === 'default';\n};\n\nconst schemaSignature = (\n  schema: ZodType,\n  seen: Set<object> = new Set()\n): string => {\n  if (seen.has(schema)) {\n    return 'cycle';\n  }\n  seen.add(schema);\n  const type = zodDefType(schema) ?? '?';\n  if (type === 'object' && 'shape' in schema) {\n    const shape = schema.shape as Record<string, ZodType>;\n    const fields = Object.keys(shape)\n      .sort()\n      .map((key) => `${key}:${schemaSignature(shape[key] as ZodType, seen)}`);\n    return `{${fields.join(',')}}`;\n  }\n  if (type === 'array' && 'element' in schema) {\n    return `[${schemaSignature((schema as { element: ZodType }).element, seen)}]`;\n  }\n  const inner = innerSchema(schema);\n  if (inner) {\n    return `${type}(${schemaSignature(inner, seen)})`;\n  }\n  return type;\n};\n\nconst arrayElement = (schema: ZodType): ZodType => {\n  const inner = unwrapAll(schema);\n  if (zodDefType(inner) === 'array' && 'element' in inner) {\n    return (inner as { element: ZodType }).element;\n  }\n  return inner;\n};\n\nconst readChild = (\n  field: string,\n  schema: ZodType\n): AuthoredChildField | undefined => {\n  const holder = brandHolder(schema, authoredChild);\n  const childType = (holder as { [authoredChild]?: unknown } | undefined)?.[\n    authoredChild\n  ];\n  if (!holder || typeof childType !== 'string') {\n    return undefined;\n  }\n  const textField = (holder as { [authoredTextField]?: unknown })[\n    authoredTextField\n  ];\n  const toItem = (holder as { [authoredToItem]?: unknown })[authoredToItem];\n  const child: AuthoredChildField = {\n    field,\n    childType,\n    itemSchema: arrayElement(holder),\n    optional: optionalThrough(schema),\n    signature: schemaSignature(arrayElement(holder)),\n  };\n  if (typeof textField === 'string') {\n    child.textField = textField;\n  }\n  if (typeof toItem === 'function') {\n    child.toItem = toItem as (\n      props: object,\n      context: AuthorChildContext\n    ) => unknown;\n  }\n  return child;\n};\n\nconst readText = (\n  field: string,\n  schema: ZodType\n): AuthoredTextField | undefined => {\n  const holder = brandHolder(schema, authoredText);\n  if (!holder) {\n    return undefined;\n  }\n  return {\n    field,\n    collapseWhitespace:\n      (holder as { [authoredCollapse]?: unknown })[authoredCollapse] !== false,\n    optional: optionalThrough(schema),\n  };\n};\n\n/** Top-level branded fields on an object schema. Nested brands stay on the item schema. */\nexport const readAuthoredSpec = (schema: ZodType): AuthoredSpec => {\n  if (zodDefType(schema) !== 'object' || !('shape' in schema)) {\n    return { children: [], text: [] };\n  }\n  const children: AuthoredChildField[] = [];\n  const text: AuthoredTextField[] = [];\n  for (const [field, fieldSchema] of Object.entries(\n    schema.shape as Record<string, ZodType>\n  )) {\n    const child = readChild(field, fieldSchema);\n    if (child) {\n      children.push(child);\n      continue;\n    }\n    const textField = readText(field, fieldSchema);\n    if (textField) {\n      text.push(textField);\n    }\n  }\n  return { children, text };\n};\n"]}

package/dist/cjs/author/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPrimitiveEntry = exports.buildAuthoringPrompt = exports.AUTHORING_PROFILE_IDS = exports.textFromChildren = exports.buildJsxShim = exports.fromTextChildren = exports.fromChildren = void 0;
+var authored_fields_1 = require("./authored_fields");
+Object.defineProperty(exports, "fromChildren", { enumerable: true, get: function () { return authored_fields_1.fromChildren; } });
+Object.defineProperty(exports, "fromTextChildren", { enumerable: true, get: function () { return authored_fields_1.fromTextChildren; } });
+var jsx_shim_1 = require("./jsx_shim");
+Object.defineProperty(exports, "buildJsxShim", { enumerable: true, get: function () { return jsx_shim_1.buildJsxShim; } });
+Object.defineProperty(exports, "textFromChildren", { enumerable: true, get: function () { return jsx_shim_1.textFromChildren; } });
+var prompt_1 = require("./prompt");
+Object.defineProperty(exports, "AUTHORING_PROFILE_IDS", { enumerable: true, get: function () { return prompt_1.AUTHORING_PROFILE_IDS; } });
+Object.defineProperty(exports, "buildAuthoringPrompt", { enumerable: true, get: function () { return prompt_1.buildAuthoringPrompt; } });
+Object.defineProperty(exports, "formatPrimitiveEntry", { enumerable: true, get: function () { return prompt_1.formatPrimitiveEntry; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/author/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/author/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,qDAM2B;AAFzB,+GAAA,YAAY,OAAA;AACZ,mHAAA,gBAAgB,OAAA;AAGlB,uCAOoB;AAFlB,wGAAA,YAAY,OAAA;AACZ,4GAAA,gBAAgB,OAAA;AAElB,mCAOkB;AAHhB,+GAAA,qBAAqB,OAAA;AACrB,8GAAA,oBAAoB,OAAA;AACpB,8GAAA,oBAAoB,OAAA","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\nexport {\n  type AuthorChildContext,\n  type AuthoredChildBrand,\n  type AuthoredTextBrand,\n  fromChildren,\n  fromTextChildren,\n} from './authored_fields';\nexport { type AuthorComponent } from './jsx';\nexport {\n  type AuthorComposition,\n  type CompositionAuthorProps,\n  type JsxShim,\n  type PrimitiveComponentMap,\n  buildJsxShim,\n  textFromChildren,\n} from './jsx_shim';\nexport {\n  type AuthoringProfileId,\n  type AuthoringPromptContext,\n  type AuthoringViewSummary,\n  AUTHORING_PROFILE_IDS,\n  buildAuthoringPrompt,\n  formatPrimitiveEntry,\n} from './prompt';\n"]}

package/dist/cjs/author/jsx.js

@@ -0,0 +1,24 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAuthorComponent = exports.authorType = void 0;
+/**
+ * Brand carrying the primitive type an authoring component stands for.
+ *
+ * `Symbol.for` rather than `Symbol()`: the SDK ships both ESM and CJS builds,
+ * so a host can hold two copies of this module and a unique symbol would make
+ * one build's components unreadable to the other's shim.
+ */
+exports.authorType = Symbol.for('elastic.isomer.author_type');
+/** The {@link AuthorComponent} for one primitive `type`. */
+const defineAuthorComponent = (type) => Object.assign(() => null, {
+    [exports.authorType]: type,
+    displayName: type,
+});
+exports.defineAuthorComponent = defineAuthorComponent;
+//# sourceMappingURL=jsx.js.map

package/dist/cjs/author/jsx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx.js","sourceRoot":"","sources":["../../../src/author/jsx.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH;;;;;;GAMG;AACU,QAAA,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAanE,4DAA4D;AACrD,MAAM,qBAAqB,GAAG,CACnC,IAAW,EACqB,EAAE,CAClC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE;IACxB,CAAC,kBAAU,CAAC,EAAE,IAAI;IAClB,WAAW,EAAE,IAAI;CAClB,CAAC,CAAC;AANQ,QAAA,qBAAqB,yBAM7B","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\n/**\n * Brand carrying the primitive type an authoring component stands for.\n *\n * `Symbol.for` rather than `Symbol()`: the SDK ships both ESM and CJS builds,\n * so a host can hold two copies of this module and a unique symbol would make\n * one build's components unreadable to the other's shim.\n */\nexport const authorType = Symbol.for('elastic.isomer.author_type');\n\n/**\n * A JSX component that renders `null` and exists only to carry `TType` through\n * the tree until the shim converts it to a composition.\n */\nexport interface AuthorComponent<TProps, TType extends string> {\n  (props: TProps): null;\n  readonly [authorType]: TType;\n  /** Set to `type` by the shim. */\n  displayName?: string;\n}\n\n/** The {@link AuthorComponent} for one primitive `type`. */\nexport const defineAuthorComponent = <TProps, TType extends string>(\n  type: TType\n): AuthorComponent<TProps, TType> =>\n  Object.assign(() => null, {\n    [authorType]: type,\n    displayName: type,\n  });\n"]}