@tomehq/theme 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @tomehq/theme
 
+## 0.2.0
+
+### Minor Changes
+
+- Shell: logo links back to landing page, dynamic version in sidebar footer
+- Shell: edit link support, table of contents depth config, changelog page layout
+- Entry: pass new config fields (editLink, tableOfContents, plugins) to Shell
+- Updated dependencies
+  - @tomehq/core@0.2.0
+  - @tomehq/components@0.2.0
+
 ## 0.1.2
 
 ### Patch Changes

package/dist/{chunk-JA4PMX6M.js → chunk-CTPOZMMK.js}

@@ -565,6 +565,26 @@ var MoonIcon = () => /* @__PURE__ */ jsx2(Icon, { d: "M21 12.79A9 9 0 1 1 11.21
 var SunIcon = () => /* @__PURE__ */ jsx2(Icon, { d: "M12 7a5 5 0 1 0 0 10 5 5 0 0 0 0-10Z" });
 var ArrowLeft = () => /* @__PURE__ */ jsx2(Icon, { d: "M19 12H5M12 19l-7-7 7-7", size: 14 });
 var ArrowRight = () => /* @__PURE__ */ jsx2(Icon, { d: "M5 12h14M12 5l7 7-7 7", size: 14 });
+var PencilIcon = () => /* @__PURE__ */ jsx2(Icon, { d: "M17 3a2.83 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z", size: 13 });
+function formatRelativeDate(isoDate) {
+  const date = new Date(isoDate);
+  const now = /* @__PURE__ */ new Date();
+  const diffMs = now.getTime() - date.getTime();
+  if (isNaN(diffMs)) return "";
+  const seconds = Math.floor(diffMs / 1e3);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  const months = Math.floor(days / 30);
+  const years = Math.floor(days / 365);
+  if (seconds < 60) return "just now";
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  if (days < 30) return `${days} day${days === 1 ? "" : "s"} ago`;
+  if (months < 12) return `${months} month${months === 1 ? "" : "s"} ago`;
+  if (years >= 1) return `${years} year${years === 1 ? "" : "s"} ago`;
+  return date.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+}
 var pagefindInstance = null;
 var PAGEFIND_PATH = "/_pagefind/pagefind.js";
 async function initPagefind() {
@@ -686,6 +706,68 @@ function AlgoliaSearchModal({
 var VersionIcon = () => /* @__PURE__ */ jsx2(Icon, { d: "M12 8v4l3 3m6-3a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z", size: 14 });
 var GlobeIcon = () => /* @__PURE__ */ jsx2(Icon, { d: "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18ZM3.6 9h16.8M3.6 15h16.8M12 3a15 15 0 0 1 4 9 15 15 0 0 1-4 9 15 15 0 0 1-4-9 15 15 0 0 1 4-9Z", size: 14 });
 var ExtLinkIcon = () => /* @__PURE__ */ jsx2(Icon, { d: "M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6M15 3h6v6M10 14L21 3", size: 11 });
+var CHANGELOG_SECTION_COLORS = {
+  Added: "#22c55e",
+  Changed: "#3b82f6",
+  Deprecated: "#f59e0b",
+  Removed: "#ef4444",
+  Fixed: "#8b5cf6",
+  Security: "#f97316"
+};
+function ChangelogView({ entries }) {
+  const [showAll, setShowAll] = useState2(entries.length <= 5);
+  const visible = showAll ? entries : entries.slice(0, 5);
+  return /* @__PURE__ */ jsxs2("div", { "data-testid": "changelog-timeline", style: { position: "relative" }, children: [
+    /* @__PURE__ */ jsx2("div", { style: { position: "absolute", left: 15, top: 8, bottom: 8, width: 2, background: "var(--bd)" } }),
+    visible.map((entry, i) => /* @__PURE__ */ jsxs2(
+      "div",
+      {
+        "data-testid": `changelog-entry-${entry.version}`,
+        style: { position: "relative", paddingLeft: 44, paddingBottom: i < visible.length - 1 ? 32 : 0 },
+        children: [
+          /* @__PURE__ */ jsx2("div", { style: {
+            position: "absolute",
+            left: 8,
+            top: 6,
+            width: 16,
+            height: 16,
+            borderRadius: "50%",
+            background: entry.version === "Unreleased" ? "var(--txM)" : "var(--ac)",
+            border: "3px solid var(--bg, #1a1a1a)"
+          } }),
+          /* @__PURE__ */ jsxs2("div", { style: { display: "flex", alignItems: "baseline", gap: 12, marginBottom: 12 }, children: [
+            /* @__PURE__ */ jsx2("span", { style: { fontSize: 18, fontWeight: 700, color: "var(--tx)", fontFamily: "var(--font-heading, inherit)" }, children: entry.url ? /* @__PURE__ */ jsx2("a", { href: entry.url, target: "_blank", rel: "noopener noreferrer", style: { color: "inherit", textDecoration: "none" }, children: entry.version }) : entry.version }),
+            entry.date && /* @__PURE__ */ jsx2("span", { style: { fontSize: 13, color: "var(--txM)", fontFamily: "var(--font-code, monospace)" }, children: entry.date })
+          ] }),
+          entry.sections.map((section) => {
+            const sColor = CHANGELOG_SECTION_COLORS[section.type] || "#6b7280";
+            return /* @__PURE__ */ jsxs2("div", { style: { marginBottom: 16 }, children: [
+              /* @__PURE__ */ jsxs2("div", { style: { display: "inline-flex", alignItems: "center", gap: 6, marginBottom: 8 }, children: [
+                /* @__PURE__ */ jsx2("span", { style: { display: "inline-block", width: 8, height: 8, borderRadius: "50%", background: sColor } }),
+                /* @__PURE__ */ jsx2("span", { style: { fontSize: 12, fontWeight: 600, textTransform: "uppercase", letterSpacing: ".06em", color: sColor, fontFamily: "var(--font-code, monospace)" }, children: section.type })
+              ] }),
+              /* @__PURE__ */ jsx2("ul", { style: { margin: 0, paddingLeft: 18, listStyleType: "disc", color: "var(--tx2)" }, children: section.items.map((item, j) => /* @__PURE__ */ jsx2("li", { style: { fontSize: 14, lineHeight: 1.7, color: "var(--tx2)", marginBottom: 2 }, children: item }, j)) })
+            ] }, section.type);
+          })
+        ]
+      },
+      entry.version
+    )),
+    !showAll && entries.length > 5 && /* @__PURE__ */ jsx2("div", { style: { textAlign: "center", marginTop: 24 }, children: /* @__PURE__ */ jsxs2(
+      "button",
+      {
+        "data-testid": "changelog-show-more",
+        onClick: () => setShowAll(true),
+        style: { background: "none", border: "1px solid var(--bd)", borderRadius: 2, padding: "8px 20px", color: "var(--tx2)", fontSize: 13, fontFamily: "var(--font-body, inherit)", cursor: "pointer" },
+        children: [
+          "Show all ",
+          entries.length,
+          " releases"
+        ]
+      }
+    ) })
+  ] });
+}
 function Shell({
   config: config2,
   navigation: navigation2,
@@ -696,6 +778,10 @@ function Shell({
   pageTitle,
   pageDescription,
   headings,
+  tocEnabled = true,
+  editUrl,
+  lastUpdated,
+  changelogEntries,
   onNavigate,
   allPages,
   versioning,
@@ -744,6 +830,60 @@ function Shell({
   useEffect2(() => {
     contentRef.current?.scrollTo(0, 0);
   }, [currentPageId]);
+  const tocConfig = config2.toc;
+  const tocDepth = tocConfig?.depth ?? 3;
+  const tocGlobalEnabled = tocConfig?.enabled !== false;
+  const showToc = tocGlobalEnabled && tocEnabled;
+  const filteredHeadings = headings.filter((h) => h.depth <= tocDepth);
+  const [activeHeadingId, setActiveHeadingId] = useState2("");
+  useEffect2(() => {
+    if (!showToc || filteredHeadings.length < 2) return;
+    const scrollRoot = contentRef.current;
+    if (!scrollRoot) return;
+    const timerId = setTimeout(() => {
+      const headingElements = [];
+      for (const h of filteredHeadings) {
+        const el = scrollRoot.querySelector(`#${CSS.escape(h.id)}`);
+        if (el) headingElements.push(el);
+      }
+      if (headingElements.length === 0) return;
+      const observer = new IntersectionObserver(
+        (entries) => {
+          const visible = entries.filter((e) => e.isIntersecting).sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+          if (visible.length > 0) {
+            setActiveHeadingId(visible[0].target.id);
+          }
+        },
+        {
+          root: scrollRoot,
+          // Trigger when heading enters the top 20% of the scroll container
+          rootMargin: "0px 0px -80% 0px",
+          threshold: 0
+        }
+      );
+      for (const el of headingElements) observer.observe(el);
+      observerRef.current = observer;
+    }, 100);
+    return () => {
+      clearTimeout(timerId);
+      observerRef.current?.disconnect();
+      observerRef.current = null;
+    };
+  }, [currentPageId, showToc, filteredHeadings.map((h) => h.id).join(",")]);
+  const observerRef = useRef2(null);
+  useEffect2(() => {
+    setActiveHeadingId("");
+  }, [currentPageId]);
+  const scrollToHeading = useCallback2((e, id) => {
+    e.preventDefault();
+    const scrollRoot = contentRef.current;
+    if (!scrollRoot) return;
+    const target = scrollRoot.querySelector(`#${CSS.escape(id)}`);
+    if (target) {
+      target.scrollIntoView({ behavior: "smooth", block: "start" });
+      setActiveHeadingId(id);
+    }
+  }, []);
   useEffect2(() => {
     const h = (e) => {
       if ((e.metaKey || e.ctrlKey) && e.key === "k") {
@@ -815,7 +955,7 @@ function Shell({
         transition: "width .2s, min-width .2s",
         overflow: "hidden"
       }, children: [
-        /* @__PURE__ */ jsxs2("div", { style: { padding: "18px 20px", display: "flex", alignItems: "baseline", gap: 6, borderBottom: "1px solid var(--bd)" }, children: [
+        /* @__PURE__ */ jsxs2("a", { href: "/", style: { padding: "18px 20px", display: "flex", alignItems: "baseline", gap: 6, borderBottom: "1px solid var(--bd)", textDecoration: "none", color: "inherit" }, children: [
           /* @__PURE__ */ jsx2("span", { style: { fontFamily: "var(--font-heading)", fontSize: 22, fontWeight: 700, fontStyle: "italic" }, children: config2.name }),
           /* @__PURE__ */ jsx2("span", { style: { width: 5, height: 5, borderRadius: "50%", background: "var(--ac)", display: "inline-block" } })
         ] }),
@@ -1138,14 +1278,44 @@ function Shell({
           /* @__PURE__ */ jsxs2("main", { style: { flex: 1, maxWidth: 760, padding: "40px 48px 80px", margin: "0 auto" }, children: [
             /* @__PURE__ */ jsx2("h1", { style: { fontFamily: "var(--font-heading)", fontSize: 38, fontWeight: 400, fontStyle: "italic", lineHeight: 1.15, marginBottom: 8 }, children: pageTitle }),
             pageDescription && /* @__PURE__ */ jsx2("p", { style: { fontSize: 16, color: "var(--tx2)", lineHeight: 1.6, marginBottom: 32 }, children: pageDescription }),
-            /* @__PURE__ */ jsx2("div", { style: { borderTop: "1px solid var(--bd)", paddingTop: 28 }, children: PageComponent ? /* @__PURE__ */ jsx2("div", { className: "tome-content", children: /* @__PURE__ */ jsx2(PageComponent, { components: mdxComponents || {} }) }) : /* @__PURE__ */ jsx2(
+            /* @__PURE__ */ jsx2("div", { style: { borderTop: "1px solid var(--bd)", paddingTop: 28 }, children: changelogEntries && changelogEntries.length > 0 ? /* @__PURE__ */ jsx2(ChangelogView, { entries: changelogEntries }) : PageComponent ? /* @__PURE__ */ jsx2("div", { className: "tome-content", children: /* @__PURE__ */ jsx2(PageComponent, { components: mdxComponents || {} }) }) : /* @__PURE__ */ jsx2(
               "div",
               {
                 className: "tome-content",
-                dangerouslySetInnerHTML: { __html: pageHtml || "" }
+                dangerouslySetInnerHTML: { __html: (pageHtml || "").replace(/<h1[^>]*>[\s\S]*?<\/h1>\s*/, "") }
               }
             ) }),
-            /* @__PURE__ */ jsxs2("div", { style: { display: "flex", justifyContent: "space-between", marginTop: 48, paddingTop: 24, borderTop: "1px solid var(--bd)", gap: 16 }, children: [
+            (editUrl || lastUpdated) && /* @__PURE__ */ jsxs2("div", { style: { marginTop: 40, display: "flex", alignItems: "center", justifyContent: "space-between", gap: 16 }, children: [
+              editUrl && /* @__PURE__ */ jsx2("div", { "data-testid": "edit-page-link", children: /* @__PURE__ */ jsxs2(
+                "a",
+                {
+                  href: editUrl,
+                  target: "_blank",
+                  rel: "noopener noreferrer",
+                  style: {
+                    display: "inline-flex",
+                    alignItems: "center",
+                    gap: 6,
+                    color: "var(--txM)",
+                    textDecoration: "none",
+                    fontSize: 13,
+                    fontFamily: "var(--font-body)",
+                    transition: "color .15s"
+                  },
+                  onMouseOver: (e) => e.currentTarget.style.color = "var(--ac)",
+                  onMouseOut: (e) => e.currentTarget.style.color = "var(--txM)",
+                  children: [
+                    /* @__PURE__ */ jsx2(PencilIcon, {}),
+                    " Edit this page on GitHub"
+                  ]
+                }
+              ) }),
+              lastUpdated && /* @__PURE__ */ jsxs2("div", { "data-testid": "last-updated", style: { fontSize: 12, color: "var(--txM)", fontFamily: "var(--font-body)" }, children: [
+                "Last updated ",
+                formatRelativeDate(lastUpdated)
+              ] })
+            ] }),
+            /* @__PURE__ */ jsxs2("div", { style: { display: "flex", justifyContent: "space-between", marginTop: editUrl || lastUpdated ? 16 : 48, paddingTop: 24, borderTop: "1px solid var(--bd)", gap: 16 }, children: [
               prev ? /* @__PURE__ */ jsxs2("button", { onClick: () => onNavigate(prev.id), style: {
                 display: "flex",
                 alignItems: "center",
@@ -1184,18 +1354,34 @@ function Shell({
               ] }) : /* @__PURE__ */ jsx2("div", {})
             ] })
           ] }),
-          headings.length > 0 && wide && /* @__PURE__ */ jsxs2("aside", { style: { width: 200, padding: "40px 16px 40px 0", position: "sticky", top: 0, alignSelf: "flex-start", flexShrink: 0 }, children: [
+          showToc && filteredHeadings.length >= 2 && wide && /* @__PURE__ */ jsxs2("aside", { "data-testid": "toc-sidebar", style: { width: 200, padding: "40px 16px 40px 0", position: "sticky", top: 0, alignSelf: "flex-start", flexShrink: 0 }, children: [
             /* @__PURE__ */ jsx2("div", { style: { fontSize: 10, fontWeight: 600, textTransform: "uppercase", letterSpacing: ".1em", color: "var(--txM)", marginBottom: 12, fontFamily: "var(--font-code)" }, children: "On this page" }),
-            /* @__PURE__ */ jsx2("div", { style: { borderLeft: "1px solid var(--bd)", paddingLeft: 0 }, children: headings.map((h, i) => /* @__PURE__ */ jsx2("a", { href: `#${h.id}`, style: {
-              display: "block",
-              fontSize: 12,
-              color: "var(--txM)",
-              textDecoration: "none",
-              padding: "4px 12px",
-              paddingLeft: 12 + (h.depth - 2) * 12,
-              lineHeight: 1.4,
-              transition: "color .12s"
-            }, children: h.text }, i)) })
+            /* @__PURE__ */ jsx2("nav", { "aria-label": "Table of contents", style: { borderLeft: "1px solid var(--bd)", paddingLeft: 0 }, children: filteredHeadings.map((h, i) => {
+              const isActive = activeHeadingId === h.id;
+              return /* @__PURE__ */ jsx2(
+                "a",
+                {
+                  href: `#${h.id}`,
+                  onClick: (e) => scrollToHeading(e, h.id),
+                  "data-testid": `toc-link-${h.id}`,
+                  style: {
+                    display: "block",
+                    fontSize: 12,
+                    color: isActive ? "var(--ac)" : "var(--txM)",
+                    fontWeight: isActive ? 500 : 400,
+                    textDecoration: "none",
+                    padding: "4px 12px",
+                    paddingLeft: 12 + (h.depth - 2) * 12,
+                    lineHeight: 1.4,
+                    transition: "color .15s, font-weight .15s",
+                    borderLeft: isActive ? "2px solid var(--ac)" : "2px solid transparent",
+                    marginLeft: -1
+                  },
+                  children: h.text
+                },
+                i
+              );
+            }) })
           ] })
         ] })
       ] })
@@ -1355,7 +1541,8 @@ import {
   Card,
   CardGroup,
   Steps,
-  Accordion
+  Accordion,
+  ChangelogTimeline
 } from "@tomehq/components";
 import { Fragment, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
 var MDX_COMPONENTS = {
@@ -1364,11 +1551,13 @@ var MDX_COMPONENTS = {
   Card,
   CardGroup,
   Steps,
-  Accordion
+  Accordion,
+  ChangelogTimeline
 };
 var contentStyles = `
   @import url('https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@300;400;500;600;700&family=Cormorant+Garamond:ital,wght@0,300;0,400;0,600;0,700;1,300;1,400;1,700&family=Fira+Code:wght@400;500;600&display=swap');
 
+  .tome-content h1 { display: none; }
   .tome-content h2 { font-family: var(--font-body); font-size: 1.35em; font-weight: 600; margin-top: 2em; margin-bottom: 0.5em; display: flex; align-items: center; gap: 10px; letter-spacing: 0.01em; }
   .tome-content h2::before { content: "#"; font-family: var(--font-heading); font-size: 1.2em; font-weight: 300; font-style: italic; color: var(--ac); opacity: 0.5; }
   .tome-content h3 { font-family: var(--font-body); font-size: 1.15em; font-weight: 600; margin-top: 1.5em; margin-bottom: 0.5em; }
@@ -1424,6 +1613,9 @@ async function loadPage(id) {
       };
     }
     if (!mod.default) return null;
+    if (mod.isChangelog && mod.changelogEntries) {
+      return { isMdx: false, ...mod.default, changelogEntries: mod.changelogEntries };
+    }
     return { isMdx: false, ...mod.default };
   } catch (err) {
     console.error(`Failed to load page: ${id}`, err);
@@ -1464,6 +1656,13 @@ function App() {
     title: r.frontmatter.title,
     description: r.frontmatter.description
   }));
+  const currentRoute = routes.find((r) => r.id === currentPageId);
+  let editUrl;
+  if (config.editLink && currentRoute?.filePath) {
+    const { repo, branch = "main", dir = "" } = config.editLink;
+    const dirPrefix = dir ? `${dir.replace(/\/$/, "")}/` : "";
+    editUrl = `https://github.com/${repo}/edit/${branch}/${dirPrefix}${currentRoute.filePath}`;
+  }
   return /* @__PURE__ */ jsxs3(Fragment, { children: [
     /* @__PURE__ */ jsx3("style", { children: contentStyles }),
     /* @__PURE__ */ jsx3(
@@ -1478,6 +1677,10 @@ function App() {
         pageTitle: pageData?.frontmatter.title || (loading ? "Loading..." : "Not Found"),
         pageDescription: pageData?.frontmatter.description,
         headings: pageData?.headings || [],
+        tocEnabled: pageData?.frontmatter.toc !== false,
+        editUrl,
+        lastUpdated: currentRoute?.lastUpdated,
+        changelogEntries: !pageData?.isMdx ? pageData?.changelogEntries : void 0,
         onNavigate: navigateTo,
         allPages,
         docContext

package/dist/entry.js

@@ -1,6 +1,6 @@
 import {
   entry_default
-} from "./chunk-JA4PMX6M.js";
+} from "./chunk-CTPOZMMK.js";
 export {
   entry_default as default
 };

package/dist/index.d.ts

@@ -36,6 +36,10 @@ interface ShellProps {
             model?: string;
             apiKeyEnv?: string;
         };
+        toc?: {
+            enabled?: boolean;
+            depth?: number;
+        };
         topNav?: Array<{
             label: string;
             href: string;
@@ -64,6 +68,18 @@ interface ShellProps {
         text: string;
         id: string;
     }>;
+    tocEnabled?: boolean;
+    editUrl?: string;
+    lastUpdated?: string;
+    changelogEntries?: Array<{
+        version: string;
+        date?: string;
+        url?: string;
+        sections: Array<{
+            type: string;
+            items: string[];
+        }>;
+    }>;
     onNavigate: (id: string) => void;
     allPages: Array<{
         id: string;
@@ -80,7 +96,7 @@ interface ShellProps {
         content: string;
     }>;
 }
-declare function Shell({ config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents, pageTitle, pageDescription, headings, onNavigate, allPages, versioning, currentVersion, i18n, currentLocale, docContext, }: ShellProps): react_jsx_runtime.JSX.Element;
+declare function Shell({ config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents, pageTitle, pageDescription, headings, tocEnabled, editUrl, lastUpdated, changelogEntries, onNavigate, allPages, versioning, currentVersion, i18n, currentLocale, docContext, }: ShellProps): react_jsx_runtime.JSX.Element;
 
 interface AiChatProps {
     provider: "openai" | "anthropic" | "custom";

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   Shell,
   THEME_PRESETS,
   entry_default
-} from "./chunk-JA4PMX6M.js";
+} from "./chunk-CTPOZMMK.js";
 export {
   AiChat,
   entry_default as App,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomehq/theme",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Tome default theme and React app shell",
   "type": "module",
   "main": "./src/index.tsx",
@@ -9,8 +9,8 @@
     "./entry": "./src/entry.tsx"
   },
   "dependencies": {
-    "@tomehq/components": "0.1.1",
-    "@tomehq/core": "0.1.1"
+    "@tomehq/components": "0.2.1",
+    "@tomehq/core": "0.2.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/Shell.test.tsx

@@ -182,22 +182,121 @@ describe("Shell theme mode", () => {
   });
 });
 
-// ── TOC ───────────────────────────────────────────────────
+// ── TOC (TOM-52) ──────────────────────────────────────────
 
 describe("Shell table of contents", () => {
-  it("renders TOC headings when headings are provided", () => {
+  beforeEach(() => {
     // jsdom window.innerWidth defaults to 0 so 'wide' will be false — we need to set it
     Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 1400 });
     fireEvent(window, new Event("resize"));
+  });
 
-    renderShell({
-      headings: [
-        { depth: 2, text: "Overview", id: "overview" },
-        { depth: 3, text: "Details", id: "details" },
-      ],
-    });
+  const sampleHeadings = [
+    { depth: 2, text: "Overview", id: "overview" },
+    { depth: 3, text: "Details", id: "details" },
+    { depth: 2, text: "Usage", id: "usage" },
+  ];
+
+  it("renders TOC headings when headings are provided", () => {
+    renderShell({ headings: sampleHeadings });
+    expect(screen.getByTestId("toc-sidebar")).toBeInTheDocument();
     expect(screen.getByText("Overview")).toBeInTheDocument();
     expect(screen.getByText("Details")).toBeInTheDocument();
+    expect(screen.getByText("Usage")).toBeInTheDocument();
+  });
+
+  it("renders 'On this page' label", () => {
+    renderShell({ headings: sampleHeadings });
+    expect(screen.getByText("On this page")).toBeInTheDocument();
+  });
+
+  it("renders TOC links with correct href attributes", () => {
+    renderShell({ headings: sampleHeadings });
+    const overviewLink = screen.getByTestId("toc-link-overview");
+    expect(overviewLink).toHaveAttribute("href", "#overview");
+    const detailsLink = screen.getByTestId("toc-link-details");
+    expect(detailsLink).toHaveAttribute("href", "#details");
+  });
+
+  it("renders TOC inside a nav element with aria-label", () => {
+    renderShell({ headings: sampleHeadings });
+    const nav = screen.getByRole("navigation", { name: "Table of contents" });
+    expect(nav).toBeInTheDocument();
+  });
+
+  it("does not render TOC when fewer than 2 headings", () => {
+    renderShell({
+      headings: [{ depth: 2, text: "Only One", id: "only-one" }],
+    });
+    expect(screen.queryByTestId("toc-sidebar")).not.toBeInTheDocument();
+  });
+
+  it("does not render TOC when headings array is empty", () => {
+    renderShell({ headings: [] });
+    expect(screen.queryByTestId("toc-sidebar")).not.toBeInTheDocument();
+  });
+
+  it("hides TOC when tocEnabled is false (frontmatter toc: false)", () => {
+    renderShell({ headings: sampleHeadings, tocEnabled: false });
+    expect(screen.queryByTestId("toc-sidebar")).not.toBeInTheDocument();
+  });
+
+  it("hides TOC when config toc.enabled is false", () => {
+    renderShell({
+      headings: sampleHeadings,
+      config: { ...baseConfig, toc: { enabled: false } },
+    });
+    expect(screen.queryByTestId("toc-sidebar")).not.toBeInTheDocument();
+  });
+
+  it("filters headings by config toc.depth", () => {
+    const headingsWithH4 = [
+      { depth: 2, text: "Section", id: "section" },
+      { depth: 3, text: "Subsection", id: "subsection" },
+      { depth: 4, text: "Deep", id: "deep" },
+    ];
+    // depth: 2 means only h2 headings
+    renderShell({
+      headings: headingsWithH4,
+      config: { ...baseConfig, toc: { depth: 2 } },
+    });
+    // Only h2 shown, but need at least 2 headings — only 1 h2 so TOC hidden
+    expect(screen.queryByTestId("toc-sidebar")).not.toBeInTheDocument();
+  });
+
+  it("shows only headings up to configured depth", () => {
+    const headingsMultiDepth = [
+      { depth: 2, text: "First", id: "first" },
+      { depth: 2, text: "Second", id: "second" },
+      { depth: 3, text: "Sub", id: "sub" },
+      { depth: 4, text: "Deep", id: "deep" },
+    ];
+    // depth: 3 means h2 + h3, but not h4
+    renderShell({
+      headings: headingsMultiDepth,
+      config: { ...baseConfig, toc: { depth: 3 } },
+    });
+    expect(screen.getByTestId("toc-sidebar")).toBeInTheDocument();
+    expect(screen.getByText("First")).toBeInTheDocument();
+    expect(screen.getByText("Second")).toBeInTheDocument();
+    expect(screen.getByText("Sub")).toBeInTheDocument();
+    expect(screen.queryByTestId("toc-link-deep")).not.toBeInTheDocument();
+  });
+
+  it("hides TOC on narrow viewports", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 800 });
+    fireEvent(window, new Event("resize"));
+
+    renderShell({ headings: sampleHeadings });
+    expect(screen.queryByTestId("toc-sidebar")).not.toBeInTheDocument();
+  });
+
+  it("shows TOC on wide viewports", () => {
+    Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 1400 });
+    fireEvent(window, new Event("resize"));
+
+    renderShell({ headings: sampleHeadings });
+    expect(screen.getByTestId("toc-sidebar")).toBeInTheDocument();
   });
 });
 
@@ -541,6 +640,141 @@ describe("Shell language switcher", () => {
   });
 });
 
+// ── Edit this page on GitHub (TOM-48) ────────────────────
+
+describe("Shell edit link", () => {
+  it("renders edit link when editUrl is provided", () => {
+    renderShell({ editUrl: "https://github.com/org/repo/edit/main/docs/intro.md" });
+    const link = screen.getByTestId("edit-page-link");
+    expect(link).toBeInTheDocument();
+    expect(link.querySelector("a")?.getAttribute("href")).toBe(
+      "https://github.com/org/repo/edit/main/docs/intro.md"
+    );
+  });
+
+  it("edit link opens in new tab", () => {
+    renderShell({ editUrl: "https://github.com/org/repo/edit/main/docs/intro.md" });
+    const anchor = screen.getByTestId("edit-page-link").querySelector("a");
+    expect(anchor?.getAttribute("target")).toBe("_blank");
+    expect(anchor?.getAttribute("rel")).toBe("noopener noreferrer");
+  });
+
+  it("shows 'Edit this page on GitHub' text", () => {
+    renderShell({ editUrl: "https://github.com/org/repo/edit/main/docs/intro.md" });
+    expect(screen.getByText("Edit this page on GitHub")).toBeInTheDocument();
+  });
+
+  it("does not render edit link when editUrl is not provided", () => {
+    renderShell();
+    expect(screen.queryByTestId("edit-page-link")).not.toBeInTheDocument();
+  });
+
+  it("does not render edit link when editUrl is undefined", () => {
+    renderShell({ editUrl: undefined });
+    expect(screen.queryByTestId("edit-page-link")).not.toBeInTheDocument();
+  });
+});
+
+// ── Last Updated (TOM-54) ────────────────────────────────
+
+describe("Shell last updated", () => {
+  it("renders last updated when lastUpdated is provided", () => {
+    renderShell({ lastUpdated: "2025-01-15T10:00:00Z" });
+    const el = screen.getByTestId("last-updated");
+    expect(el).toBeInTheDocument();
+    expect(el.textContent).toContain("Last updated");
+  });
+
+  it("does not render last updated when lastUpdated is not provided", () => {
+    renderShell();
+    expect(screen.queryByTestId("last-updated")).not.toBeInTheDocument();
+  });
+
+  it("does not render last updated when lastUpdated is undefined", () => {
+    renderShell({ lastUpdated: undefined });
+    expect(screen.queryByTestId("last-updated")).not.toBeInTheDocument();
+  });
+
+  it("renders both edit link and last updated when both provided", () => {
+    renderShell({
+      editUrl: "https://github.com/org/repo/edit/main/docs/intro.md",
+      lastUpdated: "2025-06-01T12:00:00Z",
+    });
+    expect(screen.getByTestId("edit-page-link")).toBeInTheDocument();
+    expect(screen.getByTestId("last-updated")).toBeInTheDocument();
+  });
+
+  it("shows relative date text for recent date", () => {
+    // Use a date from "1 day ago" to test relative formatting
+    const yesterday = new Date(Date.now() - 86400000).toISOString();
+    renderShell({ lastUpdated: yesterday });
+    const el = screen.getByTestId("last-updated");
+    expect(el.textContent).toContain("Last updated 1 day ago");
+  });
+});
+
+// ── Changelog (TOM-49) ──────────────────────────────────
+
+describe("Shell changelog rendering", () => {
+  const sampleEntries = [
+    {
+      version: "2.0.0",
+      date: "2025-06-01",
+      sections: [
+        { type: "Added", items: ["New feature", "Another feature"] },
+        { type: "Fixed", items: ["Bug fix"] },
+      ],
+    },
+    {
+      version: "1.0.0",
+      date: "2025-01-15",
+      sections: [
+        { type: "Added", items: ["Initial release"] },
+      ],
+    },
+  ];
+
+  it("renders changelog timeline when entries provided", () => {
+    renderShell({ changelogEntries: sampleEntries });
+    expect(screen.getByTestId("changelog-timeline")).toBeInTheDocument();
+  });
+
+  it("renders each changelog entry", () => {
+    renderShell({ changelogEntries: sampleEntries });
+    expect(screen.getByTestId("changelog-entry-2.0.0")).toBeInTheDocument();
+    expect(screen.getByTestId("changelog-entry-1.0.0")).toBeInTheDocument();
+  });
+
+  it("renders version text and dates", () => {
+    renderShell({ changelogEntries: sampleEntries });
+    expect(screen.getByText("2.0.0")).toBeInTheDocument();
+    expect(screen.getByText("2025-06-01")).toBeInTheDocument();
+  });
+
+  it("renders section labels", () => {
+    renderShell({ changelogEntries: sampleEntries });
+    expect(screen.getAllByText("Added").length).toBeGreaterThan(0);
+    expect(screen.getByText("Fixed")).toBeInTheDocument();
+  });
+
+  it("renders change items", () => {
+    renderShell({ changelogEntries: sampleEntries });
+    expect(screen.getByText("New feature")).toBeInTheDocument();
+    expect(screen.getByText("Bug fix")).toBeInTheDocument();
+    expect(screen.getByText("Initial release")).toBeInTheDocument();
+  });
+
+  it("does not render changelog when no entries provided", () => {
+    renderShell();
+    expect(screen.queryByTestId("changelog-timeline")).not.toBeInTheDocument();
+  });
+
+  it("does not render changelog when entries array is empty", () => {
+    renderShell({ changelogEntries: [] });
+    expect(screen.queryByTestId("changelog-timeline")).not.toBeInTheDocument();
+  });
+});
+
 // ── AI Chat (TOM-32) ─────────────────────────────────────
 
 describe("Shell AI chat integration", () => {

package/src/Shell.tsx

@@ -44,6 +44,28 @@ const MoonIcon = () => <Icon d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"
 const SunIcon = () => <Icon d="M12 7a5 5 0 1 0 0 10 5 5 0 0 0 0-10Z" />;
 const ArrowLeft = () => <Icon d="M19 12H5M12 19l-7-7 7-7" size={14} />;
 const ArrowRight = () => <Icon d="M5 12h14M12 5l7 7-7 7" size={14} />;
+const PencilIcon = () => <Icon d="M17 3a2.83 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z" size={13} />;
+
+// ── RELATIVE DATE FORMATTER (TOM-54) ─────────────────────
+function formatRelativeDate(isoDate: string): string {
+  const date = new Date(isoDate);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  if (isNaN(diffMs)) return "";
+  const seconds = Math.floor(diffMs / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  const months = Math.floor(days / 30);
+  const years = Math.floor(days / 365);
+  if (seconds < 60) return "just now";
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  if (days < 30) return `${days} day${days === 1 ? "" : "s"} ago`;
+  if (months < 12) return `${months} month${months === 1 ? "" : "s"} ago`;
+  if (years >= 1) return `${years} year${years === 1 ? "" : "s"} ago`;
+  return date.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+}
 
 // ── PAGEFIND CLIENT (TOM-15) ─────────────────────────────
 let pagefindInstance: any = null;
@@ -195,12 +217,79 @@ export interface I18nInfo {
   localeNames?: Record<string, string>;
 }
 
+// ── CHANGELOG VIEW (TOM-49) ─────────────────────────────
+const CHANGELOG_SECTION_COLORS: Record<string, string> = {
+  Added: "#22c55e", Changed: "#3b82f6", Deprecated: "#f59e0b",
+  Removed: "#ef4444", Fixed: "#8b5cf6", Security: "#f97316",
+};
+
+interface ChangelogViewEntry {
+  version: string;
+  date?: string;
+  url?: string;
+  sections: Array<{ type: string; items: string[] }>;
+}
+
+function ChangelogView({ entries }: { entries: ChangelogViewEntry[] }) {
+  const [showAll, setShowAll] = useState(entries.length <= 5);
+  const visible = showAll ? entries : entries.slice(0, 5);
+
+  return (
+    <div data-testid="changelog-timeline" style={{ position: "relative" }}>
+      <div style={{ position: "absolute", left: 15, top: 8, bottom: 8, width: 2, background: "var(--bd)" }} />
+      {visible.map((entry, i) => (
+        <div key={entry.version} data-testid={`changelog-entry-${entry.version}`}
+          style={{ position: "relative", paddingLeft: 44, paddingBottom: i < visible.length - 1 ? 32 : 0 }}>
+          <div style={{
+            position: "absolute", left: 8, top: 6, width: 16, height: 16, borderRadius: "50%",
+            background: entry.version === "Unreleased" ? "var(--txM)" : "var(--ac)",
+            border: "3px solid var(--bg, #1a1a1a)",
+          }} />
+          <div style={{ display: "flex", alignItems: "baseline", gap: 12, marginBottom: 12 }}>
+            <span style={{ fontSize: 18, fontWeight: 700, color: "var(--tx)", fontFamily: "var(--font-heading, inherit)" }}>
+              {entry.url ? (
+                <a href={entry.url} target="_blank" rel="noopener noreferrer" style={{ color: "inherit", textDecoration: "none" }}>{entry.version}</a>
+              ) : entry.version}
+            </span>
+            {entry.date && <span style={{ fontSize: 13, color: "var(--txM)", fontFamily: "var(--font-code, monospace)" }}>{entry.date}</span>}
+          </div>
+          {entry.sections.map((section) => {
+            const sColor = CHANGELOG_SECTION_COLORS[section.type] || "#6b7280";
+            return (
+              <div key={section.type} style={{ marginBottom: 16 }}>
+                <div style={{ display: "inline-flex", alignItems: "center", gap: 6, marginBottom: 8 }}>
+                  <span style={{ display: "inline-block", width: 8, height: 8, borderRadius: "50%", background: sColor }} />
+                  <span style={{ fontSize: 12, fontWeight: 600, textTransform: "uppercase", letterSpacing: ".06em", color: sColor, fontFamily: "var(--font-code, monospace)" }}>{section.type}</span>
+                </div>
+                <ul style={{ margin: 0, paddingLeft: 18, listStyleType: "disc", color: "var(--tx2)" }}>
+                  {section.items.map((item, j) => (
+                    <li key={j} style={{ fontSize: 14, lineHeight: 1.7, color: "var(--tx2)", marginBottom: 2 }}>{item}</li>
+                  ))}
+                </ul>
+              </div>
+            );
+          })}
+        </div>
+      ))}
+      {!showAll && entries.length > 5 && (
+        <div style={{ textAlign: "center", marginTop: 24 }}>
+          <button data-testid="changelog-show-more" onClick={() => setShowAll(true)}
+            style={{ background: "none", border: "1px solid var(--bd)", borderRadius: 2, padding: "8px 20px", color: "var(--tx2)", fontSize: 13, fontFamily: "var(--font-body, inherit)", cursor: "pointer" }}>
+            Show all {entries.length} releases
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+
 interface ShellProps {
   config: {
     name: string;
     theme?: { preset?: string; mode?: string; accent?: string; fonts?: { heading?: string; body?: string; code?: string } };
     search?: { provider?: string; appId?: string; apiKey?: string; indexName?: string };
     ai?: { enabled?: boolean; provider?: "openai" | "anthropic" | "custom"; model?: string; apiKeyEnv?: string };
+    toc?: { enabled?: boolean; depth?: number };
     topNav?: Array<{ label: string; href: string }>;
     [key: string]: unknown;
   };
@@ -215,6 +304,10 @@ interface ShellProps {
   pageTitle: string;
   pageDescription?: string;
   headings: Array<{ depth: number; text: string; id: string }>;
+  tocEnabled?: boolean;
+  editUrl?: string;
+  lastUpdated?: string;
+  changelogEntries?: Array<{ version: string; date?: string; url?: string; sections: Array<{ type: string; items: string[] }> }>;
   onNavigate: (id: string) => void;
   allPages: Array<{ id: string; title: string; description?: string }>;
   versioning?: VersioningInfo;
@@ -226,7 +319,7 @@ interface ShellProps {
 
 export function Shell({
   config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents,
-  pageTitle, pageDescription, headings, onNavigate, allPages,
+  pageTitle, pageDescription, headings, tocEnabled = true, editUrl, lastUpdated, changelogEntries, onNavigate, allPages,
   versioning, currentVersion, i18n, currentLocale, docContext,
 }: ShellProps) {
   const themeMode = config.theme?.mode || "auto";
@@ -286,6 +379,77 @@ export function Shell({
 
   useEffect(() => { contentRef.current?.scrollTo(0, 0); }, [currentPageId]);
 
+  // ── TOC: Config-based depth filtering + frontmatter opt-out ──
+  const tocConfig = config.toc;
+  const tocDepth = tocConfig?.depth ?? 3;
+  const tocGlobalEnabled = tocConfig?.enabled !== false;
+  const showToc = tocGlobalEnabled && tocEnabled;
+  const filteredHeadings = headings.filter(h => h.depth <= tocDepth);
+
+  // ── TOC: Scroll-spy with IntersectionObserver ──
+  const [activeHeadingId, setActiveHeadingId] = useState<string>("");
+
+  useEffect(() => {
+    if (!showToc || filteredHeadings.length < 2) return;
+
+    const scrollRoot = contentRef.current;
+    if (!scrollRoot) return;
+
+    // Small delay to ensure DOM headings are rendered (especially after page load)
+    const timerId = setTimeout(() => {
+      const headingElements: Element[] = [];
+      for (const h of filteredHeadings) {
+        const el = scrollRoot.querySelector(`#${CSS.escape(h.id)}`);
+        if (el) headingElements.push(el);
+      }
+      if (headingElements.length === 0) return;
+
+      const observer = new IntersectionObserver(
+        (entries) => {
+          // Find the topmost visible heading
+          const visible = entries
+            .filter(e => e.isIntersecting)
+            .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+          if (visible.length > 0) {
+            setActiveHeadingId(visible[0].target.id);
+          }
+        },
+        {
+          root: scrollRoot,
+          // Trigger when heading enters the top 20% of the scroll container
+          rootMargin: "0px 0px -80% 0px",
+          threshold: 0,
+        }
+      );
+
+      for (const el of headingElements) observer.observe(el);
+      observerRef.current = observer;
+    }, 100);
+
+    return () => {
+      clearTimeout(timerId);
+      observerRef.current?.disconnect();
+      observerRef.current = null;
+    };
+  }, [currentPageId, showToc, filteredHeadings.map(h => h.id).join(",")]);
+
+  const observerRef = useRef<IntersectionObserver | null>(null);
+
+  // Reset active heading when page changes
+  useEffect(() => { setActiveHeadingId(""); }, [currentPageId]);
+
+  // Smooth scroll handler for TOC links
+  const scrollToHeading = useCallback((e: React.MouseEvent<HTMLAnchorElement>, id: string) => {
+    e.preventDefault();
+    const scrollRoot = contentRef.current;
+    if (!scrollRoot) return;
+    const target = scrollRoot.querySelector(`#${CSS.escape(id)}`);
+    if (target) {
+      target.scrollIntoView({ behavior: "smooth", block: "start" });
+      setActiveHeadingId(id);
+    }
+  }, []);
+
   useEffect(() => {
     const h = (e: KeyboardEvent) => {
       if ((e.metaKey || e.ctrlKey) && e.key === "k") { e.preventDefault(); setSearch(true); }
@@ -342,12 +506,12 @@ export function Shell({
           display: "flex", flexDirection: "column",
           transition: "width .2s, min-width .2s", overflow: "hidden",
         }}>
-          <div style={{ padding: "18px 20px", display: "flex", alignItems: "baseline", gap: 6, borderBottom: "1px solid var(--bd)" }}>
+          <a href="/" style={{ padding: "18px 20px", display: "flex", alignItems: "baseline", gap: 6, borderBottom: "1px solid var(--bd)", textDecoration: "none", color: "inherit" }}>
             <span style={{ fontFamily: "var(--font-heading)", fontSize: 22, fontWeight: 700, fontStyle: "italic" }}>
               {config.name}
             </span>
             <span style={{ width: 5, height: 5, borderRadius: "50%", background: "var(--ac)", display: "inline-block" }} />
-          </div>
+          </a>
 
           <div style={{ padding: "12px 14px" }}>
             <button onClick={() => setSearch(true)} style={{
@@ -607,21 +771,52 @@ export function Shell({
               </h1>
               {pageDescription && <p style={{ fontSize: 16, color: "var(--tx2)", lineHeight: 1.6, marginBottom: 32 }}>{pageDescription}</p>}
               <div style={{ borderTop: "1px solid var(--bd)", paddingTop: 28 }}>
-                {/* TOM-8: Render MDX component or raw HTML */}
-                {PageComponent ? (
+                {/* TOM-49: Changelog page type */}
+                {changelogEntries && changelogEntries.length > 0 ? (
+                  <ChangelogView entries={changelogEntries} />
+                ) : PageComponent ? (
                   <div className="tome-content">
                     <PageComponent components={mdxComponents || {}} />
                   </div>
                 ) : (
                   <div
                     className="tome-content"
-                    dangerouslySetInnerHTML={{ __html: pageHtml || "" }}
+                    dangerouslySetInnerHTML={{ __html: (pageHtml || "").replace(/<h1[^>]*>[\s\S]*?<\/h1>\s*/, "") }}
                   />
                 )}
               </div>
 
+              {/* TOM-48: Edit this page link + TOM-54: Last updated */}
+              {(editUrl || lastUpdated) && (
+                <div style={{ marginTop: 40, display: "flex", alignItems: "center", justifyContent: "space-between", gap: 16 }}>
+                  {editUrl && (
+                    <div data-testid="edit-page-link">
+                      <a
+                        href={editUrl}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        style={{
+                          display: "inline-flex", alignItems: "center", gap: 6,
+                          color: "var(--txM)", textDecoration: "none", fontSize: 13,
+                          fontFamily: "var(--font-body)", transition: "color .15s",
+                        }}
+                        onMouseOver={(e) => (e.currentTarget.style.color = "var(--ac)")}
+                        onMouseOut={(e) => (e.currentTarget.style.color = "var(--txM)")}
+                      >
+                        <PencilIcon /> Edit this page on GitHub
+                      </a>
+                    </div>
+                  )}
+                  {lastUpdated && (
+                    <div data-testid="last-updated" style={{ fontSize: 12, color: "var(--txM)", fontFamily: "var(--font-body)" }}>
+                      Last updated {formatRelativeDate(lastUpdated)}
+                    </div>
+                  )}
+                </div>
+              )}
+
               {/* Prev / Next */}
-              <div style={{ display: "flex", justifyContent: "space-between", marginTop: 48, paddingTop: 24, borderTop: "1px solid var(--bd)", gap: 16 }}>
+              <div style={{ display: "flex", justifyContent: "space-between", marginTop: (editUrl || lastUpdated) ? 16 : 48, paddingTop: 24, borderTop: "1px solid var(--bd)", gap: 16 }}>
                 {prev ? (
                   <button onClick={() => onNavigate(prev.id)} style={{
                     display: "flex", alignItems: "center", gap: 8, background: "none",
@@ -641,19 +836,35 @@ export function Shell({
               </div>
             </main>
 
-            {/* TOC */}
-            {headings.length > 0 && wide && (
-              <aside style={{ width: 200, padding: "40px 16px 40px 0", position: "sticky", top: 0, alignSelf: "flex-start", flexShrink: 0 }}>
+            {/* TOC (TOM-52) */}
+            {showToc && filteredHeadings.length >= 2 && wide && (
+              <aside data-testid="toc-sidebar" style={{ width: 200, padding: "40px 16px 40px 0", position: "sticky", top: 0, alignSelf: "flex-start", flexShrink: 0 }}>
                 <div style={{ fontSize: 10, fontWeight: 600, textTransform: "uppercase", letterSpacing: ".1em", color: "var(--txM)", marginBottom: 12, fontFamily: "var(--font-code)" }}>On this page</div>
-                <div style={{ borderLeft: "1px solid var(--bd)", paddingLeft: 0 }}>
-                  {headings.map((h, i) => (
-                    <a key={i} href={`#${h.id}`} style={{
-                      display: "block", fontSize: 12, color: "var(--txM)",
-                      textDecoration: "none", padding: "4px 12px", paddingLeft: 12 + (h.depth - 2) * 12,
-                      lineHeight: 1.4, transition: "color .12s",
-                    }}>{h.text}</a>
-                  ))}
-                </div>
+                <nav aria-label="Table of contents" style={{ borderLeft: "1px solid var(--bd)", paddingLeft: 0 }}>
+                  {filteredHeadings.map((h, i) => {
+                    const isActive = activeHeadingId === h.id;
+                    return (
+                      <a
+                        key={i}
+                        href={`#${h.id}`}
+                        onClick={(e) => scrollToHeading(e, h.id)}
+                        data-testid={`toc-link-${h.id}`}
+                        style={{
+                          display: "block", fontSize: 12,
+                          color: isActive ? "var(--ac)" : "var(--txM)",
+                          fontWeight: isActive ? 500 : 400,
+                          textDecoration: "none",
+                          padding: "4px 12px",
+                          paddingLeft: 12 + (h.depth - 2) * 12,
+                          lineHeight: 1.4,
+                          transition: "color .15s, font-weight .15s",
+                          borderLeft: isActive ? "2px solid var(--ac)" : "2px solid transparent",
+                          marginLeft: -1,
+                        }}
+                      >{h.text}</a>
+                    );
+                  })}
+                </nav>
               </aside>
             )}
           </div>

package/src/entry.tsx

@@ -20,6 +20,7 @@ import {
   CardGroup,
   Steps,
   Accordion,
+  ChangelogTimeline,
 } from "@tomehq/components";
 
 const MDX_COMPONENTS: Record<string, React.ComponentType<any>> = {
@@ -29,12 +30,14 @@ const MDX_COMPONENTS: Record<string, React.ComponentType<any>> = {
   CardGroup,
   Steps,
   Accordion,
+  ChangelogTimeline,
 };
 
 // ── CONTENT STYLES ───────────────────────────────────────
 const contentStyles = `
   @import url('https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@300;400;500;600;700&family=Cormorant+Garamond:ital,wght@0,300;0,400;0,600;0,700;1,300;1,400;1,700&family=Fira+Code:wght@400;500;600&display=swap');
 
+  .tome-content h1 { display: none; }
   .tome-content h2 { font-family: var(--font-body); font-size: 1.35em; font-weight: 600; margin-top: 2em; margin-bottom: 0.5em; display: flex; align-items: center; gap: 10px; letter-spacing: 0.01em; }
   .tome-content h2::before { content: "#"; font-family: var(--font-heading); font-size: 1.2em; font-weight: 300; font-style: italic; color: var(--ac); opacity: 0.5; }
   .tome-content h3 { font-family: var(--font-body); font-size: 1.15em; font-weight: 600; margin-top: 1.5em; margin-bottom: 0.5em; }
@@ -82,14 +85,15 @@ const contentStyles = `
 interface HtmlPage {
   isMdx: false;
   html: string;
-  frontmatter: { title: string; description?: string };
+  frontmatter: { title: string; description?: string; toc?: boolean; type?: string };
   headings: Array<{ depth: number; text: string; id: string }>;
+  changelogEntries?: Array<{ version: string; date?: string; url?: string; sections: Array<{ type: string; items: string[] }> }>;
 }
 
 interface MdxPage {
   isMdx: true;
   component: React.ComponentType<{ components?: Record<string, React.ComponentType> }>;
-  frontmatter: { title: string; description?: string };
+  frontmatter: { title: string; description?: string; toc?: boolean; type?: string };
   headings: Array<{ depth: number; text: string; id: string }>;
 }
 
@@ -113,6 +117,12 @@ async function loadPage(id: string): Promise<LoadedPage | null> {
 
     // Regular .md page — mod.default is { html, frontmatter, headings }
     if (!mod.default) return null;
+
+    // TOM-49: Changelog page type
+    if (mod.isChangelog && mod.changelogEntries) {
+      return { isMdx: false, ...mod.default, changelogEntries: mod.changelogEntries };
+    }
+
     return { isMdx: false, ...mod.default };
   } catch (err) {
     console.error(`Failed to load page: ${id}`, err);
@@ -160,6 +170,15 @@ function App() {
     description: r.frontmatter.description,
   }));
 
+  // TOM-48: Compute edit URL for current page
+  const currentRoute = routes.find((r: any) => r.id === currentPageId);
+  let editUrl: string | undefined;
+  if (config.editLink && currentRoute?.filePath) {
+    const { repo, branch = "main", dir = "" } = config.editLink;
+    const dirPrefix = dir ? `${dir.replace(/\/$/, "")}/` : "";
+    editUrl = `https://github.com/${repo}/edit/${branch}/${dirPrefix}${currentRoute.filePath}`;
+  }
+
   return (
     <>
       <style>{contentStyles}</style>
@@ -173,6 +192,10 @@ function App() {
         pageTitle={pageData?.frontmatter.title || (loading ? "Loading..." : "Not Found")}
         pageDescription={pageData?.frontmatter.description}
         headings={pageData?.headings || []}
+        tocEnabled={pageData?.frontmatter.toc !== false}
+        editUrl={editUrl}
+        lastUpdated={currentRoute?.lastUpdated}
+        changelogEntries={!pageData?.isMdx ? pageData?.changelogEntries : undefined}
         onNavigate={navigateTo}
         allPages={allPages}
         docContext={docContext}