ovr 7.0.0-next.34 → 7.0.0-next.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # ovr
2
2
 
3
+ ## 7.0.0-next.36
4
+
5
+ ### Minor Changes
6
+
7
+ - 9c1bfab: `Render.raw` and `Render.escape` name markup `markup`, where it was `html`, like `Render.markup`: `Render.raw({ markup, markdown })` and `Render.escape({ markup })`.
8
+
9
+ ## 7.0.0-next.35
10
+
11
+ ### Minor Changes
12
+
13
+ - 599e2c5: `Render.escape` takes the text by where it goes, and escapes Markdown too: `Render.escape({ html })` for an element's content, `Render.escape({ attr })` for an attribute's value, where it was `Render.escape(text, true)`, and `Render.escape({ markdown })`, for text put into the Markdown `Render.raw` is given.
14
+
3
15
  ## 7.0.0-next.34
4
16
 
5
17
  ### Minor Changes
@@ -40,6 +40,11 @@ export declare namespace Markdown {
40
40
  */
41
41
  export declare class Markdown {
42
42
  #private;
43
+ /**
44
+ * @param text Plain text
45
+ * @returns The text escaped, to write in Markdown as it is
46
+ */
47
+ static escape(text: string): string;
43
48
  /**
44
49
  * Creates an `AsyncIterable` that renders the element to Markdown.
45
50
  *
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/markdown/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAiD3C,kFAAkF;AAClF,eAAO,MAAM,KAAK,eAAkB,CAAC;AAErC,yBAAiB,QAAQ,CAAC;IACzB,kCAAkC;IAClC,KAAY,OAAO,GAAG;QACrB,wEAAwE;QACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;QAEzC;;;;;;;;;;;;WAYG;QACH,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EACd,CAAC,CACD,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,GAAG,KAET;YACA,IAAI,EAAE,MAAM,CAAC;YACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC7B,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;YAC7B,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;SAC1B,GACD,SAAS,CAAC,GACZ,SAAS,CAAC;KACb,CAAC;CACF;AA41CD;;;;;;;;;;GAUG;AACH,qBAAa,QAAQ;;IAOpB;;;;;OAKG;IACH,YAAY,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,EAG3D;IAED,+CAA+C;IACxC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAWrE;IAED,4CAA4C;IAC5C,MAAM,gDAEL;IAED;;;;OAIG;IACG,MAAM,oBAcX;CACD"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/markdown/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAiD3C,kFAAkF;AAClF,eAAO,MAAM,KAAK,eAAkB,CAAC;AAErC,yBAAiB,QAAQ,CAAC;IACzB,kCAAkC;IAClC,KAAY,OAAO,GAAG;QACrB,wEAAwE;QACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;QAEzC;;;;;;;;;;;;WAYG;QACH,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EACd,CAAC,CACD,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,GAAG,KAET;YACA,IAAI,EAAE,MAAM,CAAC;YACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC7B,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;YAC7B,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;SAC1B,GACD,SAAS,CAAC,GACZ,SAAS,CAAC;KACb,CAAC;CACF;AAg3CD;;;;;;;;;;GAUG;AACH,qBAAa,QAAQ;;IACpB;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,UAEzB;IAQD;;;;;OAKG;IACH,YAAY,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,EAG3D;IAED,+CAA+C;IACxC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAWrE;IAED,4CAA4C;IAC5C,MAAM,gDAEL;IAED;;;;OAIG;IACG,MAAM,oBAcX;CACD"}
@@ -329,15 +329,33 @@ class Writer {
329
329
  #paragraph(children) {
330
330
  return this.#inline(children)
331
331
  .split("\n")
332
- .map((line) => line
333
- .trim()
334
- // a quote needs no space after it, and a line of `=` makes a heading of the one above
335
- .replace(/^(>|=+$|(?:[#+-]|-{2,})(?=\s|$))/, "\\$1")
336
- // the escape goes before the delimiter, one before a digit is text
337
- .replace(/^(\d+)([.)])(?=\s|$)/, "$1\\$2"))
332
+ .map((line) => Writer.#lead(line.trim()))
338
333
  .join("\n")
339
334
  .trim();
340
335
  }
336
+ /**
337
+ * @param line A line of text
338
+ * @returns The line with what would start a block escaped, such as a
339
+ * heading, a quote, or a list
340
+ */
341
+ static #lead(line) {
342
+ return (line
343
+ // a quote needs no space after it, and a line of `=` makes a heading of the one above
344
+ .replace(/^(\s*)(>|=+$|(?:[#+-]|-{2,})(?=\s|$))/, "$1\\$2")
345
+ // the escape goes before the delimiter, one before a digit is text
346
+ .replace(/^(\s*\d+)([.)])(?=\s|$)/, "$1\\$2"));
347
+ }
348
+ /**
349
+ * @param text Plain text, of one line or several
350
+ * @returns The text as Markdown that reads as the same text: its syntax
351
+ * characters escaped, and what would start a block on each line
352
+ */
353
+ static escape(text) {
354
+ return text
355
+ .split("\n")
356
+ .map((line) => Writer.#lead(Writer.#escape(line)))
357
+ .join("\n");
358
+ }
341
359
  /**
342
360
  * @param node Block element
343
361
  * @returns Markdown
@@ -1278,6 +1296,13 @@ class Blocks {
1278
1296
  * ```
1279
1297
  */
1280
1298
  export class Markdown {
1299
+ /**
1300
+ * @param text Plain text
1301
+ * @returns The text escaped, to write in Markdown as it is
1302
+ */
1303
+ static escape(text) {
1304
+ return Writer.escape(text);
1305
+ }
1281
1306
  /** Element to render */
1282
1307
  #element;
1283
1308
  /** Markdown options */
@@ -19,18 +19,35 @@ export declare namespace Render {
19
19
  /** Markdown options */
20
20
  type Options = MarkdownRender.Options;
21
21
  }
22
+ /** Text to escape, by where it goes: one of them */
23
+ type Escape = {
24
+ /** Text for an element's content */
25
+ readonly markup: string;
26
+ readonly attr?: never;
27
+ readonly markdown?: never;
28
+ } | {
29
+ /** Text for an attribute's value */
30
+ readonly attr: string;
31
+ readonly markup?: never;
32
+ readonly markdown?: never;
33
+ } | {
34
+ /** Text for Markdown */
35
+ readonly markdown: string;
36
+ readonly markup?: never;
37
+ readonly attr?: never;
38
+ };
22
39
  /**
23
40
  * What is written as it is, for people, agents, or both. With only
24
- * `html`, agents get the HTML too, which Markdown can contain.
41
+ * `markup`, agents get the markup too, which Markdown can contain.
25
42
  */
26
43
  type Raw = {
27
44
  /** Safe markup the page shows */
28
- readonly html: unknown;
45
+ readonly markup: unknown;
29
46
  /** What agents reading the page as Markdown get in its place, empty for nothing */
30
47
  readonly markdown?: unknown;
31
48
  } | {
32
49
  /** Safe markup the page shows, nothing when left out */
33
- readonly html?: unknown;
50
+ readonly markup?: unknown;
34
51
  /** What agents reading the page as Markdown get */
35
52
  readonly markdown: unknown;
36
53
  };
@@ -50,10 +67,10 @@ export declare class Render {
50
67
  * escaping, so both must be safe.
51
68
  *
52
69
  * ```tsx
53
- * Render.raw({ html: icon }); // the page and agents get the markup
54
- * Render.raw({ html: render(steps), markdown: steps }); // each its own
70
+ * Render.raw({ markup: icon }); // the page and agents get the markup
71
+ * Render.raw({ markup: render(steps), markdown: steps }); // each its own
55
72
  * Render.raw({ markdown: " · " }); // only agents
56
- * Render.raw({ html: button, markdown: "" }); // only the page
73
+ * Render.raw({ markup: button, markdown: "" }); // only the page
57
74
  * ```
58
75
  *
59
76
  * @param raw Safe markup for the page, and what agents get in its place
@@ -61,13 +78,20 @@ export declare class Render {
61
78
  */
62
79
  static raw(raw: Render.Raw): Render.Chunk;
63
80
  /**
64
- * Escapes text for markup.
81
+ * Escapes text, as a render does, to put in markup or Markdown you write
82
+ * yourself, such as what `Render.raw` is given.
83
+ *
84
+ * ```ts
85
+ * Render.escape({ markup: "a < b" }); // "a &lt; b"
86
+ * Render.escape({ attr: 'say "hi"' }); // "say &quot;hi&quot;"
87
+ * Render.escape({ markdown: "2 * 3" }); // "2 \\* 3"
88
+ * ```
65
89
  *
66
- * @param text Text to escape
67
- * @param attr Set to `true` if the value is an attribute, otherwise it is content
90
+ * @param text Text to escape, by where it goes: `markup` for an element's
91
+ * content, `attr` for an attribute's value, or `markdown`
68
92
  * @returns Escaped text
69
93
  */
70
- static escape(text: string, attr?: boolean): string;
94
+ static escape(text: Render.Escape): string;
71
95
  /**
72
96
  * Renders an element to markup, such as HTML, SVG, or XML.
73
97
  *
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACN,KAAK,IAAI,UAAU,EACnB,MAAM,IAAI,YAAY,EAEtB,MAAM,oBAAoB,CAAC;AAE5B,yBAAiB,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAiB,KAAM,SAAQ,UAAU;KAAG;IAE5C,+EAA+E;IAC/E,UAAiB,MAAO,SAAQ,YAAY;KAAG;IAE/C,UAAiB,MAAM,CAAC;QACvB,qBAAqB;QACrB,KAAY,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC;KAC3C;IAED,iFAAiF;IACjF,UAAiB,QAAS,SAAQ,cAAc;KAAG;IAEnD,UAAiB,QAAQ,CAAC;QACzB,uBAAuB;QACvB,KAAY,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC;KAC7C;IAED;;;OAGG;IACH,KAAY,GAAG,GACZ;QACA,iCAAiC;QACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QACvB,mFAAmF;QACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;KAC3B,GACD;QACA,wDAAwD;QACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QACxB,mDAAmD;QACnD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC1B,CAAC;CACL;AAED;;;;;;;;GAQG;AACH,qBAAa,MAAM;IAClB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAIxC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,UAEzC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,CACZ,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,GAC7B,MAAM,CAAC,MAAM,CAEf;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CACd,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,GAC/B,MAAM,CAAC,QAAQ,CAEjB;CACD"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACN,KAAK,IAAI,UAAU,EACnB,MAAM,IAAI,YAAY,EAEtB,MAAM,oBAAoB,CAAC;AAE5B,yBAAiB,MAAM,CAAC;IACvB,qEAAqE;IACrE,UAAiB,KAAM,SAAQ,UAAU;KAAG;IAE5C,+EAA+E;IAC/E,UAAiB,MAAO,SAAQ,YAAY;KAAG;IAE/C,UAAiB,MAAM,CAAC;QACvB,qBAAqB;QACrB,KAAY,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC;KAC3C;IAED,iFAAiF;IACjF,UAAiB,QAAS,SAAQ,cAAc;KAAG;IAEnD,UAAiB,QAAQ,CAAC;QACzB,uBAAuB;QACvB,KAAY,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC;KAC7C;IAED,oDAAoD;IACpD,KAAY,MAAM,GACf;QACA,oCAAoC;QACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;QACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;KACzB,GACD;QACA,oCAAoC;QACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;QACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;KACzB,GACD;QACA,wBAAwB;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;QACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;KACrB,CAAC;IAEL;;;OAGG;IACH,KAAY,GAAG,GACZ;QACA,iCAAiC;QACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACzB,mFAAmF;QACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;KAC3B,GACD;QACA,wDAAwD;QACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAC1B,mDAAmD;QACnD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;KAC1B,CAAC;CACL;AAED;;;;;;;;GAQG;AACH,qBAAa,MAAM;IAClB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAIxC;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,UAMhC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,CACZ,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,GAC7B,MAAM,CAAC,MAAM,CAEf;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CACd,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,GAC/B,MAAM,CAAC,QAAQ,CAEjB;CACD"}
@@ -15,10 +15,10 @@ export class Render {
15
15
  * escaping, so both must be safe.
16
16
  *
17
17
  * ```tsx
18
- * Render.raw({ html: icon }); // the page and agents get the markup
19
- * Render.raw({ html: render(steps), markdown: steps }); // each its own
18
+ * Render.raw({ markup: icon }); // the page and agents get the markup
19
+ * Render.raw({ markup: render(steps), markdown: steps }); // each its own
20
20
  * Render.raw({ markdown: " · " }); // only agents
21
- * Render.raw({ html: button, markdown: "" }); // only the page
21
+ * Render.raw({ markup: button, markdown: "" }); // only the page
22
22
  * ```
23
23
  *
24
24
  * @param raw Safe markup for the page, and what agents get in its place
@@ -26,18 +26,29 @@ export class Render {
26
26
  */
27
27
  static raw(raw) {
28
28
  return raw.markdown === undefined
29
- ? new ChunkClass(raw.html, true)
30
- : new Source(raw.markdown, raw.html);
29
+ ? new ChunkClass(raw.markup, true)
30
+ : new Source(raw.markdown, raw.markup);
31
31
  }
32
32
  /**
33
- * Escapes text for markup.
33
+ * Escapes text, as a render does, to put in markup or Markdown you write
34
+ * yourself, such as what `Render.raw` is given.
34
35
  *
35
- * @param text Text to escape
36
- * @param attr Set to `true` if the value is an attribute, otherwise it is content
36
+ * ```ts
37
+ * Render.escape({ markup: "a < b" }); // "a &lt; b"
38
+ * Render.escape({ attr: 'say "hi"' }); // "say &quot;hi&quot;"
39
+ * Render.escape({ markdown: "2 * 3" }); // "2 \\* 3"
40
+ * ```
41
+ *
42
+ * @param text Text to escape, by where it goes: `markup` for an element's
43
+ * content, `attr` for an attribute's value, or `markdown`
37
44
  * @returns Escaped text
38
45
  */
39
- static escape(text, attr) {
40
- return MarkupRender.escape(text, attr);
46
+ static escape(text) {
47
+ return text.markdown !== undefined
48
+ ? MarkdownRender.escape(text.markdown)
49
+ : text.attr !== undefined
50
+ ? MarkupRender.escape(text.attr, true)
51
+ : MarkupRender.escape(text.markup);
41
52
  }
42
53
  /**
43
54
  * Renders an element to markup, such as HTML, SVG, or XML.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "ovr",
3
3
  "description": "Web apps anyone can use. Each route serves people a page and agents Markdown and MCP tools, with forms, Postgres, and passkey sign-in built in.",
4
- "version": "7.0.0-next.34",
4
+ "version": "7.0.0-next.36",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
@@ -437,18 +437,38 @@ class Writer {
437
437
  #paragraph(children: (Node | string)[]) {
438
438
  return this.#inline(children)
439
439
  .split("\n")
440
- .map((line) =>
441
- line
442
- .trim()
443
- // a quote needs no space after it, and a line of `=` makes a heading of the one above
444
- .replace(/^(>|=+$|(?:[#+-]|-{2,})(?=\s|$))/, "\\$1")
445
- // the escape goes before the delimiter, one before a digit is text
446
- .replace(/^(\d+)([.)])(?=\s|$)/, "$1\\$2"),
447
- )
440
+ .map((line) => Writer.#lead(line.trim()))
448
441
  .join("\n")
449
442
  .trim();
450
443
  }
451
444
 
445
+ /**
446
+ * @param line A line of text
447
+ * @returns The line with what would start a block escaped, such as a
448
+ * heading, a quote, or a list
449
+ */
450
+ static #lead(line: string) {
451
+ return (
452
+ line
453
+ // a quote needs no space after it, and a line of `=` makes a heading of the one above
454
+ .replace(/^(\s*)(>|=+$|(?:[#+-]|-{2,})(?=\s|$))/, "$1\\$2")
455
+ // the escape goes before the delimiter, one before a digit is text
456
+ .replace(/^(\s*\d+)([.)])(?=\s|$)/, "$1\\$2")
457
+ );
458
+ }
459
+
460
+ /**
461
+ * @param text Plain text, of one line or several
462
+ * @returns The text as Markdown that reads as the same text: its syntax
463
+ * characters escaped, and what would start a block on each line
464
+ */
465
+ static escape(text: string) {
466
+ return text
467
+ .split("\n")
468
+ .map((line) => Writer.#lead(Writer.#escape(line)))
469
+ .join("\n");
470
+ }
471
+
452
472
  /**
453
473
  * @param node Block element
454
474
  * @returns Markdown
@@ -1467,6 +1487,14 @@ class Blocks {
1467
1487
  * ```
1468
1488
  */
1469
1489
  export class Markdown {
1490
+ /**
1491
+ * @param text Plain text
1492
+ * @returns The text escaped, to write in Markdown as it is
1493
+ */
1494
+ static escape(text: string) {
1495
+ return Writer.escape(text);
1496
+ }
1497
+
1470
1498
  /** Element to render */
1471
1499
  readonly #element: JSX.Element;
1472
1500
 
@@ -26,20 +26,41 @@ export namespace Render {
26
26
  export type Options = MarkdownRender.Options;
27
27
  }
28
28
 
29
+ /** Text to escape, by where it goes: one of them */
30
+ export type Escape =
31
+ | {
32
+ /** Text for an element's content */
33
+ readonly markup: string;
34
+ readonly attr?: never;
35
+ readonly markdown?: never;
36
+ }
37
+ | {
38
+ /** Text for an attribute's value */
39
+ readonly attr: string;
40
+ readonly markup?: never;
41
+ readonly markdown?: never;
42
+ }
43
+ | {
44
+ /** Text for Markdown */
45
+ readonly markdown: string;
46
+ readonly markup?: never;
47
+ readonly attr?: never;
48
+ };
49
+
29
50
  /**
30
51
  * What is written as it is, for people, agents, or both. With only
31
- * `html`, agents get the HTML too, which Markdown can contain.
52
+ * `markup`, agents get the markup too, which Markdown can contain.
32
53
  */
33
54
  export type Raw =
34
55
  | {
35
56
  /** Safe markup the page shows */
36
- readonly html: unknown;
57
+ readonly markup: unknown;
37
58
  /** What agents reading the page as Markdown get in its place, empty for nothing */
38
59
  readonly markdown?: unknown;
39
60
  }
40
61
  | {
41
62
  /** Safe markup the page shows, nothing when left out */
42
- readonly html?: unknown;
63
+ readonly markup?: unknown;
43
64
  /** What agents reading the page as Markdown get */
44
65
  readonly markdown: unknown;
45
66
  };
@@ -60,10 +81,10 @@ export class Render {
60
81
  * escaping, so both must be safe.
61
82
  *
62
83
  * ```tsx
63
- * Render.raw({ html: icon }); // the page and agents get the markup
64
- * Render.raw({ html: render(steps), markdown: steps }); // each its own
84
+ * Render.raw({ markup: icon }); // the page and agents get the markup
85
+ * Render.raw({ markup: render(steps), markdown: steps }); // each its own
65
86
  * Render.raw({ markdown: " · " }); // only agents
66
- * Render.raw({ html: button, markdown: "" }); // only the page
87
+ * Render.raw({ markup: button, markdown: "" }); // only the page
67
88
  * ```
68
89
  *
69
90
  * @param raw Safe markup for the page, and what agents get in its place
@@ -71,19 +92,30 @@ export class Render {
71
92
  */
72
93
  static raw(raw: Render.Raw): Render.Chunk {
73
94
  return raw.markdown === undefined
74
- ? new ChunkClass(raw.html, true)
75
- : new Source(raw.markdown, raw.html);
95
+ ? new ChunkClass(raw.markup, true)
96
+ : new Source(raw.markdown, raw.markup);
76
97
  }
77
98
 
78
99
  /**
79
- * Escapes text for markup.
100
+ * Escapes text, as a render does, to put in markup or Markdown you write
101
+ * yourself, such as what `Render.raw` is given.
102
+ *
103
+ * ```ts
104
+ * Render.escape({ markup: "a < b" }); // "a &lt; b"
105
+ * Render.escape({ attr: 'say "hi"' }); // "say &quot;hi&quot;"
106
+ * Render.escape({ markdown: "2 * 3" }); // "2 \\* 3"
107
+ * ```
80
108
  *
81
- * @param text Text to escape
82
- * @param attr Set to `true` if the value is an attribute, otherwise it is content
109
+ * @param text Text to escape, by where it goes: `markup` for an element's
110
+ * content, `attr` for an attribute's value, or `markdown`
83
111
  * @returns Escaped text
84
112
  */
85
- static escape(text: string, attr?: boolean) {
86
- return MarkupRender.escape(text, attr);
113
+ static escape(text: Render.Escape) {
114
+ return text.markdown !== undefined
115
+ ? MarkdownRender.escape(text.markdown)
116
+ : text.attr !== undefined
117
+ ? MarkupRender.escape(text.attr, true)
118
+ : MarkupRender.escape(text.markup);
87
119
  }
88
120
 
89
121
  /**