specra 0.2.58 → 0.2.60

package/dist/components/docs/CodeBlock.svelte

@@ -5,9 +5,19 @@
     code: string;
     language: string;
     filename?: string;
+    showLineNumbers?: boolean;
   }
 
-  let { code, language, filename }: Props = $props();
+  let { code, language, filename, showLineNumbers = false }: Props = $props();
+
+  // Languages whose syntax the JS/TS-oriented tokenizer below does NOT model.
+  // Highlighting these would mis-colour prose markup (e.g. a markdown list `-`
+  // becomes a red "operator", `# heading` becomes a grey "comment"), so they are
+  // rendered as plain, uncoloured text instead.
+  const PLAIN_LANGUAGES = new Set([
+    'markdown', 'md', 'mdx', 'text', 'txt', 'plaintext', 'plain', '',
+  ]);
+  let isPlain = $derived(PLAIN_LANGUAGES.has((language || '').toLowerCase()));
 
   let copied = $state(false);
   let copyTimeout: ReturnType<typeof setTimeout> | undefined;
@@ -115,7 +125,7 @@
 
   <!-- Code content -->
   <div class="bg-muted/30 dark:bg-muted/20 rounded-b-xl overflow-x-auto border border-border/50">
-    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = language === 'diff' && line.startsWith('-') && !line.startsWith('--')}{@const isAddition = language === 'diff' && line.startsWith('+') && !line.startsWith('++')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = tokenizeLine(line)}<div class="table-row {diffBgClass}"><span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span><span class="table-cell align-top">{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}</span></div>{/each}</code></pre>
+    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = language === 'diff' && line.startsWith('-') && !line.startsWith('--')}{@const isAddition = language === 'diff' && line.startsWith('+') && !line.startsWith('++')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = isPlain ? [] : tokenizeLine(line)}<div class="table-row {diffBgClass}">{#if showLineNumbers}<span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span>{/if}<span class="table-cell align-top">{#if isPlain}{#if line}{line}{:else}&nbsp;{/if}{:else}{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}{/if}</span></div>{/each}</code></pre>
   </div>
 </div>
 

package/dist/components/docs/CodeBlock.svelte.d.ts

@@ -2,6 +2,7 @@ interface Props {
     code: string;
     language: string;
     filename?: string;
+    showLineNumbers?: boolean;
 }
 declare const CodeBlock: import("svelte").Component<Props, {}, "">;
 type CodeBlock = ReturnType<typeof CodeBlock>;

package/dist/mdx-security.d.ts

@@ -23,8 +23,19 @@ export declare function validatePathWithinDirectory(filePath: string, allowedDir
  */
 export declare function scanMDXForDangerousPatterns(content: string): string[];
 /**
- * Sanitize MDX content by removing/escaping dangerous patterns
- * This is a defensive measure - ideally content should be rejected if dangerous
+ * Sanitize MDX content by neutralizing dangerous patterns in executable prose,
+ * while leaving fenced code blocks and inline code completely untouched.
+ *
+ * Code spans are not executable — the code renderer displays their contents as
+ * escaped text — so dangerous-looking examples inside them (e.g. a documented
+ * `<script>` tag) must be preserved verbatim, never stripped. We mask code spans
+ * with placeholder tokens, sanitize only the surrounding prose, then restore
+ * them unchanged.
+ *
+ * In prose, script tags are *escaped* (turned into inert, visible literal text)
+ * rather than deleted, so content never silently vanishes. Event-handler
+ * attributes and `javascript:` URLs are invisible attack vectors on otherwise
+ * valid HTML, so those are removed (neutralizing them deletes no visible text).
  */
 export declare function sanitizeMDXContent(content: string, strict?: boolean): string;
 /**

package/dist/mdx.js

@@ -3,6 +3,7 @@ import path from "path";
 import matter from "gray-matter";
 import yaml from "js-yaml";
 import { rehypeBasePath } from "./rehype-base-path.js";
+import { remarkCodeMeta } from "./remark-code-meta.js";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
@@ -518,6 +519,7 @@ async function processMarkdownToHtml(markdown) {
         .use(remarkParse)
         .use(remarkGfm)
         .use(remarkMath)
+        .use(remarkCodeMeta)
         .use(remarkRehype, { allowDangerousHtml: true })
         .use(rehypeRaw)
         .use(rehypeSlug)
@@ -575,9 +577,20 @@ function extractCodeBlockProps(node) {
     const language = langClass ? langClass.replace('language-', '') : 'txt';
     // Extract text content from the code element
     const code = extractTextContent(codeChild).replace(/\n$/, '');
-    // Check for filename in data attributes (e.g. from remark-code-meta)
-    const filename = node.properties?.['data-filename'] || codeChild.properties?.['data-filename'];
-    return { code, language, ...(filename ? { filename } : {}) };
+    // Read attributes set by remark-code-meta from the fence meta. rehypeRaw
+    // normalises `data-foo` to the camel-cased `dataFoo` hast property, so accept
+    // both spellings, on either the <pre> or the <code>.
+    const readDataAttr = (camel, kebab) => node.properties?.[camel] ?? node.properties?.[kebab] ??
+        codeChild.properties?.[camel] ?? codeChild.properties?.[kebab];
+    const filename = readDataAttr('dataFilename', 'data-filename');
+    const lineNumbers = readDataAttr('dataLineNumbers', 'data-line-numbers');
+    const showLineNumbers = lineNumbers === 'true' || lineNumbers === true || lineNumbers === '';
+    return {
+        code,
+        language,
+        ...(filename ? { filename } : {}),
+        ...(showLineNumbers ? { showLineNumbers: true } : {}),
+    };
 }
 /**
  * Detect GitHub-style alert blockquotes: > [!WARNING] content
@@ -1176,6 +1189,7 @@ async function processMarkdownToMdxNodes(markdown) {
         .use(remarkParse)
         .use(remarkGfm)
         .use(remarkMath)
+        .use(remarkCodeMeta)
         .use(remarkRehype, { allowDangerousHtml: true })
         .use(rehypeRaw)
         .use(rehypeSlug)

package/dist/remark-code-meta.d.ts

@@ -1,6 +1,14 @@
 /**
- * Remark plugin to extract code block meta strings and pass them as props
- * Converts: ```js filename.js
- * Into props: { language: 'js', meta: 'filename.js' }
+ * Remark plugin to read a code block's fence meta string and expose the
+ * recognised options as `data-*` attributes on the rendered <code>.
+ *
+ * Supported syntax:
+ *   ```js title="app.js"          -> data-filename="app.js"
+ *   ```ts title='src/index.ts'    -> data-filename="src/index.ts"
+ *   ```js showLineNumbers         -> data-line-numbers="true"
+ *   ```js showLineNumbers=true    -> data-line-numbers="true"
+ *
+ * Line numbers are opt-in: only an explicit `showLineNumbers` (or
+ * `showLineNumbers=true`) turns them on; absence (or `=false`) leaves them off.
  */
 export declare function remarkCodeMeta(): (tree: any) => void;

package/dist/remark-code-meta.js

@@ -1,16 +1,38 @@
 /**
- * Remark plugin to extract code block meta strings and pass them as props
- * Converts: ```js filename.js
- * Into props: { language: 'js', meta: 'filename.js' }
+ * Remark plugin to read a code block's fence meta string and expose the
+ * recognised options as `data-*` attributes on the rendered <code>.
+ *
+ * Supported syntax:
+ *   ```js title="app.js"          -> data-filename="app.js"
+ *   ```ts title='src/index.ts'    -> data-filename="src/index.ts"
+ *   ```js showLineNumbers         -> data-line-numbers="true"
+ *   ```js showLineNumbers=true    -> data-line-numbers="true"
+ *
+ * Line numbers are opt-in: only an explicit `showLineNumbers` (or
+ * `showLineNumbers=true`) turns them on; absence (or `=false`) leaves them off.
  */
 export function remarkCodeMeta() {
     return (tree) => {
         const visit = (node) => {
             if (node.type === 'code' && node.meta) {
-                // Store the meta string in the node's data
-                node.data = node.data || {};
-                node.data.hProperties = node.data.hProperties || {};
-                node.data.hProperties.meta = node.meta;
+                const hProperties = {};
+                // title="..." / title='...' -> filename shown in the code block header.
+                const titleMatch = node.meta.match(/\btitle\s*=\s*"([^"]*)"/i) ||
+                    node.meta.match(/\btitle\s*=\s*'([^']*)'/i);
+                if (titleMatch) {
+                    hProperties['data-filename'] = titleMatch[1];
+                }
+                // showLineNumbers (opt-in). Bare flag or `=true` enables; `=false` keeps off.
+                const lineNumbersMatch = node.meta.match(/\bshowLineNumbers(?:\s*=\s*(true|false))?\b/i);
+                if (lineNumbersMatch &&
+                    (lineNumbersMatch[1] === undefined ||
+                        lineNumbersMatch[1].toLowerCase() === 'true')) {
+                    hProperties['data-line-numbers'] = 'true';
+                }
+                if (Object.keys(hProperties).length > 0) {
+                    node.data = node.data || {};
+                    node.data.hProperties = { ...(node.data.hProperties || {}), ...hProperties };
+                }
             }
             if (node.children) {
                 node.children.forEach(visit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.58",
+  "version": "0.2.60",
   "description": "A modern documentation library for SvelteKit with built-in versioning, API reference generation, full-text search, and MDX support",
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",