@particle-academy/fancy-code 0.11.0 → 0.12.1

package/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to `@particle-academy/fancy-code` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+> **Pre-1.0:** breaking changes land in MINOR releases. Until 1.0 the minor
+> number is not a compatibility promise — read the entry, not the version.
+
+> This file starts here. Earlier releases predate it and were never written up;
+> `git log` is the record for those. It is not backfilled rather than
+> guessed-at, because a changelog that invents its own history is worse than one
+> that admits where it begins.
+
+## [Unreleased]
+
+## [0.12.1] - 2026-10-18
+
+### Security
+
+- **`<MarkdownEditor>`'s preview no longer renders a link or image whose URL
+  can run script.** The preview is built as an HTML string and inserted with
+  `innerHTML`, where React's `javascript:` guard does not apply. URLs were kept
+  inside their attribute but their scheme was never checked, so
+  `[x](javascript:...)` became a live script link in the preview, in the page's
+  own origin. A link now needs a relative URL or `http`, `https`, `mailto` or
+  `tel`; an image needs a relative URL, `http(s)`, or a raster
+  `data:image/...`. Anything else renders as its text (a link) or its alt text
+  (an image). The scheme is read the way a browser reads it: case-insensitive,
+  with leading control characters and embedded tabs and newlines ignored.
+  **Upgrade if any markdown you preview was written by someone else**, an agent
+  included. Nothing else changes. Found while auditing the viewers fancy-labs
+  uses to show agent-written documents.
+
+## [0.12.0] - 2026-10-17
+
+### Added
+
+- **`<FileViewer line={42}>` lands on a line**: scrolled to the middle of the
+  view, caret placed, and highlighted — on mount and again whenever `line`
+  changes, so re-targeting an open file scrolls again. `column` places the caret
+  within it. Text files only; it does not steal focus.
+
+  Asked for by Genie 2, whose `openFileForUser(path, line)` now opens files in its
+  own FileViewer panel. `CodeEditor` could already reveal a line (`cursorLine`);
+  `FileViewer` never passed one through, and nothing marked the line on arrival.
+
+- **`highlightLines` on `FileViewer` and `CodeEditor`** draws a full-width band
+  behind each listed line and bolds its gutter number. `FileViewer` highlights
+  `[line]` by default; pass a range or several hits to override, or `[]` to land
+  without a highlight. Lines outside the document are ignored. Measured in a real
+  browser: the band lines up with the gutter row to the pixel. Sized for
+  unwrapped lines, as the gutter is.
+
+  Handle: `data-fancy-code-highlight-line={n}`.
+
+**What you must DO: nothing.** Both props are optional; without them the viewer
+renders exactly as before.
+
+### Fixed
+
+- **`CHANGELOG.md` is now in the published tarball.** `files` did not whitelist it, so npm never shipped it — and this package puts breaking changes in MINOR releases and tells you in the README to read the entry before taking one. The instruction existed for the author, who has the file, and not for the consumer, who is the only one being instructed. Nothing for you to do; the file simply arrives from this release on.
+
+### Security
+
+- `source-map-js` is pinned forward to `^1.2.2` via `overrides`. Versions up to
+  1.2.1 allow an event-loop denial of service through indexed source-map section
+  offsets, and it arrives here transitively through the build toolchain.
+  **Nothing for a consumer to do, and no runtime change**: an npm package does
+  not ship a lockfile, so this governs builds OF this repo, not anything
+  installed FROM it. Recorded rather than left silent because the override it
+  sits beside — `shell-quote` `^1.9.0`, added for an earlier advisory — was
+  carried with no note of why, and had drifted back inside the vulnerable range
+  before anyone looked.
+
+## [0.11.0] — 2026-08-14
+
+### Changed
+
+- **The `MarkdownEditor` preview now renders through react-fancy's `<ContentRenderer format="markdown">`** — a full CommonMark + GFM parse — instead of the small built-in renderer.
+
+  Reported by a consumer reviewing documents through this surface, and measured before changing anything: a GFM table collapsed into a single run-on `<p>` (no table support at all), a hard-wrapped blockquote became one `<blockquote>` per source line, and a wrapped list item's continuation escaped the `<ul>` to become a `<p>`. On a document hard-wrapped at ~95 characters that degrades *everything*, and reads as though the author wrote it badly. Their most important block — a claim/evidence/status table — was the worst rendered.
+
+  The fix adds **no dependency**. `marked` was already in this tree as a runtime dependency of react-fancy, which fancy-code already requires, so the built-in renderer was a second, weaker markdown implementation sitting next to a complete one. Output is sanitised by default, as before.
+
+  **What you must do:** nothing to install, and nothing if you already pass `renderPreview` — that still wins and is still injected as-is. If you style the preview, note the rendered HTML is now marked's output: real `<table>`/`<thead>`/`<td>`, one `<blockquote>` per quote, and `<p>` inside `<blockquote>`. Selectors written against the old flattened markup may need updating.
+
+  `renderMarkdown` is unchanged and still exported for direct use; it is simply no longer the preview default.
+
+### Fixed
+
+- **`maxHeight` now constrains the preview pane.** It was passed only to the editor, so a long document rendered at full height instead of scrolling. The preview gets `maxHeight` + `overflow-y: auto` when the prop is set.
+
+## [0.10.0] — 2026-08-07
+
+### Changed
+
+- **BREAKING — Node 22 is now declared as the floor.** `engines.node` is `>=22`, where this package previously declared **nothing at all**.
+
+  Declaring nothing was not the same as supporting old Node: a consumer on 18 installed cleanly and found out at runtime.
+
+  **What you must do:** on Node 22 or newer, nothing. Note npm only *warns* on an `engines` mismatch while **pnpm fails the install**, so this surfaces differently depending on your package manager. Node 18 is end-of-life and 20 is maintenance-only.
+
+- **BREAKING — React 18 is no longer supported.** `peerDependencies.react` / `react-dom` are now `^19.0.0`.
+
+  **What you must do:** on React 19, nothing. On React 18, stay on the previous release, or upgrade your app to 19 first.
+
+  React 18 support was a claim nothing tested — every build and test in this package ran against 19, so the 18 half of the old range was never executed. An untested compatibility claim is worse than an absent one, because it reads as support.
+
+### Why
+
+These are the kit 0.5 platform floors, applied across every package at once so a consumer never has to resolve a mix. **No API changed, nothing was removed, nothing was renamed** — only what the package requires.
+
+
+## [0.9.1] — 2026-07-28
+
+### Fixed
+
+- **`CodeEditorPanel` crashed when the editor engine arrived after first
+  render.** `if (!engine) return null` sat above the `useMemo` that builds the
+  gutter, so a render without an engine ran zero hooks and the next ran one —
+  React desyncs on the changed count and throws from inside itself.
+  `_engineReturn` is typed `| null` and starts null, so any host rendering the
+  panel before the engine settles hit this.
+
+  **No action needed** — the fix is internal and the API is unchanged.
+
+### Added
+
+- `jsdom` as a devDependency, and the first component test in this package.
+  There was previously no way to render a component in a test here at all, which
+  is precisely how the bug above shipped.
+
+### Changed
+
+- Widened the `@particle-academy/fancy-file-commons` requirement from `^0.2.0` to
+  `>=0.2 <2.0`, so a sibling minor release is an upgrade and not a resolver
+  conflict. **No action needed** — widening a range only adds candidates; the
+  version you have today still resolves.
+
+  A caret on a `0.x` range locks the MINOR, so this pinned a sibling at
+  whatever it happened to be on the day it was written, and each sibling
+  release then read as a conflict to the resolver rather than an upgrade.
+  Nothing here was using an API the newer minors removed — the range was the
+  whole problem.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -12,7 +12,36 @@ npm install @particle-academy/fancy-code
 # or: yarn add @particle-academy/fancy-code
 ```
 
-**Peer dependencies:** `react >= 18`, `react-dom >= 18`, `@particle-academy/react-fancy >= 4.9` (the `FileViewer` delegates media to react-fancy's `<MediaViewer>`, added in 4.9)
+**Peer dependencies:** `react ^19.0.0`, `react-dom ^19.0.0`, `@particle-academy/react-fancy >= 4.9` (the `FileViewer` delegates media to react-fancy's `<MediaViewer>`, added in 4.9)
+
+## Which version range to depend on
+
+**Use a caret. `^0.11.0` is correct here, and it is deliberate.**
+
+```jsonc
+"@particle-academy/fancy-code": "^0.11.0"
+```
+
+This package is **pre-1.0, and breaking changes land in MINOR releases** — see
+the note at the top of [`CHANGELOG.md`](./CHANGELOG.md). A caret on a `0.x` locks
+the minor (npm reads `^0.11.0` as `>=0.11.0 <0.12.0`), so it gives you patches and
+holds you at a surface you have already integrated against. That is the right
+default when the next minor may change something under you.
+
+**Moving up a minor is a deliberate act.** Read that version's `CHANGELOG.md`
+entry before you do — breaking entries say what a consumer must actually DO, and
+about half of what reads as breaking needs no action at all.
+
+> **A note on the rest of the suite.** Some Fancy packages recommend an open
+> `>=X <2.0` range instead. That is not an inconsistency: those packages carry a
+> **runtime compatibility check** that fails loudly when a consumer is out of
+> step — `fancy-connector-core`'s `CONNECTOR_API_VERSION` is the example — which
+> is a stronger guarantee than a caret and makes the caret unnecessary. This
+> package has no such check, so the caret is doing real work.
+>
+> The rule inside the suite differs again: first-party packages depend on each
+> other with an open range because they are **released and tested together** at a
+> kit version. A consumer is not, which is why the advice here is not the same.
 
 ## Setup
 

package/dist/index.cjs

@@ -41,12 +41,14 @@ function CodeEditorPanel({ className }) {
     placeholder,
     _diffAnnotations: diffAnnotations,
     _maxHeight,
-    _minHeight
+    _minHeight,
+    _highlightLines: highlightLines
   } = useCodeEditor();
   const lineNumberElements = react.useMemo(() => {
     if (!engine || !lineNumbers) return null;
     const { themeColors: themeColors2, lineCount: lineCount2, activeLine: activeLine2 } = engine;
     const removed = diffRemovedColor(themeColors2);
+    const highlighted = new Set(highlightLines ?? []);
     const lines = [];
     for (let i = 1; i <= lineCount2; i++) {
       const mark = gutterDiffMark(diffAnnotations, i);
@@ -58,8 +60,9 @@ function CodeEditorPanel({ className }) {
             "data-diff-deleted-above": mark?.deletedAbove ? "" : void 0,
             style: {
               position: "relative",
-              color: i === activeLine2 ? themeColors2.foreground : themeColors2.gutterForeground,
-              backgroundColor: i === activeLine2 ? themeColors2.activeLineBackground : void 0
+              color: i === activeLine2 || highlighted.has(i) ? themeColors2.foreground : themeColors2.gutterForeground,
+              backgroundColor: i === activeLine2 ? themeColors2.activeLineBackground : void 0,
+              fontWeight: highlighted.has(i) ? 600 : void 0
             },
             className: "pr-3 text-right text-[13px] leading-[1.5] select-none",
             children: [
@@ -119,7 +122,7 @@ function CodeEditorPanel({ className }) {
       );
     }
     return lines;
-  }, [engine, lineNumbers, diffAnnotations]);
+  }, [engine, lineNumbers, diffAnnotations, highlightLines]);
   if (!engine) return null;
   const {
     textareaRef,
@@ -162,6 +165,21 @@ function CodeEditorPanel({ className }) {
           }
         ),
         /* @__PURE__ */ jsxRuntime.jsxs("div", { className: reactFancy.cn("relative flex-1", wordWrap && "min-w-0"), children: [
+          (highlightLines ?? []).filter((n) => Number.isInteger(n) && n >= 1 && n <= lineCount).map((n) => /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              "data-fancy-code-highlight-line": n,
+              "aria-hidden": "true",
+              className: "pointer-events-none absolute inset-x-0 text-[13px] leading-[1.5]",
+              style: {
+                top: `calc(0.625rem + ${(n - 1) * 1.5}em)`,
+                height: "1.5em",
+                backgroundColor: themeColors.selectionBackground,
+                opacity: 0.55
+              }
+            },
+            `highlight-${n}`
+          )),
           /* @__PURE__ */ jsxRuntime.jsx(
             "pre",
             {
@@ -1517,7 +1535,8 @@ function CodeEditorRoot({
   maxHeight,
   cursorLine,
   cursorColumn,
-  diffBase
+  diffBase,
+  highlightLines
 }) {
   const [currentValue, setCurrentValue] = reactFancy.useControllableState(valueProp, defaultValue, onChange);
   const diffAnnotations = react.useMemo(
@@ -1610,9 +1629,10 @@ function CodeEditorRoot({
       _diffAnnotations: diffAnnotations,
       _engineReturn: engineReturn,
       _minHeight: minHeight,
-      _maxHeight: maxHeight
+      _maxHeight: maxHeight,
+      _highlightLines: highlightLines
     }),
-    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, diffAnnotations, minHeight, maxHeight]
+    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, diffAnnotations, minHeight, maxHeight, highlightLines]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(CodeEditorContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsxRuntime.jsx(
     "div",
@@ -1717,6 +1737,9 @@ function FileViewer({
   fileKind,
   lineNumbers = true,
   wordWrap = false,
+  line,
+  column,
+  highlightLines,
   minHeight,
   maxHeight,
   mediaProps,
@@ -1768,6 +1791,9 @@ function FileViewer({
           wordWrap,
           minHeight,
           maxHeight,
+          cursorLine: line,
+          cursorColumn: column,
+          highlightLines: highlightLines ?? (line != null ? [line] : void 0),
           children: /* @__PURE__ */ jsxRuntime.jsx(CodeEditor.Panel, {})
         }
       )
@@ -1783,8 +1809,27 @@ function escapeHtml(s) {
 function escapeAttr(s) {
   return s.replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+var LINK_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto", "tel"]);
+function schemeOf(url) {
+  let s = "";
+  for (const ch of url) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code === 9 || code === 10 || code === 13) continue;
+    if (s === "" && code <= 32) continue;
+    s += ch;
+  }
+  const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(s);
+  return m ? m[1].toLowerCase() : null;
+}
+function safeUrl(url, kind) {
+  const scheme = schemeOf(url);
+  if (scheme === null) return true;
+  if (scheme === "http" || scheme === "https") return true;
+  if (kind === "link") return LINK_SCHEMES.has(scheme);
+  return scheme === "data" && /^data:image\/(png|jpe?g|gif|webp|avif|bmp);/i.test(url.trim());
+}
 function inline(text) {
-  return text.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, alt, src, title) => `<img src="${escapeAttr(src)}" alt="${escapeAttr(alt)}"${title ? ` title="${escapeAttr(title)}"` : ""}>`).replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, t, href, title) => `<a href="${escapeAttr(href)}"${title ? ` title="${escapeAttr(title)}"` : ""} rel="noopener">${t}</a>`).replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`).replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, "<strong>$2</strong>").replace(/(\*|_)(?=\S)([\s\S]*?\S)\1/g, "<em>$2</em>");
+  return text.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, alt, src, title) => safeUrl(src, "image") ? `<img src="${escapeAttr(src)}" alt="${escapeAttr(alt)}"${title ? ` title="${escapeAttr(title)}"` : ""}>` : alt).replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, t, href, title) => safeUrl(href, "link") ? `<a href="${escapeAttr(href)}"${title ? ` title="${escapeAttr(title)}"` : ""} rel="noopener">${t}</a>` : t).replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`).replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, "<strong>$2</strong>").replace(/(\*|_)(?=\S)([\s\S]*?\S)\1/g, "<em>$2</em>");
 }
 function renderMarkdown(markdown) {
   const lines = markdown.replace(/\r\n?/g, "\n").split("\n");