Learn: a /learn/ deep-dive section — markdown lessons as before/after spec progressions

src/core/json-format.ts

@@ -17,6 +17,24 @@ const DEFAULT_MAX_LINE = 80;
 /** Default indent (spaces) — matches the editor's default tab size (spec §07). */
 const DEFAULT_INDENT = 2;
 
+/**
+ * Pretty-print a spec *object* (not text) in the same Vega house style as
+ * {@link formatJson}. Object-in callers — the lesson source panes, anything that
+ * holds a spec as a parsed value — use this so their rendered JSON matches the
+ * editor's formatting exactly. Key order is the object's own insertion order,
+ * deliberately: where consecutive specs are small edits of one another (a lesson's
+ * 80%→100% chain), a stable order is what keeps a line-diff between them legible.
+ */
+export function formatSpec(
+  value: unknown,
+  opts: { indent?: number; maxLength?: number } = {},
+): string {
+  return stringify(value, {
+    indent: opts.indent ?? DEFAULT_INDENT,
+    maxLength: opts.maxLength ?? DEFAULT_MAX_LINE,
+  });
+}
+
 /**
  * Reformat `text` as consistently-indented JSON, or return `null` when it is not
  * valid JSON. Returning `null` (rather than throwing) lets callers skip a no-op
@@ -34,8 +52,5 @@ export function formatJson(
   } catch {
     return null;
   }
-  return stringify(parsed, {
-    indent: opts.indent ?? DEFAULT_INDENT,
-    maxLength: opts.maxLength ?? DEFAULT_MAX_LINE,
-  });
+  return formatSpec(parsed, opts);
 }