livemark 0.25.0 → 0.27.0

package/source/routes/__root.tsx

@@ -1,72 +1,39 @@
 import { config } from "livemark:virtual"
 import { TanStackDevtools } from "@tanstack/react-devtools"
 import { ReactQueryDevtoolsPanel } from "@tanstack/react-query-devtools"
-import {
-  createRootRoute,
-  HeadContent,
-  Outlet,
-  Scripts,
-  useMatch,
-} from "@tanstack/react-router"
+import { createRootRoute, HeadContent, Outlet, Scripts } from "@tanstack/react-router"
 import { TanStackRouterDevtoolsPanel } from "@tanstack/react-router-devtools"
 import type * as React from "react"
+import { useEffect } from "react"
 import { Layout } from "../components/Layout.tsx"
+import { Root } from "../components/Root.tsx"
 import { DefaultCatchBoundary } from "../components/DefaultCatchBoundary.tsx"
 import { NotFound } from "../components/NotFound.tsx"
+import { useHydrated } from "../hooks/hydrated.ts"
 import { Toaster } from "../elements/sonner.tsx"
-import { faviconType } from "../helpers/favicon.ts"
-import { prefixUrl } from "../helpers/prefix-url.ts"
+import { buildRootHead } from "../helpers/head.ts"
+import { startTheme } from "../helpers/theme.ts"
+import { customizeHead } from "../head.ts"
 import defaultFavicon from "../assets/logo.svg"
 import generalCss from "../styles/general.css?url"
 import markdownCss from "../styles/markdown.css?url"
 
 export const Route = createRootRoute({
-  head: () => {
-    const favicon = prefixUrl(
-      config.favicon ?? config.logo ?? defaultFavicon,
-      config.base,
-    )
-    const feedLinks = config.site
-      ? (config.sections ?? [])
-          .filter(s => s.type === "blog")
-          .map(s => ({
-            rel: "alternate",
-            type: "application/rss+xml",
-            title: `${s.siteTitle ?? s.title} RSS Feed`,
-            href: prefixUrl(`${s.prefix}rss.xml`, config.base),
-          }))
-      : []
-    return {
-      meta: [
-        { charSet: "utf-8" },
-        { title: config.title },
-        { name: "description", content: config.description },
-        { property: "og:title", content: config.title },
-        {
-          property: "og:description",
-          content: config.description,
-        },
-        { property: "og:site_name", content: config.title },
-        { property: "og:type", content: "website" },
-        {
-          name: "viewport",
-          content: "width=device-width, initial-scale=1",
-        },
-      ],
-      links: [
-        { rel: "icon", href: favicon, type: faviconType(favicon) },
-        { rel: "shortcut icon", href: favicon, type: faviconType(favicon) },
-        { rel: "stylesheet", href: generalCss },
-        { rel: "stylesheet", href: markdownCss },
-        ...feedLinks,
-      ],
-    }
-  },
-  notFoundComponent: () => <NotFound />,
+  head: () =>
+    customizeHead(
+      buildRootHead({ config, defaultFavicon, stylesheets: [generalCss, markdownCss] }),
+    ),
+  notFoundComponent: () => (
+    <Layout>
+      <NotFound />
+    </Layout>
+  ),
   errorComponent: props => {
     return (
       <Document>
-        <DefaultCatchBoundary {...props} />
+        <Layout>
+          <DefaultCatchBoundary {...props} />
+        </Layout>
       </Document>
     )
   },
@@ -80,32 +47,45 @@ export const Route = createRootRoute({
 })
 
 function Document(props: { children: React.ReactNode }) {
-  const articleRoute = useMatch({ from: "/$", shouldThrow: false })
-  const withSidebar = articleRoute?.loaderData?.sidebar
+  // Off the raw URL, not the router's parsed search: a route whose validateSearch
+  // does not declare this key strips it.
+  const hydrated = useHydrated()
+  const devtools = hydrated && window.location.search.includes("tanstack-devtools")
+
+  useEffect(startTheme, [])
 
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
       <head>
         <HeadContent />
       </head>
       <body>
-        <Layout withSidebar={withSidebar}>{props.children}</Layout>
+        <Root>{props.children}</Root>
         <Toaster position="top-center" />
-        <TanStackDevtools
-          config={{ hideUntilHover: true, position: "bottom-left" }}
-          plugins={[
-            {
-              name: "TanStack Query",
-              render: <ReactQueryDevtoolsPanel />,
-              defaultOpen: true,
-            },
-            {
-              name: "TanStack Router",
-              render: <TanStackRouterDevtoolsPanel />,
-              defaultOpen: false,
-            },
-          ]}
-        />
+        {/* Gated here, not by the devtools' own `requireUrlFlag`: that setting seeds
+            localStorage on a browser's first run and is read from there afterwards,
+            so a browser that loaded the site before it was set keeps the trigger. */}
+        {/* The build strips the devtools element alone; the fragment keeps
+            `devtools && (<></>)` valid instead of the syntax error `&& ()`. */}
+        {devtools && (
+          <>
+            <TanStackDevtools
+              config={{ requireUrlFlag: true, position: "bottom-left" }}
+              plugins={[
+                {
+                  name: "TanStack Query",
+                  render: <ReactQueryDevtoolsPanel />,
+                  defaultOpen: true,
+                },
+                {
+                  name: "TanStack Router",
+                  render: <TanStackRouterDevtoolsPanel />,
+                  defaultOpen: false,
+                },
+              ]}
+            />
+          </>
+        )}
         <Scripts />
       </body>
     </html>

package/source/settings.ts

@@ -14,6 +14,7 @@ export const ESCAPABLE_FILES: readonly string[] = [
   "client.tsx",
   "server.ts",
   "router.tsx",
+  "head.ts",
 ]
 
 /** Glob patterns auto-excluded from content scanning when the consumer's

package/source/styles/general.css

@@ -1,5 +1,6 @@
 @import "tailwindcss";
 @import "tw-animate-css";
+@import "./shape.css";
 @plugin "@tailwindcss/typography";
 
 @custom-variant dark (&:is(.dark *));
@@ -13,14 +14,28 @@
   --popover-foreground: oklch(0.145 0 0);
   --primary: oklch(54.6% 0.245 262.881);
   --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(89.4% 0.057 293.283);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
+  --secondary: oklch(54.1% 0.281 293.009);
+  --secondary-foreground: oklch(0.985 0 0);
+  --banner: oklch(89.4% 0.057 293.283);
+  --banner-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.985 0 0);
   --muted-foreground: oklch(0.5 0 0);
   --accent: oklch(0.97 0 0);
   --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --positive: oklch(0.648 0.2 131.684);
+  --positive-foreground: oklch(0.205 0 0);
+  --positive-tint: oklch(96.7% 0.067 122.328);
+  --positive-tint-foreground: oklch(53.2% 0.157 131.589);
+  --warning: oklch(79.5% 0.184 86.047);
+  --warning-foreground: oklch(0.205 0 0);
+  --warning-tint: oklch(97.3% 0.071 103.193);
+  --warning-tint-foreground: oklch(47.6% 0.114 61.907);
+  --highlight: oklch(90.5% 0.182 98.111);
+  --highlight-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.55 0.2 25);
+  --destructive-foreground: oklch(0.985 0 0);
+  --destructive-tint: oklch(93.6% 0.032 17.717);
+  --destructive-tint-foreground: oklch(50.5% 0.213 27.518);
   --border: oklch(0.922 0 0);
   --input: oklch(0.922 0 0);
   --ring: oklch(0.708 0 0);
@@ -30,7 +45,7 @@
   --chart-4: oklch(0.828 0.189 84.429);
   --chart-5: oklch(0.769 0.188 70.08);
   --radius: 0.625rem;
-  --sidebar: oklch(0.985 0 0);
+  --sidebar: var(--muted);
   --sidebar-foreground: oklch(0.145 0 0);
   --sidebar-primary: oklch(0.205 0 0);
   --sidebar-primary-foreground: oklch(0.985 0 0);
@@ -49,14 +64,28 @@
   --popover-foreground: oklch(0.985 0 0);
   --primary: oklch(0.623 0.214 259.815);
   --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.269 0 0);
+  --secondary: oklch(60.6% 0.25 292.717);
   --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
+  --banner: oklch(0.269 0 0);
+  --banner-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.205 0 0);
   --muted-foreground: oklch(0.708 0 0);
   --accent: oklch(0.269 0 0);
   --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.396 0.141 25.723);
-  --destructive-foreground: oklch(0.637 0.237 25.331);
+  --positive: oklch(0.841 0.238 128.85);
+  --positive-foreground: oklch(0.205 0 0);
+  --positive-tint: oklch(27.4% 0.072 132.109);
+  --positive-tint-foreground: oklch(84.1% 0.238 128.85);
+  --warning: oklch(85.2% 0.199 91.936);
+  --warning-foreground: oklch(0.22 0.04 70);
+  --warning-tint: oklch(28.6% 0.066 53.813);
+  --warning-tint-foreground: oklch(85.2% 0.199 91.936);
+  --highlight: oklch(55.4% 0.135 66.442);
+  --highlight-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.7 0.17 25);
+  --destructive-foreground: oklch(0.2 0.03 25);
+  --destructive-tint: oklch(25.8% 0.092 26.042);
+  --destructive-tint-foreground: oklch(70.4% 0.191 22.216);
   --border: oklch(0.269 0 0);
   --input: oklch(0.269 0 0);
   --ring: oklch(0.439 0 0);
@@ -65,7 +94,7 @@
   --chart-3: oklch(0.769 0.188 70.08);
   --chart-4: oklch(0.627 0.265 303.9);
   --chart-5: oklch(0.645 0.246 16.439);
-  --sidebar: oklch(0.205 0 0);
+  --sidebar: var(--muted);
   --sidebar-foreground: oklch(0.985 0 0);
   --sidebar-primary: oklch(0.488 0.243 264.376);
   --sidebar-primary-foreground: oklch(0.985 0 0);
@@ -86,12 +115,26 @@
   --color-primary-foreground: var(--primary-foreground);
   --color-secondary: var(--secondary);
   --color-secondary-foreground: var(--secondary-foreground);
+  --color-banner: var(--banner);
+  --color-banner-foreground: var(--banner-foreground);
   --color-muted: var(--muted);
   --color-muted-foreground: var(--muted-foreground);
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
+  --color-positive: var(--positive);
+  --color-positive-foreground: var(--positive-foreground);
+  --color-positive-tint: var(--positive-tint);
+  --color-positive-tint-foreground: var(--positive-tint-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-warning-tint: var(--warning-tint);
+  --color-warning-tint-foreground: var(--warning-tint-foreground);
+  --color-highlight: var(--highlight);
+  --color-highlight-foreground: var(--highlight-foreground);
   --color-destructive: var(--destructive);
   --color-destructive-foreground: var(--destructive-foreground);
+  --color-destructive-tint: var(--destructive-tint);
+  --color-destructive-tint-foreground: var(--destructive-tint-foreground);
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
@@ -122,6 +165,11 @@
     @apply bg-background text-foreground;
   }
 
+  ::highlight(search-match) {
+    background-color: var(--highlight);
+    color: var(--highlight-foreground);
+  }
+
   html {
     scroll-behavior: smooth;
     scrollbar-color: #ddd transparent;

package/source/styles/markdown.css

@@ -2,6 +2,12 @@
 @reference "./general.css";
 
 @layer components {
+  /* A bare URL or long inline code is one unbreakable word that widens the whole
+     page on a phone, so it scrolls sideways. */
+  .prose {
+    overflow-wrap: break-word;
+  }
+
   .prose :is(h1, h2, h3, h4, h5, h6) {
     @apply scroll-mt-28 md:scroll-mt-20;
   }
@@ -43,29 +49,29 @@
   }
 
   .prose pre code .line[data-diff="add"] {
-    @apply bg-green-500/15;
+    @apply bg-positive/15;
   }
 
   .prose pre code .line[data-diff="remove"] {
-    @apply bg-red-500/15;
+    @apply bg-destructive/15;
   }
 
   .prose pre code .line[data-diff="add"]::before {
     content: "+";
-    @apply text-green-600 absolute left-1;
+    @apply text-positive-tint-foreground absolute left-1;
   }
 
   .prose pre code .line[data-diff="remove"]::before {
     content: "-";
-    @apply text-red-600 absolute left-1;
+    @apply text-destructive-tint-foreground absolute left-1;
   }
 
   .prose pre code .line[data-line-status="error"] {
-    @apply bg-red-500/15;
+    @apply bg-destructive/15;
   }
 
   .prose pre code .line[data-line-status="warning"] {
-    @apply bg-yellow-500/15;
+    @apply bg-warning/15;
   }
 
   .prose pre[data-has-focus] code .line:not([data-focus]) {
@@ -100,7 +106,7 @@
   }
 
   .prose pre code .twoslash-error-line {
-    @apply bg-red-500/10;
+    @apply bg-destructive/10;
   }
 
   .prose pre code .twoslash-tag-line {

package/source/styles/shape.css

@@ -0,0 +1,14 @@
+/* Elements name these, never a raw `rounded-md`: controls are pills, rows and cards 1rem,
+   panels 1.5rem. Pills ignore `--radius`; only the `sm`…`xl` scale follows it. */
+@theme inline {
+  --radius-control: 9999px;
+  --radius-control-sm: 9999px;
+  --radius-control-xs: 9999px;
+  --radius-control-inset: 9999px;
+  --radius-textarea: 1rem;
+  --radius-row: 1rem;
+  --radius-card: 1rem;
+  --radius-panel: 1.5rem;
+  --radius-menu: 1rem;
+  --radius-menu-item: calc(1rem - 4px);
+}

package/source/vite.config.ts

@@ -6,6 +6,7 @@ import react from "@vitejs/plugin-react"
 import { defineConfig } from "vite"
 import svgr from "vite-plugin-svgr"
 import { loadConfig } from "./actions/config/load.ts"
+import { agents } from "./plugins/vite-agents.ts"
 import { livemark } from "./plugins/vite-livemark.ts"
 import { robots } from "./plugins/vite-robots.ts"
 
@@ -28,6 +29,7 @@ export default defineConfig({
   plugins: [
     livemark({ config }),
     robots({ config }),
+    agents({ config }),
     devtools(),
     tailwind(),
     contentCollections({ configPath: "content-collections.ts" }),

package/.agents/skills/change-review/SKILL.md

@@ -1,47 +0,0 @@
----
-name: change-review
-description: Review a pull request for correctness, security and repo conventions, posting findings as inline comments. Invoked by the review workflow and by a person; never fires on its own.
-disable-model-invocation: true
----
-
-# Review a pull request
-
-Read the diff, judge it, post findings as inline comments. Be useful, not thorough-looking:
-a review that flags twenty things teaches nothing, and the twenty-first — the real one — is lost
-in it.
-
-## What to look for
-
-**Correctness**
-
-- Logic that is wrong for an input the change makes reachable, not merely unusual.
-- Error handling that swallows a failure or reports success on a partial write.
-- Concurrency: two requests, two sessions, a retry, a replay.
-- Performance where the change makes it structurally worse (a query in a loop, an unbounded
-  scan), not where it is merely not optimal.
-
-**Security — OWASP-shaped, but reported only when reachable**
-
-- Injection (SQL and otherwise), XSS, SSRF, XXE, unsafe deserialisation.
-- Broken authentication or access control: a route that skips the permission it needs, a scope
-  resolved from user input, an id trusted because it came from the client.
-- Sensitive data exposure: secrets in code or logs, PII widening, a credential recoverable from
-  the database.
-- Insecure cryptography, race conditions and TOCTOU, missing logging on a security-relevant
-  action.
-
-**This repo's own conventions** — these are where a generic reviewer is blind, and they matter
-more than the generic checklist. Read `AGENTS.md` and the sibling skills before judging: a
-change that violates a documented invariant is a finding even when the code is otherwise
-correct.
-
-## How to report
-
-Rate each finding **CRITICAL / HIGH / MEDIUM / LOW**, and say what input or sequence produces
-the failure. A finding that cannot name the case that breaks is a hunch: either verify it or
-leave it out.
-
-Post specific issues as inline comments on the lines they concern. Keep the summary short.
-Silence on the parts that are fine is not laziness — it is what makes the flagged parts legible.
-
-If the change is good, say so briefly and stop. Do not manufacture findings to justify the run.

package/.agents/skills/livemark-customization/SKILL.md

@@ -1,118 +0,0 @@
----
-name: livemark-customization
-description: Use when overriding Livemark's built-in UI or adding custom routes — drop same-named files under .livemark/{components,elements,styles} to shadow defaults, author .livemark/routes/*.tsx for new pages, or copy defaults with the `livemark escape` command.
----
-
-# Livemark Customization
-
-Guidance for customizing the UI layer of a Livemark project beyond what `livemark.config.ts` exposes.
-
-## When to use this skill
-
-Invoke when the user asks to:
-
-- Change a built-in component's layout or markup (Footer, Sidebar, Banner, …).
-- Restyle a shared primitive (buttons, inputs, cards, sheet, …).
-- Rebrand via CSS tokens (colors, radii, typography).
-- Add a brand-new page that isn't a Markdown article (landing hero, pricing page, about page).
-- Replace Livemark's default landing page with a custom React component.
-- Serve a custom `favicon.svg`, `robots.txt`, `og-image.png`, or other static asset.
-
-## Three overlapping mechanisms
-
-| Goal                              | Mechanism                                             |
-| --------------------------------- | ----------------------------------------------------- |
-| Replace a default component/style | Drop a file at `.livemark/components/<Name>.tsx` etc. |
-| Add a new page at an exact URL    | Create `.livemark/routes/<path>.tsx`                  |
-| Serve a static asset at `/<path>` | Put the file in `.livemark/public/<path>`             |
-
-None require config changes. The Vite plugin (`website/plugins/vite-livemark.ts`) watches `.livemark/**` and hot-reloads.
-
-## Discovering what's overridable
-
-Run the `escape` command. No arg lists every overridable file:
-
-```bash
-livemark escape
-```
-
-Output is a flat `<subdir>/<file>` list across `components/`, `elements/`, and `styles/`. With an argument, the command copies the default into `.livemark/`:
-
-```bash
-livemark escape components/Footer.tsx   # → .livemark/components/Footer.tsx
-livemark escape elements/button.tsx     # → .livemark/elements/button.tsx
-livemark escape styles/general.css      # → .livemark/styles/general.css
-```
-
-The command refuses to overwrite an existing override. Delete the override first if you want a fresh start.
-
-## Typical workflow: override a component
-
-1. `livemark escape components/Footer.tsx` — copy the default.
-2. Edit `.livemark/components/Footer.tsx`. All the site's Footer renders shift to the new file on save.
-3. Inside the override, import other Livemark modules from the `livemark/<subdir>/*` subpath exports:
-   ```tsx
-   import { cn } from "livemark/helpers/style"
-   import { Button } from "livemark/elements/button"
-   ```
-
-## Typical workflow: rebrand
-
-1. `livemark escape styles/general.css`.
-2. Edit the `:root` and `.dark` blocks in `.livemark/styles/general.css`:
-   - `--primary` — brand accent (Tailwind-flavoured oklch values work).
-   - `--radius` — corner roundness base.
-   - Sidebar / chart tokens if you want deeper tweaks.
-3. Save — the dev server applies immediately.
-
-Whole-site contrast is audited: light mode targets blue-600, dark mode targets blue-500. Keep new token values AA-compliant on both backgrounds (≥4.5:1 for text).
-
-## Typical workflow: add a page
-
-Custom routes use [TanStack Router](https://tanstack.com/router). Minimal example:
-
-```tsx title=".livemark/routes/about.tsx"
-import { createFileRoute } from "@tanstack/react-router"
-
-export const Route = createFileRoute("/about")({
-  component: () => (
-    <main className="mx-auto max-w-3xl px-6 py-16 prose">
-      <h1>About</h1>
-      <p>Hello.</p>
-    </main>
-  ),
-})
-```
-
-Filename maps to URL path: `.livemark/routes/pricing.tsx` → `/pricing/`. Nested paths work via nested folders.
-
-An `index.tsx` in `.livemark/routes/` **replaces** Livemark's default landing at `/`.
-
-Custom routes win over the Markdown catch-all at exact URLs. Don't create a route that collides with an article URL unless you intend to hide the article.
-
-## Rules of thumb
-
-1. **Don't fork the repo** for routine customization. Use `.livemark/` first — it reliably survives Livemark upgrades.
-2. **Same filename, same path under `.livemark/`.** The override plugin is case-sensitive and mirrors the subdirectory structure exactly.
-3. **Override files are full replacements**, not diffs. Copy the default first (via `escape`), then edit.
-4. **Import Livemark internals via `livemark/*`**, not via relative paths — the plugin routes those through the override resolver, so chained overrides (e.g., your Layout using your Sidebar) compose correctly.
-5. **Static files belong in `.livemark/public/`**, which Vite exposes at the site root.
-
-## What's NOT overridable
-
-- `actions/`, `commands/`, `program.ts` — server/CLI code. Fork upstream if you need to change these.
-- `livemark.config.ts` schema — fixed.
-- Content-collections transform pipeline. Customize markdown via remark/rehype plugins in a fork (or PR upstream).
-
-## Verification
-
-- `pnpm type` — confirms overrides typecheck.
-- `pnpm docs:build` — smoke-test the override lands in the bundle.
-- Browser: load an article page with the dev server; custom Footer/Sidebar/etc. should render without a full reload.
-
-## References
-
-- Narrative docs: `docs/customization/file-overrides.md`, `docs/customization/custom-routes.md`.
-- Plugin implementation: `website/plugins/vite-livemark.ts`.
-- Escape command: `commands/escape.ts`.
-- Subpath exports: `package.json` `exports` block.