@bendyline/docblocks-cli 2.7.2 → 2.7.3

package/THIRD_PARTY_NOTICES.txt

@@ -15,11 +15,11 @@ This notice is included in the published npm tarball. Transitive packages instal
 | Package | Version | License | Source |
 | --- | --- | --- | --- |
 | @antfu/install-pkg | 2.1.0 | MIT | https://github.com/antfu-collective/install-pkg |
-| @bendyline/squisq | 2.12.0 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-cli | 2.9.1 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-formats | 2.7.1 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-react | 2.12.1 | MIT | https://github.com/bendyline/squisq |
-| @bendyline/squisq-video | 2.4.0 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq | 2.12.3 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-cli | 2.9.5 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-formats | 2.7.3 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-react | 2.12.4 | MIT | https://github.com/bendyline/squisq |
+| @bendyline/squisq-video | 2.4.3 | MIT | https://github.com/bendyline/squisq |
 | @braintree/sanitize-url | 7.1.2 | MIT | https://github.com/braintree/sanitize-url |
 | @chevrotain/types | 11.1.2 | Apache-2.0 | https://github.com/Chevrotain/chevrotain |
 | @ffmpeg/ffmpeg | 0.12.15 | MIT | https://github.com/ffmpegwasm/ffmpeg.wasm |
@@ -409,7 +409,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.9.1, @bendyline/squisq-formats@2.7.1, @bendyline/squisq-react@2.12.1, @bendyline/squisq-video@2.4.0, @bendyline/squisq@2.12.0
+Components: @bendyline/squisq-cli@2.9.5, @bendyline/squisq-formats@2.7.3, @bendyline/squisq-react@2.12.4, @bendyline/squisq-video@2.4.3, @bendyline/squisq@2.12.3
 Source files: node_modules/@bendyline/squisq-cli/LICENSE, node_modules/@bendyline/squisq-formats/LICENSE, node_modules/@bendyline/squisq-react/LICENSE, node_modules/@bendyline/squisq-video/LICENSE, node_modules/@bendyline/squisq/LICENSE
 ==============================================================================
 MIT License
@@ -679,7 +679,7 @@ This software contains code derived from the Puppeteer project (https://github.c
 available under the Apache 2.0 license (https://github.com/puppeteer/puppeteer/blob/master/LICENSE).
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.9.1
+Components: @bendyline/squisq-cli@2.9.5
 Source files: node_modules/@bendyline/squisq-cli/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-cli
@@ -699,7 +699,7 @@ Copyright and complete license texts for these dependencies are included in
 their respective npm distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-cli@2.9.1
+Components: @bendyline/squisq-cli@2.9.5
 Source files: node_modules/@bendyline/squisq-cli/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-cli
@@ -5869,7 +5869,7 @@ The above copyright notice and this permission notice shall be included in all c
 **THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.**
 
 ==============================================================================
-Components: @bendyline/squisq-formats@2.7.1
+Components: @bendyline/squisq-formats@2.7.3
 Source files: node_modules/@bendyline/squisq-formats/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-formats
@@ -5895,7 +5895,7 @@ texts for these dependencies are included in their respective npm
 distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-formats@2.7.1
+Components: @bendyline/squisq-formats@2.7.3
 Source files: node_modules/@bendyline/squisq-formats/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-formats
@@ -5906,6 +5906,7 @@ repository license, the pinned upstream copy is vendored and identified below.
 
 COMPONENTS
 - @fortawesome/fontawesome-free@7.3.1 ((CC-BY-4.0 AND OFL-1.1 AND MIT)); files: LICENSE.txt
+- dejavu-fonts-ttf@2.37.3 (SEE LICENSE IN README.md AND LICENSE); files: LICENSE
 
 ==============================================================================
 @fortawesome/fontawesome-free@7.3.1 - LICENSE.txt
@@ -6077,7 +6078,198 @@ Awesome, nor vice versa. **Please do not use brand logos for any purpose except
 to represent the company, product, or service to which they refer.**
 
 ==============================================================================
-Components: @bendyline/squisq-react@2.12.1
+dejavu-fonts-ttf@2.37.3 - LICENSE
+==============================================================================
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
+
+
+Bitstream Vera Fonts Copyright
+------------------------------
+
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
+a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license ("Fonts") and associated
+documentation files (the "Font Software"), to reproduce and distribute the
+Font Software, including without limitation the rights to use, copy, merge,
+publish, distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright and trademark notices and this permission notice shall
+be included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional glyphs or characters may be added to the Fonts, only if the fonts
+are renamed to names not containing either the words "Bitstream" or the word
+"Vera".
+
+This License becomes null and void to the extent applicable to Fonts or Font
+Software that has been modified and is distributed under the "Bitstream
+Vera" names.
+
+The Font Software may be sold as part of a larger software package but no
+copy of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+FONT SOFTWARE.
+
+Except as contained in this notice, the names of Gnome, the Gnome
+Foundation, and Bitstream Inc., shall not be used in advertising or
+otherwise to promote the sale, use or other dealings in this Font Software
+without prior written authorization from the Gnome Foundation or Bitstream
+Inc., respectively. For further information, contact: fonts at gnome dot
+org.
+
+Arev Fonts Copyright
+------------------------------
+
+Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the fonts accompanying this license ("Fonts") and
+associated documentation files (the "Font Software"), to reproduce
+and distribute the modifications to the Bitstream Vera Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be included in all copies of one or more of the Font Software
+typefaces.
+
+The Font Software may be modified, altered, or added to, and in
+particular the designs of glyphs or characters in the Fonts may be
+modified and additional glyphs or characters may be added to the
+Fonts, only if the fonts are renamed to names not containing either
+the words "Tavmjong Bah" or the word "Arev".
+
+This License becomes null and void to the extent applicable to Fonts
+or Font Software that has been modified and is distributed under the 
+"Tavmjong Bah Arev" names.
+
+The Font Software may be sold as part of a larger software package but
+no copy of one or more of the Font Software typefaces may be sold by
+itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+Except as contained in this notice, the name of Tavmjong Bah shall not
+be used in advertising or otherwise to promote the sale, use or other
+dealings in this Font Software without prior written authorization
+from Tavmjong Bah. For further information, contact: tavmjong @ free
+. fr.
+
+TeX Gyre DJV Math
+-----------------
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+
+Math extensions done by B. Jackowski, P. Strzelczyk and P. Pianowski
+(on behalf of TeX users groups) are in public domain.
+
+Letters imported from Euler Fraktur from AMSfonts are (c) American
+Mathematical Society (see below).
+Bitstream Vera Fonts Copyright
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera
+is a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license (“Fonts”) and associated
+documentation
+files (the “Font Software”), to reproduce and distribute the Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute,
+and/or sell copies of the Font Software, and to permit persons  to whom
+the Font Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be
+included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional
+glyphs or characters may be added to the Fonts, only if the fonts are
+renamed
+to names not containing either the words “Bitstream” or the word “Vera”.
+
+This License becomes null and void to the extent applicable to Fonts or
+Font Software
+that has been modified and is distributed under the “Bitstream Vera”
+names.
+
+The Font Software may be sold as part of a larger software package but
+no copy
+of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL,
+SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN
+ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR
+INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
+Except as contained in this notice, the names of GNOME, the GNOME
+Foundation,
+and Bitstream Inc., shall not be used in advertising or otherwise to promote
+the sale, use or other dealings in this Font Software without prior written
+authorization from the GNOME Foundation or Bitstream Inc., respectively.
+For further information, contact: fonts at gnome dot org.
+
+AMSFonts (v. 2.2) copyright
+
+The PostScript Type 1 implementation of the AMSFonts produced by and
+previously distributed by Blue Sky Research and Y&Y, Inc. are now freely
+available for general use. This has been accomplished through the
+cooperation
+of a consortium of scientific publishers with Blue Sky Research and Y&Y.
+Members of this consortium include:
+
+Elsevier Science IBM Corporation Society for Industrial and Applied
+Mathematics (SIAM) Springer-Verlag American Mathematical Society (AMS)
+
+In order to assure the authenticity of these fonts, copyright will be
+held by
+the American Mathematical Society. This is not meant to restrict in any way
+the legitimate use of the fonts, such as (but not limited to) electronic
+distribution of documents containing these fonts, inclusion of these fonts
+into other public domain or commercial font collections or computer
+applications, use of the outline data to create derivative fonts and/or
+faces, etc. However, the AMS does require that the AMS copyright notice be
+removed from any derivative versions of the fonts which have been altered in
+any way. In addition, to ensure the fidelity of TeX documents using Computer
+Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
+has requested that any alterations which yield different font metrics be
+given a different name.
+
+$Id$
+
+==============================================================================
+Components: @bendyline/squisq-react@2.12.4
 Source files: node_modules/@bendyline/squisq-react/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-react
@@ -6102,7 +6294,7 @@ third-party license texts for the complete standalone bundle graph are shipped
 in THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq-react@2.12.1
+Components: @bendyline/squisq-react@2.12.4
 Source files: node_modules/@bendyline/squisq-react/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-react
@@ -11031,7 +11223,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 ==============================================================================
-Components: @bendyline/squisq-video@2.4.0
+Components: @bendyline/squisq-video@2.4.3
 Source files: node_modules/@bendyline/squisq-video/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq-video
@@ -11056,7 +11248,7 @@ Copyright and complete license texts for the listed dependencies are included
 in their respective npm distributions and source repositories.
 
 ==============================================================================
-Components: @bendyline/squisq-video@2.4.0
+Components: @bendyline/squisq-video@2.4.3
 Source files: node_modules/@bendyline/squisq-video/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq-video
@@ -11068,7 +11260,7 @@ repository license, the pinned upstream copy is vendored and identified below.
 COMPONENTS
 
 ==============================================================================
-Components: @bendyline/squisq@2.12.0
+Components: @bendyline/squisq@2.12.3
 Source files: node_modules/@bendyline/squisq/NOTICE.md
 ==============================================================================
 # Third-Party Notices for @bendyline/squisq
@@ -11099,7 +11291,7 @@ third-party license texts for bundled code and data are shipped in
 THIRD_PARTY_LICENSES.txt.
 
 ==============================================================================
-Components: @bendyline/squisq@2.12.0
+Components: @bendyline/squisq@2.12.3
 Source files: node_modules/@bendyline/squisq/THIRD_PARTY_LICENSES.txt
 ==============================================================================
 THIRD-PARTY LICENSES FOR @bendyline/squisq

package/dist/bin.js

@@ -1824,7 +1824,13 @@ async function inspectPreparedDocument(_documents, prepared, maximumBlocks = DEF
       (diagnostic) => mapDocDiagnostic(diagnostic, prepared.sourceFormat)
     ),
     ...missingAltTextDiagnostics(prepared.markdownDoc, prepared.sourceFormat),
-    ...await authoringDiagnostics(prepared, "inspect", prepared.sourceFormat, signal)
+    ...await authoringDiagnostics(prepared, "inspect", prepared.sourceFormat, signal),
+    ...await svgPictureDiagnostics(
+      prepared.markdownDoc,
+      "inspect",
+      prepared.sourceFormat,
+      signal
+    )
   ];
   let wordCount = 0;
   for (let index = 0; index < analyzed.length; index += 1) {
@@ -2433,6 +2439,172 @@ function missingAltTextDiagnostics(markdownDoc, format) {
     }
   ];
 }
+async function svgPictureDiagnostics(markdownDoc, stage, format, signal) {
+  throwIfAborted5(signal);
+  const { SVG_ISLAND_LIMITS, isSvgIslandLang, parseSvgIsland } = await import("@bendyline/squisq/markdown");
+  const diagnostics = [];
+  const untitled = [];
+  let fenceCount = 0;
+  const pending = [markdownDoc];
+  let visited = 0;
+  while (pending.length > 0) {
+    const checkpoint = cancellationCheckpoint(signal, visited);
+    if (checkpoint) await checkpoint;
+    visited += 1;
+    const node = pending.pop();
+    if (!node || typeof node !== "object") continue;
+    const candidate = node;
+    if (candidate.type === "code" && typeof candidate.value === "string" && isSvgIslandLang(typeof candidate.lang === "string" ? candidate.lang : null)) {
+      fenceCount += 1;
+      if (fenceCount > MAX_SVG_FENCES_ANALYZED) continue;
+      const location = sourceLocation(candidate.position);
+      const result = parseSvgIsland(candidate.value);
+      if (!result.ok) {
+        diagnostics.push(
+          svgFenceNotRenderedDiagnostic(result, location, stage, format, SVG_ISLAND_LIMITS)
+        );
+        continue;
+      }
+      if (result.diagnostics.length > 0) {
+        diagnostics.push(svgContentRemovedDiagnostic(result.diagnostics, location, stage, format));
+      }
+      if (result.island.title === void 0) untitled.push(location);
+      continue;
+    }
+    if (candidate.type === "htmlBlock" || candidate.type === "htmlInline") {
+      const svgCount = countSvgElements(candidate.htmlChildren);
+      if (svgCount > 0) {
+        diagnostics.push(
+          rawSvgHtmlDiagnostic(svgCount, sourceLocation(candidate.position), stage, format)
+        );
+      }
+    }
+    if (Array.isArray(candidate.children)) {
+      for (let index = candidate.children.length - 1; index >= 0; index -= 1) {
+        pending.push(candidate.children[index]);
+      }
+    }
+  }
+  if (untitled.length > 0) {
+    diagnostics.push(svgMissingTitleDiagnostic(untitled, stage, format));
+  }
+  if (fenceCount > MAX_SVG_FENCES_ANALYZED) {
+    diagnostics.push({
+      code: "svg-analysis-truncated",
+      severity: "info",
+      stage,
+      format,
+      count: fenceCount - MAX_SVG_FENCES_ANALYZED,
+      message: `SVG diagnostics analyzed the first ${MAX_SVG_FENCES_ANALYZED} of ${fenceCount} \`\`\`svg fences.`,
+      remediation: "Split the document before requesting exhaustive SVG picture diagnostics.",
+      retryable: false,
+      location: null
+    });
+  }
+  return diagnostics;
+}
+function svgFenceLabel(location) {
+  return location ? `The \`\`\`svg fence at line ${location.line}` : "A ```svg fence";
+}
+function svgFenceNotRenderedDiagnostic(result, location, stage, format, limits) {
+  const sourceKiB = Math.floor(limits.maxSourceBytes / 1024);
+  const remediation = {
+    empty: "Put one complete <svg>\u2026</svg> element in the fence, or delete the fence.",
+    "not-svg": "Keep exactly one <svg> root element in the fence and nothing beside it. To show SVG source as code instead, use an ```xml fence.",
+    "too-large": `Simplify the picture and remove circular <use> references: a fence must stay under ${sourceKiB} KiB of source, ${limits.maxElements} elements, and ${limits.maxExpandedElements} elements after <use> expansion.`,
+    "too-deep": `Flatten nested groups: a fence may nest elements at most ${limits.maxDepth} levels deep.`,
+    parse: "Repair the markup so the fence holds one well-formed <svg> element."
+  }[result.reason];
+  return {
+    code: "svg-fence-not-rendered",
+    severity: "error",
+    stage,
+    format,
+    count: 1,
+    message: `${svgFenceLabel(location)} cannot be drawn (${result.reason}): ${result.message} It shows as code, or as a placeholder on slides, instead of a picture.`,
+    remediation,
+    retryable: false,
+    location
+  };
+}
+function svgContentRemovedDiagnostic(removals, location, stage, format) {
+  const listed = removals.slice(0, MAX_LISTED_SVG_REMOVALS).map(({ kind, name, count }) => {
+    const bounded = name.slice(0, MAX_SVG_REMOVAL_NAME_CHARACTERS);
+    return `${kind === "element" ? `<${bounded}>` : bounded} \xD7${count}`;
+  });
+  const omitted = removals.length - listed.length;
+  const occurrences = removals.reduce(
+    (sum, removal) => safeDiagnosticCountSum(sum, removal.count),
+    0
+  );
+  return {
+    code: "svg-content-removed",
+    severity: "warning",
+    stage,
+    format,
+    count: Math.max(1, occurrences),
+    message: `${svgFenceLabel(location)} draws, but the sanitizer removed ${listed.join(", ")}${omitted > 0 ? `, and ${omitted} more` : ""}.`,
+    remediation: "Delete the removed content or replace it with what renders: inline shapes and text, #id and url(#id) references, base64 PNG, JPEG, GIF, or WebP <image> data, and system fonts. Scripts, event handlers, foreignObject, external links or images, @import, and @font-face never render.",
+    retryable: false,
+    location
+  };
+}
+function svgMissingTitleDiagnostic(locations, stage, format) {
+  const lines = locations.filter((location) => location !== null).map(({ line }) => line);
+  const listedLines = lines.length === 0 ? "" : ` (line${lines.length === 1 ? "" : "s"} ${lines.slice(0, MAX_LISTED_SVG_LINES).join(", ")}${lines.length > MAX_LISTED_SVG_LINES ? ", \u2026" : ""})`;
+  return {
+    code: "svg-missing-title",
+    severity: "warning",
+    stage,
+    format,
+    count: locations.length,
+    message: locations.length === 1 ? `One \`\`\`svg fence has no accessible name${listedLines}.` : `${locations.length} \`\`\`svg fences have no accessible name${listedLines}.`,
+    remediation: "Add a concise <title> as the first child of each <svg> root, or an aria-label on the root; it becomes the alternative text.",
+    retryable: false,
+    location: locations.length === 1 ? locations[0] ?? null : null
+  };
+}
+function rawSvgHtmlDiagnostic(count, location, stage, format) {
+  return {
+    code: "raw-svg-html-dropped",
+    severity: "warning",
+    stage,
+    format,
+    count,
+    message: `${location ? `Raw <svg> HTML at line ${location.line}` : "Raw <svg> HTML"} is removed by the Markdown sanitizer, so it never shows as a picture.`,
+    remediation: "Wrap the markup in a ```svg fence to draw it as a picture, or in an ```xml fence to show it as code.",
+    retryable: false,
+    location
+  };
+}
+function countSvgElements(htmlChildren) {
+  let count = 0;
+  const pending = Array.isArray(htmlChildren) ? [...htmlChildren] : [];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (!node || typeof node !== "object") continue;
+    const element = node;
+    if (element.type !== "htmlElement") continue;
+    if (typeof element.tagName === "string" && element.tagName.toLowerCase() === "svg") {
+      count += 1;
+      continue;
+    }
+    if (Array.isArray(element.children)) {
+      for (const child of element.children) pending.push(child);
+    }
+  }
+  return count;
+}
+function sourceLocation(position) {
+  if (!position || typeof position !== "object") return null;
+  const start = position.start;
+  if (!start || typeof start !== "object") return null;
+  const { line, column } = start;
+  if (typeof line !== "number" || typeof column !== "number" || !Number.isSafeInteger(line) || !Number.isSafeInteger(column) || line < 1 || column < 1) {
+    return null;
+  }
+  return { kind: "source", line, column };
+}
 function boundDiagnostics(diagnostics, stage) {
   const aggregated = aggregateDiagnostics(diagnostics);
   if (aggregated.length <= MAX_DIAGNOSTICS) return aggregated;
@@ -2651,7 +2823,7 @@ function change(category, similarity, label, leftCount, rightCount) {
 function clamp01(value) {
   return Math.max(0, Math.min(1, Number(value.toFixed(6))));
 }
-var DEFAULT_MAX_INSPECTION_BLOCKS, MAX_INSPECTION_BLOCKS, MCP_MAX_PUBLISHED_DIAGNOSTICS, MAX_DIAGNOSTICS, FORMAT_PATTERN, CANCELLATION_YIELD_INTERVAL;
+var DEFAULT_MAX_INSPECTION_BLOCKS, MAX_INSPECTION_BLOCKS, MCP_MAX_PUBLISHED_DIAGNOSTICS, MAX_DIAGNOSTICS, FORMAT_PATTERN, CANCELLATION_YIELD_INTERVAL, MAX_SVG_FENCES_ANALYZED, MAX_LISTED_SVG_REMOVALS, MAX_LISTED_SVG_LINES, MAX_SVG_REMOVAL_NAME_CHARACTERS;
 var init_intelligence = __esm({
   "src/mcp/intelligence.ts"() {
     "use strict";
@@ -2664,6 +2836,10 @@ var init_intelligence = __esm({
     MAX_DIAGNOSTICS = MCP_MAX_PUBLISHED_DIAGNOSTICS;
     FORMAT_PATTERN = /^[a-z0-9][a-z0-9.+_-]{0,63}$/u;
     CANCELLATION_YIELD_INTERVAL = 256;
+    MAX_SVG_FENCES_ANALYZED = 1e3;
+    MAX_LISTED_SVG_REMOVALS = 12;
+    MAX_LISTED_SVG_LINES = 10;
+    MAX_SVG_REMOVAL_NAME_CHARACTERS = 64;
   }
 });
 
@@ -4211,6 +4387,86 @@ var init_preview_content = __esm({
   }
 });
 
+// src/mcp/picture-guidance.ts
+function pictureExportGuidance(targetFormat) {
+  switch (targetFormat) {
+    case "pptx":
+      return "PPTX exports Mermaid as source text; draw flows as ```svg. Other pictures draw.";
+    case "docx":
+    case "epub":
+      return "In DOCX and EPUB only ```svg becomes a picture; Mermaid, timeline and tree fences export as source text, so draw pictures that must survive as ```svg.";
+    case "pdf":
+      return 'Semantic PDF prints every picture fence as source text. Use fidelity "rendered-fidelity" only when pictures matter more than selectable text; Mermaid still does not draw there.';
+    default:
+      return null;
+  }
+}
+function documentPictureHint(target) {
+  return target === "docx" ? `For pictures use ${SVG_FENCE_SUMMARY}; DOCX keeps Mermaid, timeline and tree fences as source text, and raw <svg> HTML is silently dropped.` : `For pictures use ${SVG_FENCE_SUMMARY}; raw <svg> HTML is silently dropped. Semantic PDF prints picture fences as source text, so pass fidelity "rendered-fidelity" when pictures matter more than selectable text.`;
+}
+async function authoringGuidePictures() {
+  const [{ SVG_ISLAND_LIMITS }, { TABLE_FED_TEMPLATES, getAvailableTemplates }] = await Promise.all(
+    [import("@bendyline/squisq/markdown"), import("@bendyline/squisq/doc")]
+  );
+  const available = new Set(getAvailableTemplates());
+  const chartTemplates = [...TABLE_FED_TEMPLATES].filter(
+    (id) => id !== "dataTable" && available.has(id)
+  );
+  const sourceKiB = Math.floor(SVG_ISLAND_LIMITS.maxSourceBytes / 1024);
+  return {
+    choose: [
+      "```mermaid for flows, sequences, state machines, hierarchies, and gantt schedules.",
+      "```timeline for dated events: one rail per track, for example `\u25CF 2020 Founded \u2500\u2500\u2500\u25CF 2022 Launch \u2500\u2500\u2500\u25BA`.",
+      "```tree for outlines and file trees drawn with \u251C\u2500\u2500 and \u2514\u2500\u2500 branches.",
+      "A Markdown table under a heading annotated with a chart template for numbers, for example `## Revenue {[barChart]}`. Every chart template reads the first table in its block.",
+      "```svg for bespoke illustrations, icons, annotated figures, and anything the formats above cannot draw.",
+      "A sidecar `![alt](assets/name.svg)` image only for large or reused artwork. Pass it as a bundle asset, or stage it with create_document_bundle, so it travels with the document. Sidecar SVG is sanitized like a fence but keeps its own colors.",
+      "The diagram, drawing, and layout container templates build pictures from child headings; use describe_template for their inputs."
+    ],
+    chartTemplates,
+    svgRules: [
+      'Exactly one <svg> root with a viewBox, for example viewBox="0 0 640 360", and nothing beside it.',
+      "A <title> as the first child: it becomes the alt text. A root aria-label also works.",
+      'currentColor for strokes and text, and fill="none" or currentColor with fill-opacity, instead of hard-coded black or white. Fences then follow the theme text color on screen, in slides, DOCX, and EPUB. Accent colors are fine, but nothing inside the picture follows dark mode or CSS variables.',
+      "No script, foreignObject, on* event handlers, external href or xlink:href links and images, url() other than url(#id), @import, or @font-face web fonts: the sanitizer removes them. <image> accepts only base64 PNG, JPEG, GIF, or WebP data URIs.",
+      'font-family="sans-serif": pictures render with system fonts, never the page or theme fonts. Keep labels short and keep all text inside the viewBox.',
+      `Stay well under the limits: ${sourceKiB} KiB of source, ${SVG_ISLAND_LIMITS.maxElements} elements, nesting depth ${SVG_ISLAND_LIMITS.maxDepth}, and ${SVG_ISLAND_LIMITS.maxExpandedElements} elements after <use> expansion. A fence past any limit shows as code.`
+    ],
+    svgExample: SVG_ISLAND_EXAMPLE,
+    never: "Never write raw <svg> HTML in Markdown: the sanitizer silently drops it with its content. Use a ```svg fence to draw it, or an ```xml fence to show SVG source as code.",
+    exports: [
+      "convert_document embeds ```svg as a vector picture in DOCX, PPTX, EPUB, and HTML.",
+      "PPTX also draws timeline, tree, and chart pictures as native shapes.",
+      "Mermaid exports as source text in DOCX, PPTX, EPUB, and PDF; timeline and tree fences do too in DOCX, EPUB, and PDF. Draw a picture that must survive those exports as ```svg.",
+      "Semantic PDF prints every picture fence as source text. Rendered-fidelity PDF draws ```svg, timeline, tree, and chart pictures, but not Mermaid."
+    ],
+    check: 'inspect_document reports a ```svg fence that will not draw (svg-fence-not-rendered), content the sanitizer removed (svg-content-removed), a missing <title> (svg-missing-title), and raw <svg> HTML (raw-svg-html-dropped). preview_document draws ```svg, timeline, tree, and chart pictures, or a dashed "Couldn\'t render this SVG" placeholder for a broken fence; Mermaid shows a placeholder there.'
+  };
+}
+var PICTURE_SELECTION_GUIDANCE, PICTURE_INSTRUCTION_GUIDANCE, SVG_FENCE_SUMMARY, PRESENTATION_PICTURE_HINT, SVG_ISLAND_EXAMPLE;
+var init_picture_guidance = __esm({
+  "src/mcp/picture-guidance.ts"() {
+    "use strict";
+    PICTURE_SELECTION_GUIDANCE = 'Pictures: ```mermaid for flows, sequences, states, hierarchies, gantt; ```timeline for dated events; ```tree for outlines; a table under `## Sales {[barChart]}` for numbers; ```svg for bespoke illustrations, icons, annotated figures. In ```svg: one <svg> root with a viewBox and <title>, currentColor strokes and text, font-family="sans-serif"; no script, foreignObject, event handlers, external links or web fonts. Never raw <svg> HTML (silently dropped); use ```xml to show SVG source. inspect_document flags broken ```svg.';
+    PICTURE_INSTRUCTION_GUIDANCE = "Draw pictures with fences, never raw <svg> HTML, which is silently dropped: ```svg for bespoke art, ```mermaid, ```timeline, ```tree, or a chart template over a table. get_authoring_context gives target-specific picture rules.";
+    SVG_FENCE_SUMMARY = "a ```svg fence (one <svg> root with a viewBox, a <title>, and currentColor strokes and text)";
+    PRESENTATION_PICTURE_HINT = `For pictures use ${SVG_FENCE_SUMMARY}, \`\`\`timeline, \`\`\`tree, or a chart template over a table; Mermaid exports to PPTX as source text, and raw <svg> HTML is silently dropped.`;
+    SVG_ISLAND_EXAMPLE = [
+      "```svg",
+      '<svg viewBox="0 0 320 120" xmlns="http://www.w3.org/2000/svg">',
+      "  <title>A request flows from the client to the server</title>",
+      '  <rect x="10" y="30" width="110" height="60" rx="8" fill="currentColor" fill-opacity="0.08" stroke="currentColor" stroke-width="2"/>',
+      '  <text x="65" y="66" font-family="sans-serif" font-size="16" text-anchor="middle" fill="currentColor">Client</text>',
+      '  <path d="M124 60 H188" fill="none" stroke="currentColor" stroke-width="2"/>',
+      '  <path d="M188 52 L200 60 L188 68 Z" fill="currentColor"/>',
+      '  <rect x="200" y="30" width="110" height="60" rx="8" fill="none" stroke="currentColor" stroke-width="2"/>',
+      '  <text x="255" y="66" font-family="sans-serif" font-size="16" text-anchor="middle" fill="currentColor">Server</text>',
+      "</svg>",
+      "```"
+    ].join("\n");
+  }
+});
+
 // src/mcp/style-guidance.ts
 var STYLE_SELECTION_GUIDANCE, TRANSFORM_SELECTION_GUIDANCE, MOTION_SELECTION_GUIDANCE;
 var init_style_guidance = __esm({
@@ -4596,13 +4852,14 @@ function registerAuthoringGuideResource(server) {
       annotations: { audience: ["assistant"], priority: 1 }
     },
     async () => {
-      const [templates, schemaModule, transformModule] = await Promise.all([
+      const [templates, schemaModule, transformModule, pictures] = await Promise.all([
         authoringTemplateCatalog(),
         import("@bendyline/squisq/schemas"),
-        import("@bendyline/squisq/transform")
+        import("@bendyline/squisq/transform"),
+        authoringGuidePictures()
       ]);
       const guide = {
-        version: 10,
+        version: 11,
         workflow: [
           "plain text and ordinary Markdown can be passed directly to convert_document without a preflight or template annotations",
           "for deliberate PPTX slide boundaries, use one level-one Markdown heading per slide; headings alone create the boundaries, so do not add --- between them unless a visible horizontal rule is intended",
@@ -4610,6 +4867,7 @@ function registerAuthoringGuideResource(server) {
           STYLE_SELECTION_GUIDANCE,
           TRANSFORM_SELECTION_GUIDANCE,
           MOTION_SELECTION_GUIDANCE,
+          "for pictures, choose a format from pictures.choose, follow pictures.svgRules for ```svg fences, and check pictures.exports for the target; never write raw <svg> HTML, which is silently dropped",
           "use a bundle source when assets must travel with the document, or create_document_bundle when one draft will be reused by two or more inspect, preview, or convert calls",
           "use inspect_document or preview_document only when the user asks for document analysis or visual evidence",
           "convert_document creates immutable artifacts; save_artifact only when a durable file is required"
@@ -4617,6 +4875,7 @@ function registerAuthoringGuideResource(server) {
         markdownAnnotation: '# Heading {[templateId key="value"]}',
         standaloneAnnotation: '{[templateId key="value"]}',
         standaloneWarning: "A standalone annotation creates an additional heading-less block. Bind the annotation to a heading unless that extra block is deliberate.",
+        pictures,
         fidelity: {
           semantic: "Prioritize meaning and portability.",
           "editable-native": "Produce editable native structures with target-specific diagnostics.",
@@ -4682,6 +4941,7 @@ function registerTemplateTools(server, context) {
             import("@bendyline/squisq/transform")
           ]);
           const annotationHandling = normalizedTarget ? await targetTemplateAnnotationHandling(normalizedTarget) : null;
+          const pictureExport = pictureExportGuidance(normalizedTarget);
           const candidateTemplates = annotationHandling === "ignored" ? fullTemplates.filter((template) => template.safeForContentFirst) : fullTemplates;
           let recommendations = [];
           let totalBlocks = null;
@@ -4734,6 +4994,8 @@ function registerTemplateTools(server, context) {
               ...normalizedTarget === "pptx" || normalizedTarget === "html" || normalizedTarget === "htmlzip" || normalizedTarget === "mp4" || normalizedTarget === "gif" ? [MOTION_SELECTION_GUIDANCE] : [],
               "convert_document chooses compatible templates automatically. Annotations on headings are optional layout hints that take precedence; use the returned exact starter examples when useful.",
               annotationHandling === "ignored" ? "This target flattens template annotations to semantic content, so annotations are unnecessary for the exported file." : "Explicit valid annotations override automatic layout choices; invalid or unnecessary annotations should be omitted rather than repaired through a separate workflow.",
+              PICTURE_SELECTION_GUIDANCE,
+              ...pictureExport ? [pictureExport] : [],
               "Pass Markdown directly to convert_document. Use a bundle source for assets, or create_document_bundle only when one draft will be reused by two or more inspect, preview, or convert calls.",
               "Use inspect_document or preview_document only when the user asks for document analysis or visual evidence. Save only final durable artifacts with save_artifact."
             ],
@@ -5384,6 +5646,7 @@ var init_agentic_tools = __esm({
     init_progress();
     init_preview_content();
     init_output_bounds();
+    init_picture_guidance();
     init_style_guidance();
     READ_ONLY = {
       readOnlyHint: true,
@@ -5834,7 +6097,7 @@ function presentationPrompt(topic, style, theme, template) {
 
 1. For durable output, call list_roots before drafting. If no returned root is write-enabled, stop and explain that the MCP server must restart with --allow-write; do not use a shell or CLI converter.
 2. ${selectionHint} ${MOTION_SELECTION_GUIDANCE} Call get_authoring_context only when the linked theme and Summarize descriptions would materially improve the choice.
-3. Author plain Markdown. One level-one heading (\`#\`) creates each deliberate slide boundary; headings alone create the boundaries, so do not add \`---\` between them unless a visible horizontal rule is intended. Unstructured text is also accepted. Squisq annotations are optional layout hints.${templateHint}
+3. Author plain Markdown. One level-one heading (\`#\`) creates each deliberate slide boundary; headings alone create the boundaries, so do not add \`---\` between them unless a visible horizontal rule is intended. Unstructured text is also accepted. Squisq annotations are optional layout hints.${templateHint} ${PRESENTATION_PICTURE_HINT}
 4. Pass the Markdown directly to convert_document with a pptx target${themeHint}${styleHint}. Use a bundle source only when assets must travel with the document. No validation, inspection, or preview is required.
 5. Use inspect_document or preview_document only when the user explicitly asks for document analysis or visual evidence.
 6. Call save_artifact only when a durable file is required.`;
@@ -5870,7 +6133,7 @@ function documentPrompt(topic, format, theme, template) {
   return `Create a document about: ${topic}
 
 1. For durable output, call list_roots before drafting and stop if no root is write-enabled; do not use a shell or CLI converter.
-2. Author plain Markdown. Squisq annotations are optional layout hints.${templateHint} Call get_authoring_context only when exact annotation examples or theme details would help.
+2. Author plain Markdown. Squisq annotations are optional layout hints.${templateHint} ${documentPictureHint(target)} Call get_authoring_context only when exact annotation examples or theme details would help.
 3. Pass the Markdown directly to convert_document with a ${target} target${themeHint}. Use a bundle source only when assets must travel with the document. No validation, inspection, or preview is required.
 4. Use inspect_document or preview_document only when the user explicitly asks for document analysis or visual evidence.
 5. Call save_artifact only when a durable file is required.`;
@@ -5884,6 +6147,7 @@ var init_prompts = __esm({
   "src/mcp/prompts.ts"() {
     "use strict";
     init_conversion_service();
+    init_picture_guidance();
     init_style_guidance();
     MAX_ID_CHARACTERS = 256;
     MAX_TOPIC_CHARACTERS = 1e4;
@@ -5924,6 +6188,7 @@ function createMcpServer(options = {}) {
         STYLE_SELECTION_GUIDANCE,
         TRANSFORM_SELECTION_GUIDANCE,
         MOTION_SELECTION_GUIDANCE,
+        PICTURE_INSTRUCTION_GUIDANCE,
         "Use a bundle source when assets must travel with the document. Use create_document_bundle only when one complete draft will be reused by two or more inspect, preview, or convert calls.",
         "Use inspect_document or preview_document only when the user asks for document analysis or visual evidence.",
         "convert_document returns immutable artifacts and diagnostics. Save only final durable output with save_artifact; never invent root ids or switch conversion to a shell or CLI."
@@ -5994,6 +6259,7 @@ var init_server = __esm({
     init_artifact_store();
     init_authority();
     init_discovery_tools();
+    init_picture_guidance();
     init_prompts();
     init_style_guidance();
     DEFAULT_MAX_CONCURRENT_OPERATIONS = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/docblocks-cli",
-  "version": "2.7.2",
+  "version": "2.7.3",
   "description": "Build, preview, convert, render, inspect, and automate documents",
   "license": "MIT",
   "author": "Bendyline",
@@ -47,12 +47,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/docblocks": "2.7.2",
-    "@bendyline/squisq": "2.12.0",
-    "@bendyline/squisq-cli": "2.9.1",
-    "@bendyline/squisq-formats": "2.7.1",
-    "@bendyline/squisq-react": "2.12.1",
-    "@bendyline/squisq-video": "2.4.0",
+    "@bendyline/docblocks": "2.7.3",
+    "@bendyline/squisq": "2.12.3",
+    "@bendyline/squisq-cli": "2.9.5",
+    "@bendyline/squisq-formats": "2.7.3",
+    "@bendyline/squisq-react": "2.12.4",
+    "@bendyline/squisq-video": "2.4.3",
     "@modelcontextprotocol/sdk": "1.32.1",
     "commander": "13.1.0",
     "jszip": "3.10.1",