Merge FR-010 TypeScript port — Phase 2: OutputFormatRenderer

Output-format prompt fragment renderer (artifact 1) in @metaobjectsdev/render — 3 comment-free
styles × {json,xml}, byte-identical to Java/Kotlin/C#, reuses ESCAPERS. Pre-merge review+simplifier
caught + fixed two invalid-JSON BLOCKERs (empty-fields `{\n}` parity; radix-literal quoting),
both regression-covered. 20 prompt tests + render suite 232 green; strict typecheck clean.
TS Phase 3 (attrs + serializer fix + codegen) follows.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/render/src/index.ts

@@ -42,3 +42,14 @@ export {
   asBool,
   asStringList,
 } from "./recover/recover-map.js";
+
+// FR-010 artifact 1 — output-format prompt renderer ("produce your answer like this").
+export { renderOutputFormat } from "./prompt/output-format-renderer.js";
+export { PromptStyle, promptStyleFrom } from "./prompt/prompt-style.js";
+export {
+  PROMPT_OVERRIDES_NONE,
+  noOverrides,
+  type PromptOverrides,
+} from "./prompt/prompt-overrides.js";
+export type { OutputFormatSpec } from "./prompt/output-format-spec.js";
+export type { PromptField } from "./prompt/prompt-field.js";

server/typescript/packages/render/src/prompt/output-format-renderer.ts

@@ -0,0 +1,179 @@
+// FR-010 artifact 1 — output-format prompt renderer ("produce your answer like this").
+//
+// Renders an OutputFormatSpec into a prompt fragment that teaches an LLM how to
+// shape its answer. Three comment-free styles (guide / inline / exampleOnly) ×
+// two formats (json / xml). Guidance is carried in prose / inline placeholders /
+// a filled skeleton — NEVER in comments (models ignore them).
+//
+// Cross-port INVARIANT: the rendered text is byte-identical to the Java/C#/Kotlin
+// reference (com.metaobjects.render.prompt.OutputFormatRenderer). Do not change
+// the verbatim prose, skeleton shapes, or numeric-vs-quoted decision.
+
+import { ESCAPERS } from "../escapers.js";
+import { FieldKind, Format } from "../recover/types.js";
+import type { OutputFormatSpec } from "./output-format-spec.js";
+import type { PromptField } from "./prompt-field.js";
+import type { PromptOverrides } from "./prompt-overrides.js";
+import { PromptStyle } from "./prompt-style.js";
+
+const NUMERIC_KINDS: ReadonlySet<FieldKind> = new Set<FieldKind>([
+  FieldKind.INT,
+  FieldKind.LONG,
+  FieldKind.DOUBLE,
+  FieldKind.BOOLEAN,
+]);
+
+// The render engine OWNS format-keyed escaping; Format ("JSON"/"XML") maps to the
+// lowercase ESCAPERS keys.
+const escapeXml = (s: string): string => ESCAPERS.xml(s);
+const escapeJson = (s: string): string => ESCAPERS.json(s);
+
+/**
+ * Render an {@link OutputFormatSpec} into an output-format prompt fragment. The
+ * effective style is the override's style if present, otherwise the spec's.
+ */
+export function renderOutputFormat(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  const effectiveStyle = overrides.style ?? spec.style;
+  switch (effectiveStyle) {
+    case PromptStyle.EXAMPLE_ONLY:
+      return renderExampleOnly(spec, overrides);
+    case PromptStyle.INLINE:
+      return renderInline(spec, overrides);
+    default:
+      return renderGuide(spec, overrides);
+  }
+}
+
+// ---- INLINE ----------------------------------------------------------------
+
+function renderInline(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  return spec.format === Format.XML
+    ? renderXmlInline(spec, overrides)
+    : renderJsonInline(spec, overrides);
+}
+
+function renderXmlInline(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  const lines = spec.fields.map((field) => {
+    const escaped = escapeXml(inlineContent(field, overrides));
+    return `  <${field.name}>${escaped}</${field.name}>\n`;
+  });
+  return `<${spec.rootName}>\n${lines.join("")}</${spec.rootName}>`;
+}
+
+function renderJsonInline(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  const lines = spec.fields.map(
+    (field) => `  "${field.name}": "${escapeJson(inlineContent(field, overrides))}"`,
+  );
+  // Empty object is `{\n}` (Java/C# parity), not `{\n\n}` from join("") on no lines.
+  return spec.fields.length === 0 ? "{\n}" : `{\n${lines.join(",\n")}\n}`;
+}
+
+function inlineContent(field: PromptField, overrides: PromptOverrides): string {
+  if (field.kind === FieldKind.ENUM && field.enumValues != null && field.enumValues.length > 0) {
+    return field.enumValues.join(" | ");
+  }
+  if (field.kind === FieldKind.BOOLEAN) {
+    return "true | false";
+  }
+  const instruction = resolveInstruction(field, overrides);
+  return instruction != null ? `{${instruction}}` : `{${field.name}}`;
+}
+
+/** Effective instruction: override first, then the field default, else null. */
+function resolveInstruction(field: PromptField, overrides: PromptOverrides): string | null {
+  const ov = overrides.instructions?.[field.name];
+  if (ov != null) return ov;
+  return field.instruction;
+}
+
+// ---- GUIDE -----------------------------------------------------------------
+
+function renderGuide(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  let sb = "Fill in each field as described below:\n";
+  for (const field of spec.fields) {
+    const req = field.required ? "required" : "optional";
+    sb += `- ${field.name} (${req})`;
+    const instruction = resolveInstruction(field, overrides);
+    if (instruction != null) {
+      sb += `: ${instruction}`;
+    }
+    sb += "\n";
+    if (field.kind === FieldKind.ENUM && field.enumValues != null && field.enumValues.length > 0) {
+      sb += `    one of ${field.enumValues.join(", ")}\n`;
+      const enumDoc = field.enumDoc;
+      if (enumDoc != null) {
+        for (const val of field.enumValues) {
+          const doc = enumDoc[val];
+          if (doc != null) {
+            sb += `      ${val} = ${doc}\n`;
+          }
+        }
+      }
+    }
+    const eg = exampleValueIfDeclared(field, overrides);
+    if (eg != null) {
+      sb += `    e.g. ${eg}\n`;
+    }
+  }
+  sb += "\nRespond exactly like this:\n";
+  sb += renderExampleOnly(spec, overrides);
+  return sb;
+}
+
+// ---- EXAMPLE-ONLY (also the skeleton appended by GUIDE) ---------------------
+
+function renderExampleOnly(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  return spec.format === Format.XML
+    ? renderXmlSkeleton(spec, overrides)
+    : renderJsonSkeleton(spec, overrides);
+}
+
+function renderXmlSkeleton(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  const lines = spec.fields.map((field) => {
+    const escaped = escapeXml(exampleValue(field, overrides));
+    return `  <${field.name}>${escaped}</${field.name}>\n`;
+  });
+  return `<${spec.rootName}>\n${lines.join("")}</${spec.rootName}>`;
+}
+
+function renderJsonSkeleton(spec: OutputFormatSpec, overrides: PromptOverrides): string {
+  // NOTE: FieldKind.OBJECT / nested fields are not expanded here — they render as
+  // a "{fieldName}" placeholder. Nested-object expansion is a bounded deferral
+  // (mirrors Java/C#).
+  const lines = spec.fields.map((field) => {
+    const value = exampleValue(field, overrides);
+    const rendered = isNumericOrBoolean(field.kind, value) ? value : `"${escapeJson(value)}"`;
+    return `  "${field.name}": ${rendered}`;
+  });
+  // Empty object is `{\n}` (Java/C# parity), not `{\n\n}` from join("") on no lines.
+  return spec.fields.length === 0 ? "{\n}" : `{\n${lines.join(",\n")}\n}`;
+}
+
+function exampleValueIfDeclared(field: PromptField, overrides: PromptOverrides): string | null {
+  const ov = overrides.examples?.[field.name];
+  if (ov != null) return ov;
+  if (field.example != null) return field.example;
+  return null;
+}
+
+function exampleValue(field: PromptField, overrides: PromptOverrides): string {
+  const ov = overrides.examples?.[field.name];
+  if (ov != null) return ov;
+  if (field.example != null) return field.example;
+  if (field.kind === FieldKind.ENUM && field.enumValues != null && field.enumValues.length > 0) {
+    return field.enumValues[0]!;
+  }
+  return `{${field.name}}`;
+}
+
+function isNumericOrBoolean(kind: FieldKind, value: string): boolean {
+  if (!NUMERIC_KINDS.has(kind)) return false;
+  if (value === "true" || value === "false") return true;
+  // Finite-only: NaN/Infinity fall through to a quoted string so the emitted JSON
+  // stays valid. Number("") is 0, so guard the empty/blank case explicitly. Reject
+  // JS-only radix literals (0x../0b../0o..) that Number() accepts but Java/C# don't —
+  // same guard as the recover engine's parseFiniteNumber (keeps the JSON valid + parity).
+  const t = value.trim();
+  if (t === "" || /^[+-]?0[xXbBoO]/.test(t)) return false;
+  return Number.isFinite(Number(t));
+}

server/typescript/packages/render/src/prompt/output-format-spec.ts

@@ -0,0 +1,20 @@
+// FR-010 artifact 1 — a complete output-format descriptor.
+
+import type { Format } from "../recover/types.js";
+import type { PromptField } from "./prompt-field.js";
+import type { PromptStyle } from "./prompt-style.js";
+
+/**
+ * A complete output-format descriptor: the format, the root element/object name,
+ * the default presentation style, and the ordered fields. Drives
+ * {@link renderOutputFormat}.
+ *
+ * Precondition: `rootName` must be identifier-safe (valid XML element name / JSON
+ * key). The renderer does not escape it.
+ */
+export interface OutputFormatSpec {
+  readonly format: Format;
+  readonly rootName: string;
+  readonly style: PromptStyle;
+  readonly fields: readonly PromptField[];
+}

server/typescript/packages/render/src/prompt/prompt-field.ts

@@ -0,0 +1,24 @@
+// FR-010 artifact 1 — one field of an output-format fragment.
+
+import type { FieldKind } from "../recover/types.js";
+import type { OutputFormatSpec } from "./output-format-spec.js";
+
+/**
+ * One field of an output-format fragment. `enumValues`/`enumDoc` are non-null
+ * only for ENUM; `nested` non-null only for OBJECT; `example`/`instruction` are
+ * nullable.
+ *
+ * Precondition: `name` must be identifier-safe (valid XML element name / JSON
+ * key). The renderer does not escape field names.
+ */
+export interface PromptField {
+  readonly name: string;
+  readonly kind: FieldKind;
+  readonly required: boolean;
+  readonly array: boolean;
+  readonly enumValues: readonly string[] | null;
+  readonly enumDoc: Readonly<Record<string, string>> | null;
+  readonly example: string | null;
+  readonly instruction: string | null;
+  readonly nested: OutputFormatSpec | null;
+}

server/typescript/packages/render/src/prompt/prompt-overrides.ts

@@ -0,0 +1,27 @@
+// FR-010 artifact 1 — render-time overrides of the metadata defaults.
+
+import type { PromptStyle } from "./prompt-style.js";
+
+/**
+ * Render-time overrides of the metadata defaults. `style` undefined keeps the
+ * spec's style; the maps override `PromptField.example`/`PromptField.instruction`
+ * per field name.
+ */
+export interface PromptOverrides {
+  readonly style?: PromptStyle;
+  readonly examples?: Readonly<Record<string, string>>;
+  readonly instructions?: Readonly<Record<string, string>>;
+}
+
+/** No overrides — keep every metadata default. Mirrors Java `PromptOverrides.none()`. */
+export const PROMPT_OVERRIDES_NONE: PromptOverrides = Object.freeze({
+  // `style` omitted (not `undefined`) under exactOptionalPropertyTypes: an absent
+  // style keeps the spec's own style, matching Java `PromptOverrides.none()`.
+  examples: {},
+  instructions: {},
+});
+
+/** No overrides — keep every metadata default. */
+export function noOverrides(): PromptOverrides {
+  return PROMPT_OVERRIDES_NONE;
+}

server/typescript/packages/render/src/prompt/prompt-style.ts

@@ -0,0 +1,36 @@
+// FR-010 artifact 1 — output-format prompt renderer.
+//
+// How the output-format fragment teaches the model. Guidance is NEVER carried in
+// comments (models ignore them) — it lives in prose / inline placeholders / a
+// filled skeleton. Default is "guide".
+//
+// Tier-2 idiomatic TS: the Java SCREAMING_SNAKE enum (GUIDE/INLINE/EXAMPLE_ONLY)
+// becomes a string-union whose members ARE the wire `@promptStyle` values
+// ("guide" | "inline" | "exampleOnly") — no name<->wire mapping table needed.
+
+/**
+ * - `"guide"`: prose field list ("Fill in each field…") followed by an example skeleton.
+ * - `"inline"`: a single skeleton whose field values are inline placeholders / enum choices.
+ * - `"exampleOnly"`: just a filled example skeleton, nothing else.
+ */
+export const PromptStyle = {
+  GUIDE: "guide",
+  INLINE: "inline",
+  EXAMPLE_ONLY: "exampleOnly",
+} as const;
+export type PromptStyle = (typeof PromptStyle)[keyof typeof PromptStyle];
+
+/**
+ * Maps the `@promptStyle` attribute string to a {@link PromptStyle}. Null or any
+ * unrecognized value falls back to `"guide"` (matches Java `PromptStyle.from`).
+ */
+export function promptStyleFrom(s?: string | null): PromptStyle {
+  switch (s) {
+    case PromptStyle.INLINE:
+      return PromptStyle.INLINE;
+    case PromptStyle.EXAMPLE_ONLY:
+      return PromptStyle.EXAMPLE_ONLY;
+    default:
+      return PromptStyle.GUIDE;
+  }
+}