@readme/markdown 14.10.1 → 14.10.3

package/components/Embed/index.tsx

@@ -2,6 +2,8 @@
 /* eslint-disable react/jsx-props-no-spreading */
 import React from 'react';
 
+import { normalizeYouTubeUrlToEmbedUrl } from './normalizeYouTubeUrl';
+
 interface FaviconProps {
   alt?: string;
   src: string;
@@ -72,7 +74,8 @@ const Embed = ({
     !html && !explicitOptOut && url && typeOfEmbed && IFRAME_DERIVABLE_TYPES.has(typeOfEmbed);
 
   if (iframe || renderTypeAsIframe) {
-    return <iframe {...spreadAttrs} src={url} style={iframeStyle} title={title} />;
+    const src = normalizeYouTubeUrlToEmbedUrl(url);
+    return <iframe {...spreadAttrs} src={src} style={iframeStyle} title={title} />;
   }
 
   if (!providerUrl && url)

package/components/Embed/normalizeYouTubeUrl.ts

@@ -0,0 +1,41 @@
+// YouTube watch/share URLs (youtube.com/watch?v=ID, youtu.be/ID) set X-Frame-Options
+// and refuse to be framed. The player only allows embedding via youtube.com/embed/ID.
+const YOUTUBE_HOSTS = new Set(['youtube.com', 'www.youtube.com', 'm.youtube.com', 'youtu.be', 'www.youtu.be', 'm.youtu.be']);
+
+// /embed/ accepts `start` (integer seconds), not the watch-page `t` value which may carry units (e.g. 596s, 1h2m3s).
+const toStartSeconds = (timestamp: string): string | null => {
+  const [, hours, minutes, seconds] = timestamp.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s?)?$/) ?? [];
+  const total = (Number(hours) || 0) * 3600 + (Number(minutes) || 0) * 60 + (Number(seconds) || 0);
+  return total > 0 ? String(total) : null;
+};
+
+const extractVideoId = (parsed: URL): string | null => {
+  if (parsed.hostname.endsWith('youtu.be')) return parsed.pathname.slice(1).split('/')[0] || null;
+  if (parsed.pathname.startsWith('/watch')) return parsed.searchParams.get('v');
+  if (parsed.pathname.startsWith('/shorts/')) return parsed.pathname.slice('/shorts/'.length).split('/')[0] || null;
+  return null;
+};
+
+// Most youtube links we get from the browser are watch URLs, like https://www.youtube.com/watch?v=dQw4w9WgXcQ
+// These /watch URLs won't work in an iframe, so we need to convert them to the embed URL if iframe is used
+export const normalizeYouTubeUrlToEmbedUrl = (url: string): string => {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+
+  if (!YOUTUBE_HOSTS.has(parsed.hostname)) return url;
+  if (parsed.pathname.startsWith('/embed/')) return url;
+
+  const videoId = extractVideoId(parsed);
+  if (!videoId) return url;
+
+  const embed = new URL(`https://www.youtube.com/embed/${videoId}`);
+  const timestamp = parsed.searchParams.get('start') || parsed.searchParams.get('t');
+  const start = timestamp ? toStartSeconds(timestamp) : null;
+  if (start) embed.searchParams.set('start', start);
+
+  return embed.toString();
+};

package/dist/components/Embed/normalizeYouTubeUrl.d.ts

@@ -0,0 +1 @@
+export declare const normalizeYouTubeUrlToEmbedUrl: (url: string) => string;

package/dist/lib/micromark/mdx-component/syntax.d.ts

@@ -13,12 +13,13 @@ declare module 'micromark-util-types' {
  * self-closing `<Component />`). Prevents CommonMark from fragmenting them
  * across multiple HTML / paragraph nodes.
  *
- * **Text (inline)** — registers only for lowercase tags with brace attrs
- * (e.g. `Start <a href={url}>here</a> end`). Picks them up during inline
- * parsing so they render inline inside their paragraph, then are rewritten
- * to `mdxJsxTextElement` by the `components/inline-html` transformer.
- * PascalCase is intentionally flow-only; ReadMe's custom components are
- * authored as block-level elements.
+ * **Text (inline)** — registers for lowercase tags and inline PascalCase
+ * components (Anchor, Glossary) that carry brace attrs (e.g.
+ * `Start <a href={url}>here</a> end`, `<Anchor href={url}>x</Anchor>`). Picks
+ * them up during inline parsing so they render inline inside their paragraph,
+ * then are rewritten to `mdxJsxTextElement` by the `components/inline-html`
+ * transformer. All other PascalCase is flow-only; ReadMe's custom components
+ * are authored as block-level elements.
  *
  * Excludes tags handled by dedicated tokenizers: Table, HTMLBlock, Glossary,
  * Anchor.

package/dist/lib/render-diff/differ.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structural HTML diff for MDX-vs-MDXish render comparison.
+ *
+ * Algorithm overview:
+ *   parseDocument(html, { xmlMode: true }) → walk → canonical {tag, attrs, children} tree
+ *   apply canonicalization pipeline (sort/normalize/collapse)
+ *   compute bottom-up content hash
+ *   fast-path match if hashes equal
+ *   otherwise, recursive walk emitting Change records
+ *
+ * Tree-walk targets the htmlparser2 / domhandler node shape. The canonicalization
+ * rules and severity model are transplanted verbatim from the reference differ.ts
+ * (PR #18479 in the readme repo). The tree-walk is re-targeted to htmlparser2/domhandler.
+ *
+ * The lint disables below are intentional and scoped to this file:
+ * - `no-restricted-syntax` + `no-continue`: this is a tree-walker with greedy
+ *   alignment and lookahead; for-of with continue is the natural shape and
+ *   array iteration helpers would obscure the control flow.
+ * - `@typescript-eslint/no-use-before-define`: helpers are ordered bottom-up
+ *   (primitives first, public `diff()` last) so the public API anchors the
+ *   end of the file.
+ */
+import type { DiffOptions, DiffResult } from './types';
+/**
+ * Diff two rendered HTML strings.
+ *
+ * The diff tool is engine-agnostic — `leftHtml` and `rightHtml` are simply
+ * the two HTML strings to compare in that order. Common use cases:
+ * - MDX vs MDXish (Suite B in this repo)
+ * - Before vs after a `@readme/markdown` version bump on the same source
+ * - Any two HTML strings a consumer wants to compare
+ *
+ * Both strings are canonicalized (whitespace collapse, class sort, attribute
+ * normalization, noise-attr drop, heading-counter strip, void-tag handling,
+ * text-equivalent merging) before comparison.
+ *
+ * A bottom-up content hash provides a fast-path: if both trees hash identically,
+ * `{ status: 'match' }` is returned without a full walk.
+ *
+ * The returned `changes[]` is ordered by document position and is identical
+ * across repeated calls on the same input. Each change carries `left` and
+ * `right` fields corresponding to the two inputs.
+ *
+ * @param leftHtml  - First HTML string to compare.
+ * @param rightHtml - Second HTML string to compare.
+ * @param opts      - Optional canonicalization / diff configuration.
+ * @returns `{ status: 'match' }` or `{ status: 'differ', severity, changes }`.
+ */
+export declare function diff(leftHtml: string, rightHtml: string, opts?: DiffOptions): DiffResult;

package/dist/lib/render-diff/index.d.ts

@@ -0,0 +1,2 @@
+export { diff } from './differ';
+export type { Change, DiffOptions, DiffResult, Preset, Severity } from './types';

package/dist/lib/render-diff/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * TypeScript types for the render-diff HTML diffing tool.
+ *
+ * These types form the public contract for `lib/render-diff/differ.ts`.
+ */
+/**
+ * Severity level of a single diff change or aggregate page diff result.
+ *
+ * - `cosmetic` — minor presentation differences (e.g. `data-*` / `aria-*` attrs)
+ * - `structural` — tag, element, or layout differences
+ * - `content` — visible text or meaningful attribute value differences
+ */
+export type Severity = 'content' | 'cosmetic' | 'structural';
+/**
+ * A single diffed change between two rendered HTML inputs.
+ *
+ * The diff tool is engine-agnostic — `left` and `right` are simply the two
+ * HTML strings passed to `diff()` in that order. Suite B uses them as
+ * MDX vs MDXish; other consumers (e.g. before/after a markdown version bump)
+ * use them however they like.
+ *
+ * Each change is emitted at a specific document-position path.
+ */
+export interface Change {
+    /**
+     * Attribute name — populated only when `kind` is `'attr'`.
+     */
+    attrName?: string;
+    /**
+     * The type of difference detected.
+     *
+     * - `tag`     — element tag mismatch between `left` and `right`
+     * - `attr`    — attribute present, missing, or different value
+     * - `text`    — text node content differs
+     * - `missing` — node present in `left` but absent in `right`
+     * - `extra`   — node present in `right` but absent in `left`
+     */
+    kind: 'attr' | 'extra' | 'missing' | 'tag' | 'text';
+    /**
+     * String representation from the `left` input, or `null` when the node is absent.
+     */
+    left: string | null;
+    /**
+     * Document-position path of the diffed node (top-to-bottom tree-walk order).
+     */
+    path: string;
+    /**
+     * String representation from the `right` input, or `null` when the node is absent.
+     */
+    right: string | null;
+    /**
+     * Severity of this individual change.
+     */
+    severity: Severity;
+}
+/**
+ * Result returned by `diff(leftHtml, rightHtml)`.
+ *
+ * Discriminated union on `status`:
+ * - `'match'` arm collapses to `{ status: 'match' }` — no `severity` or `changes` keys.
+ * - `'differ'` arm carries the full `{ status, severity, changes }` shape.
+ *
+ * TypeScript narrowing on `result.status === 'differ'` exposes `severity` and `changes`.
+ */
+export type DiffResult = {
+    changes: Change[];
+    severity: Severity;
+    status: 'differ';
+} | {
+    status: 'match';
+};
+/**
+ * Canonicalization preset for `diff()`.
+ *
+ * - `'cross-engine'` — full normalization including span-flatten and adjacent-text
+ *   merge. Designed for MDX↔MDXish comparison (Suite B).
+ * - `'minimal'` — lighter normalization; span-flatten and adjacent-text merge are
+ *   skipped. Suitable for same-engine before/after comparison where those transforms
+ *   would mask real structural changes.
+ */
+export type Preset = 'cross-engine' | 'minimal';
+/**
+ * Options accepted by `diff()`.
+ *
+ * All fields are optional. Default behaviour: hash fast-path enabled, all
+ * heading counter suffixes stripped, no additional attributes ignored.
+ */
+export interface DiffOptions {
+    /**
+     * Additional attribute names to drop during canonicalization (lowercased).
+     * Added to the built-in noise-attr set (`data-reactroot`, `data-testid`,
+     * `suppresshydrationwarning`).
+     */
+    attrIgnore?: Set<string>;
+    /**
+     * When `true`, bypass the content-hash fast-path and always perform the full
+     * tree walk. Intended for testing only.
+     */
+    noHashFastPath?: boolean;
+    /**
+     * When `true`, skip stripping `-N` counter suffixes from heading `id` attrs.
+     * Default: `false` (suffixes are stripped so repeated headings compare equal).
+     */
+    preserveHeadingCounters?: boolean;
+    /**
+     * Canonicalization preset. Controls which structural-normalization transforms
+     * are applied before comparison.
+     *
+     * - `'cross-engine'` (default) — full normalization including span-flatten
+     *   and adjacent-text merge. Designed for MDX↔MDXish comparison (Suite B).
+     * - `'minimal'` — lighter normalization; span-flatten and adjacent-text merge
+     *   are skipped. Suitable for same-engine before/after comparison where those
+     *   transforms would mask real structural changes.
+     *
+     * Every normalization `'minimal'` performs is also performed by `'cross-engine'`.
+     * Default: omitting `preset` is equivalent to `'cross-engine'` (backward compatible).
+     */
+    preset?: Preset;
+}

package/dist/lib/render-fixture/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public barrel for `@readme/markdown/render-fixture`.
+ *
+ * Pairs with the engine-free `@readme/markdown/render-diff` subpath: this
+ * bundle DOES include the engine (it has to — its job is to render). A
+ * typical consumer that wants regression coverage across @readme/markdown
+ * version bumps pairs the two:
+ *
+ *   import { renderFixture } from '@readme/markdown/render-fixture';
+ *   import { diff } from '@readme/markdown/render-diff';
+ *
+ *   const oldHtml = readFileSync('snapshot.html', 'utf8');
+ *   const { html: newHtml } = renderFixture(body, ctx, 'mdxish');
+ *   const result = diff(oldHtml, newHtml, { preset: 'minimal' });
+ */
+export { loadFixture } from './loadFixture';
+export type { RenderContext } from './loadFixture';
+export { renderFixture } from './renderFixture';
+export type { Engine, FixtureRenderResult } from './renderFixture';

package/dist/lib/render-fixture/loadFixture.d.ts

@@ -0,0 +1,21 @@
+export interface RenderContext {
+    components: {
+        source: string;
+        tag: string;
+    }[];
+    glossary: {
+        definition: string;
+        term: string;
+    }[];
+    variables: {
+        defaults: {
+            default: string;
+            name: string;
+        }[];
+        user: Record<string, string>;
+    };
+}
+export declare function loadFixture(dir: string): {
+    body: string;
+    ctx: RenderContext;
+};

package/dist/lib/render-fixture/renderFixture.d.ts

@@ -0,0 +1,17 @@
+import type { RenderContext } from './loadFixture';
+export type Engine = 'mdx' | 'mdxish';
+export interface FixtureRenderResult {
+    error: string | null;
+    html: string;
+}
+/**
+ * Renders a fixture body string through the specified engine and returns the
+ * serialized HTML. Renders are deterministic — Date.now and Math.random are
+ * frozen for the duration of each render call.
+ *
+ * For MDXish, the components map is passed to BOTH mdxish() and renderMdxish()
+ * — both call sites need it for custom-block resolution.
+ *
+ * The loader's `ctx.glossary` is mapped onto the engine's `terms` parameter.
+ */
+export declare function renderFixture(body: string, ctx: RenderContext, engine: Engine): FixtureRenderResult;