hazo_blog 0.3.0 → 0.4.0

package/CHANGE_LOG.md

@@ -3,6 +3,64 @@
 All notable changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 0.4.0 — 2026-07-14
+
+**`validatePost()` — pre-publish content-quality gate (new, `hazo_blog/lib`)**
+
+Encodes the SEO lessons a stale Bing report surfaced late on a consumer site, so they're caught
+before a post goes live rather than months after. `validatePost(input, opts?)` returns
+`{ ok, errors, warnings, issues, wordCount }`:
+
+- **Blocking errors:** thin content (`< minWords`, default 300), missing meta description, and a
+  second page heading in the body — an `# ` markdown H1 or a `<h1>` (the post title is already the
+  page H1). Code samples in fenced blocks are ignored so a `#` comment doesn't false-positive.
+- **Advisory warnings:** meta-description length outside 150–160, composed SEO title over
+  `titleLengthLimit` (default 60, *including* the `titleSuffix` — same suffix-aware fix shipped in
+  hazo_seo 0.5.0), missing excerpt, missing FAQ, and no subheadings.
+
+Consumers wire this into their create/update/publish path (e.g. gotimer's `PATCH /api/blog/manage`)
+and reject on `!result.ok`. Pure + server-safe; reuses the existing `mdxToPlainText`/`countWords`/
+`extractToc` helpers, no new dependencies. Reachable from the main `hazo_blog` entry and the
+`hazo_blog/lib` subpath.
+
+**`hazo_blog/lib` subpath export (new)** — the `./lib` subpath (advertised in the README for the
+text utilities but previously absent from `package.json` `exports`) is now a real entry, so
+`sanitizeMdx`/`mdxToPlainText`/`slugify`/`extractToc`/`validatePost` etc. import directly from
+`hazo_blog/lib` as documented (they were only reachable via the main `hazo_blog` entry before).
+
+**Internal (test tooling)**
+- Fixed `repository.integration.test.ts` failing to run: the CJS-transformed `hazo_connect` adapter
+  graph does `require()` of ESM-only hazo packages (`hazo_core`, and transitively
+  `hazo_secure/crypto`), which jest's vm-modules loader can't `require()` on Node < 24.9 ("Must use
+  import to load ES Module"). Fix: plain-**CJS** mocks — `__mocks__/hazo_core.cjs` (functional error
+  classes + `safeJsonParse` etc.) and `__mocks__/hazo_secure_crypto.cjs` (passthrough field-crypto
+  stub) — mapped via `moduleNameMapper`, plus a `transformIgnorePatterns` exception for
+  `hazo_connect`/`hazo_core`. `.cjs` isn't matched by the `tsx` transform, so it loads raw as
+  CommonJS and the real `hazo_connect` adapter resolves against it. The integration test now runs
+  against real `hazo_connect` + real SQLite on the Node 22 the workspace pins for better-sqlite3.
+  (An earlier `.ts` ESM mock silently did **not** fix this on Node 22 — a CJS `require()` still can't
+  load an ESM `.ts`.)
+
+## 0.3.3 — 2026-07-06
+
+**`sanitizeMdx` hardened against raw WordPress HTML**
+
+Extends the sanitizer beyond HTML comments to cover three more parser-breaking patterns commonly
+found in imported WordPress post bodies. All run on the code-masked string, so fenced/inline code
+spans stay byte-for-byte untouched, and the transform remains idempotent.
+
+- **`<script>` / `<style>` blocks** — dropped entirely. Their bodies (JSON-LD, inline CSS) contain
+  raw `{ }` that MDX parses as a JS expression, throwing "Could not parse expression with acorn".
+  They carry no visible prose, so removing them never changes rendered output.
+- **HTML void elements** (`<img>`, `<br>`, `<hr>`, `<input>`, …) — normalized to self-closing
+  (`<img src="x" />`). Un-self-closed voids throw "Expected a closing tag" in MDX/JSX.
+- **String-valued `style="..."` / `style='...'` attributes** — dropped. Valid HTML but invalid JSX
+  (React requires the object form `style={{...}}`), else "The style prop expects a mapping … not a
+  string" at render. The JSX object form is deliberately left untouched.
+
+No API change — same `sanitizeMdx(mdx: string): string` signature. **Consumer note:** `^0.3.0`
+resolves to `0.3.3` (caret allows patch/minor within the same pre-1.0 minor).
+
 ## 0.3.0 — 2026-06-12
 
 **Build resilience: sanitizer + async try/catch guard against malformed MDX**

package/README.md

@@ -208,9 +208,14 @@ const nextConfig = {
 
 `BlogContent` (≥ 0.3.0) is an async server component that catches MDX compilation errors with
 `try/catch`, so a single malformed post renders a graceful fallback instead of failing the whole
-`next build`. It also pre-sanitizes content with `sanitizeMdx` (converts HTML comments → MDX
-comments, escapes stray `<!`) before passing it to the compiler. The sanitizer is also available
-as a standalone export from `hazo_blog/lib` for custom rendering pipelines.
+`next build`. It also pre-sanitizes content with `sanitizeMdx` before passing it to the compiler.
+The sanitizer fixes the common ways raw WordPress HTML trips the MDX/acorn parser: converts HTML
+comments → MDX comments (and escapes stray `<!`), strips `<script>`/`<style>` blocks whose bodies
+break parsing, self-closes HTML void elements (`<img>`, `<br>`, …), and drops string-valued
+`style="..."` attributes (invalid JSX; the object form `style={{...}}` is left untouched). Fenced
+and inline code spans are left byte-for-byte untouched, and the transform is idempotent. The
+sanitizer is also available as a standalone export from `hazo_blog/lib` for custom rendering
+pipelines.
 
 ## Exports
 
@@ -219,7 +224,7 @@ as a standalone export from `hazo_blog/lib` for custom rendering pipelines.
 | `hazo_blog` | server: `createBlogService`, `createBlogRepository`, SEO builders, **route-handler factories** (React-free), types |
 | `hazo_blog/client` | client components: `PostCard`, `PostHero`, `AuthorBio`, `FaqSection`, `TableOfContents`, `RelatedPosts`, `BlogSearch`, `PostForm`, MDX components, `trackBlogEvent` |
 | `hazo_blog/next` | sealed page factories: public (`createBlogIndexPage`, `createBlogPostPage`, `createBlogTagPage`) + admin (`createBlogAdminListPage`, `createBlogAdminNewPage`, `createBlogAdminEditPage`) + `BlogContent` + `MdxErrorBoundary` |
-| `hazo_blog/lib` | pure text utilities: `sanitizeMdx`, `mdxToPlainText`, `buildExcerpt`, `slugify`, `calculateReadingTime`, `extractToc` |
+| `hazo_blog/lib` | pure text utilities: `sanitizeMdx`, `mdxToPlainText`, `buildExcerpt`, `slugify`, `calculateReadingTime`, `extractToc` + `validatePost` (pre-publish content-quality gate) |
 | `hazo_blog/seo` | `buildBlogPostingJsonLd`, `buildBreadcrumbJsonLd`, `buildFaqJsonLd`, `getBlogSitemapEntries`, `getBlogRobotsRules`, `getBlogRssXml` |
 | `hazo_blog/config` | `BlogConfig` types + `resolveConfig` |
 
@@ -239,6 +244,28 @@ searchApiPath: "/api/blog/search", // default
 See `SETUP_CHECKLIST.md` for a step-by-step integration list. A runnable demo
 lives in `test-app/`.
 
+## Pre-publish validation
+
+`validatePost` is a pure, server-safe content-quality gate. Wire it into your
+create/update/publish path and reject on `!result.ok`:
+
+```ts
+import { validatePost } from "hazo_blog"; // also on the `hazo_blog/lib` subpath
+
+const result = validatePost(
+  { title, content, meta_description, excerpt, faq },
+  { titleSuffix: " | GoTimer" }, // options are optional
+);
+
+if (!result.ok) {
+  return fail(result.errors); // blocking: thin content, missing meta description, a second <h1>
+}
+logWarnings(result.warnings);   // advisory: meta length, over-long title, missing excerpt/FAQ, no subheadings
+```
+
+Options: `minWords` (default 300), `titleLengthLimit` (default 60, suffix-aware),
+`titleSuffix`, `descriptionRange` (default `[150, 160]`).
+
 ## License
 
 MIT

package/SETUP_CHECKLIST.md

@@ -36,6 +36,7 @@ for full code samples.
 - [ ] `app/api/blog/feed/route.ts` → `createBlogFeedRoute`
 - [ ] `app/api/admin/blog/route.ts` + `[id]/route.ts` → `createBlogAdminRoutes`
 - [ ] (optional) `app/api/blog/manage/route.ts` → `createBlogManageRoutes`
+- [ ] (optional) call `validatePost(input, opts)` in your create/update/publish path and reject on `!result.ok` (pre-publish content-quality gate)
 - [ ] Merge `getBlogSitemapEntries()` into root `app/sitemap.ts` and `getBlogRobotsRules()` into `app/robots.ts`
 
 ### Admin UI pages (sealed, recommended)

package/dist/lib/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./text.js";
+export * from "./validate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/lib/index.js

@@ -1,2 +1,3 @@
 // hazo_blog/src/lib/index.ts — core library exports (server-safe).
 export * from "./text.js";
+export * from "./validate.js";

package/dist/lib/text.d.ts

@@ -23,13 +23,33 @@ export interface TocHeading {
 }
 export declare function extractToc(mdx: string): TocHeading[];
 /**
- * Make raw MDX safe to compile. MDX has no HTML comments — a `<!--` in prose
- * makes the parser expect a JSX tag name after `<` and throw "Unexpected
- * character `!` before name", crashing the whole Next build at prerender.
- * Convert HTML comments to MDX comments ({/*…*\/}, equally non-rendering) and
- * escape any stray `<!`, while leaving fenced/inline code untouched (it is
- * literal in MDX, never errors, and may legitimately show an HTML comment in a
- * sample). Idempotent: after one pass no literal `<!` survives in prose.
+ * Make raw MDX safe to compile. Raw WordPress HTML stored as post content
+ * trips the MDX/acorn parser in a handful of unambiguously-fixable ways:
+ *
+ * 1. HTML comments — MDX has none, so a bare `<!--` makes the parser expect
+ *    a JSX tag name after `<` and throw "Unexpected character `!` before
+ *    name". Converted to MDX comments ({/*…*\/}, equally non-rendering).
+ * 2. `<script>`/`<style>` blocks — their bodies (JSON-LD, inline CSS)
+ *    contain raw `{ }` that MDX parses as a JS expression, throwing "Could
+ *    not parse expression with acorn". They carry no visible prose (SEO
+ *    metadata / global CSS handle those concerns elsewhere), so dropping the
+ *    whole block is safe and never changes rendered output.
+ * 3. HTML void elements (`<img>`, `<br>`, …) written un-self-closed — MDX/JSX
+ *    requires them self-closed; `<img src="x">` alone throws "Expected a
+ *    closing tag". Normalized to `<img src="x" />` regardless of whether a
+ *    stray slash was already present.
+ * 4. String-valued `style="..."` / `style='...'` attributes — valid HTML but
+ *    invalid JSX/MDX (React requires `style={{...}}`, an object, never a
+ *    string); left alone, they compile fine but throw "The style prop
+ *    expects a mapping ... not a string" at render time. Always broken, so
+ *    the attribute is dropped outright. Only the quoted-string form is
+ *    matched (`style="`/`style='`) — the legitimate JSX object form
+ *    (`style={{...}}`) never matches and is left untouched.
+ *
+ * All four run on the code-MASKED string, so fenced/inline code spans are
+ * left byte-for-byte untouched (they are literal in MDX, never error, and
+ * may legitimately show a comment, a `<script>` sample, or a bare `<img>` in
+ * a code sample). Idempotent: running this twice yields the same output.
  */
 export declare function sanitizeMdx(mdx: string): string;
 //# sourceMappingURL=text.d.ts.map

package/dist/lib/text.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/lib/text.ts"],"names":[],"mappings":"AAGA,6CAA6C;AAC7C,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS7C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAalD;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,SAAM,GAAG,MAAM,CAG9E;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,MAAM,CAMhE;AAED,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAYpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkB/C"}
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/lib/text.ts"],"names":[],"mappings":"AAGA,6CAA6C;AAC7C,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS7C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAalD;AAED,0CAA0C;AAC1C,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,SAAM,GAAG,MAAM,CAG9E;AAED,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,MAAM,CAMhE;AAED,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAYpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA+B/C"}

package/dist/lib/text.js

@@ -68,13 +68,33 @@ export function extractToc(mdx) {
     return headings;
 }
 /**
- * Make raw MDX safe to compile. MDX has no HTML comments — a `<!--` in prose
- * makes the parser expect a JSX tag name after `<` and throw "Unexpected
- * character `!` before name", crashing the whole Next build at prerender.
- * Convert HTML comments to MDX comments ({/*…*\/}, equally non-rendering) and
- * escape any stray `<!`, while leaving fenced/inline code untouched (it is
- * literal in MDX, never errors, and may legitimately show an HTML comment in a
- * sample). Idempotent: after one pass no literal `<!` survives in prose.
+ * Make raw MDX safe to compile. Raw WordPress HTML stored as post content
+ * trips the MDX/acorn parser in a handful of unambiguously-fixable ways:
+ *
+ * 1. HTML comments — MDX has none, so a bare `<!--` makes the parser expect
+ *    a JSX tag name after `<` and throw "Unexpected character `!` before
+ *    name". Converted to MDX comments ({/*…*\/}, equally non-rendering).
+ * 2. `<script>`/`<style>` blocks — their bodies (JSON-LD, inline CSS)
+ *    contain raw `{ }` that MDX parses as a JS expression, throwing "Could
+ *    not parse expression with acorn". They carry no visible prose (SEO
+ *    metadata / global CSS handle those concerns elsewhere), so dropping the
+ *    whole block is safe and never changes rendered output.
+ * 3. HTML void elements (`<img>`, `<br>`, …) written un-self-closed — MDX/JSX
+ *    requires them self-closed; `<img src="x">` alone throws "Expected a
+ *    closing tag". Normalized to `<img src="x" />` regardless of whether a
+ *    stray slash was already present.
+ * 4. String-valued `style="..."` / `style='...'` attributes — valid HTML but
+ *    invalid JSX/MDX (React requires `style={{...}}`, an object, never a
+ *    string); left alone, they compile fine but throw "The style prop
+ *    expects a mapping ... not a string" at render time. Always broken, so
+ *    the attribute is dropped outright. Only the quoted-string form is
+ *    matched (`style="`/`style='`) — the legitimate JSX object form
+ *    (`style={{...}}`) never matches and is left untouched.
+ *
+ * All four run on the code-MASKED string, so fenced/inline code spans are
+ * left byte-for-byte untouched (they are literal in MDX, never error, and
+ * may legitimately show a comment, a `<script>` sample, or a bare `<img>` in
+ * a code sample). Idempotent: running this twice yields the same output.
  */
 export function sanitizeMdx(mdx) {
     const stash = [];
@@ -90,8 +110,18 @@ export function sanitizeMdx(mdx) {
         .replace(/~~~[\s\S]*?~~~/g, keep)
         .replace(/`[^`\n]*`/g, keep);
     masked = masked
+        // Strip <script>/<style> blocks entirely — see rationale above.
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "")
         // Comment body: neutralize any `*/` so it can't close the MDX comment early.
         .replace(/<!--([\s\S]*?)-->/g, (_, body) => `{/*${body.replace(/\*\//g, "* /")}*/}`)
-        .replace(/<!(?!--)/g, "&lt;!");
+        .replace(/<!(?!--)/g, "&lt;!")
+        // Strip string-valued `style="..."` attributes — see rationale above.
+        // Deliberately does NOT match `style={` (the valid JSX object form).
+        .replace(/\sstyle=("[^"]*"|'[^']*')/gi, "")
+        // Self-close HTML void elements — see rationale above. Emits `/>`
+        // whether or not a slash was already present, so a second pass is a
+        // no-op (idempotent).
+        .replace(/<(img|br|hr|input|source|meta|link|col|area|base|embed|param|track|wbr)\b([^>]*?)\s*\/?>/gi, "<$1$2 />");
     return masked.replace(/(\d+)/g, (_, i) => stash[Number(i)]);
 }

package/dist/lib/validate.d.ts

@@ -0,0 +1,48 @@
+import type { FaqItem, PostStatus } from '../types/index.js';
+export interface ValidatePostInput {
+    title: string;
+    /** Raw MDX body. */
+    content: string;
+    meta_title?: string;
+    meta_description?: string;
+    excerpt?: string | null;
+    faq?: FaqItem[];
+    status?: PostStatus;
+}
+export interface PostValidationOptions {
+    /** Minimum body word count before content is flagged as thin. Default 300. */
+    minWords?: number;
+    /**
+     * Max length of the *composed* SEO title (title + `titleSuffix`) before a
+     * warning. Default 60 (Google's practical display limit).
+     */
+    titleLengthLimit?: number;
+    /** Brand/site suffix appended to titles at render time, e.g. " | GoTimer". Default "". */
+    titleSuffix?: string;
+    /** [min, max] ideal meta-description length. Default [150, 160]. */
+    descriptionRange?: [number, number];
+}
+export type ValidationSeverity = 'error' | 'warning';
+export interface ValidationIssue {
+    code: string;
+    severity: ValidationSeverity;
+    message: string;
+}
+export interface PostValidationResult {
+    /** True when there are no `error`-severity issues. */
+    ok: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+    /** All issues (errors + warnings), in the order produced. */
+    issues: ValidationIssue[];
+    /** Body word count (plain text), exposed for logging/telemetry. */
+    wordCount: number;
+}
+/**
+ * Validate a post before publishing. Blocking issues land in `errors`
+ * (thin content, missing meta description, a second page <h1> in the body);
+ * advisory issues land in `warnings` (meta-description length, over-long title,
+ * missing excerpt/FAQ, no subheadings). `ok` is true iff there are no errors.
+ */
+export declare function validatePost(input: ValidatePostInput, opts?: PostValidationOptions): PostValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/lib/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/lib/validate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG7D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,6DAA6D;IAC7D,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAOD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,IAAI,GAAE,qBAA0B,GAC/B,oBAAoB,CAyDtB"}

package/dist/lib/validate.js

@@ -0,0 +1,68 @@
+// hazo_blog/lib — validatePost(): a pre-publish content-quality gate.
+//
+// Encodes the SEO lessons that a stale Bing report surfaced late on a consumer
+// site: thin content, missing/oversized meta, and multiple <h1> per page. A
+// post's <h1> is its *title* — an `# ` (or <h1>) inside the body creates a
+// second page heading. Consumers call this before persisting/publishing and
+// reject on `errors` (blocking) while surfacing `warnings` (advisory).
+//
+// Pure + server-safe; reuses the existing text helpers, no new deps.
+import { mdxToPlainText, countWords, extractToc } from './text.js';
+/** Strip fenced code so a `#` in a code sample isn't mistaken for a heading. */
+function stripFencedCode(mdx) {
+    return mdx.replace(/```[\s\S]*?```/g, ' ');
+}
+/**
+ * Validate a post before publishing. Blocking issues land in `errors`
+ * (thin content, missing meta description, a second page <h1> in the body);
+ * advisory issues land in `warnings` (meta-description length, over-long title,
+ * missing excerpt/FAQ, no subheadings). `ok` is true iff there are no errors.
+ */
+export function validatePost(input, opts = {}) {
+    const minWords = opts.minWords ?? 300;
+    const titleLimit = opts.titleLengthLimit ?? 60;
+    const titleSuffix = opts.titleSuffix ?? '';
+    const [descMin, descMax] = opts.descriptionRange ?? [150, 160];
+    const errors = [];
+    const warnings = [];
+    const add = (severity, code, message) => (severity === 'error' ? errors : warnings).push({ code, severity, message });
+    // --- Thin content ---
+    const wordCount = countWords(mdxToPlainText(input.content));
+    if (wordCount < minWords) {
+        add('error', 'THIN_CONTENT', `Body is ${wordCount} words (<${minWords}). Expand before publishing.`);
+    }
+    // --- Second page <h1> in the body (the post title is the page <h1>) ---
+    const body = stripFencedCode(input.content);
+    const hasMarkdownH1 = /(^|\n)#\s+\S/.test(body);
+    const hasJsxH1 = /<h1[\s>]/i.test(body);
+    if (hasMarkdownH1 || hasJsxH1) {
+        add('error', 'BODY_H1', 'Body contains an H1 ("# " or <h1>). The post title is already the page H1 — demote body headings to ## or lower.');
+    }
+    // --- Meta description ---
+    const desc = input.meta_description?.trim();
+    if (!desc) {
+        add('error', 'MISSING_META_DESCRIPTION', 'Missing meta description.');
+    }
+    else if (desc.length < descMin) {
+        add('warning', 'META_DESCRIPTION_SHORT', `Meta description is ${desc.length} chars (<${descMin}). The ${descMin}–${descMax} band maximises snippet size.`);
+    }
+    else if (desc.length > descMax) {
+        add('warning', 'META_DESCRIPTION_LONG', `Meta description is ${desc.length} chars (>${descMax}) and will be truncated in SERPs.`);
+    }
+    // --- Composed title length ---
+    const seoTitle = (input.meta_title?.trim() || input.title.trim()) + titleSuffix;
+    if (seoTitle.length > titleLimit) {
+        add('warning', 'TITLE_TOO_LONG', `Rendered title "${seoTitle}" is ${seoTitle.length} chars (>${titleLimit}, incl. suffix). Google truncates ~60 and Bing flags >70.`);
+    }
+    // --- Softer structural advisories ---
+    if (!input.excerpt?.trim()) {
+        add('warning', 'MISSING_EXCERPT', 'No excerpt set — one will be auto-generated, but a hand-written excerpt reads better in listings.');
+    }
+    if (!input.faq || input.faq.length === 0) {
+        add('warning', 'NO_FAQ', 'No FAQ items. An FAQ section adds long-tail coverage (and is used across the site).');
+    }
+    if (extractToc(input.content).length === 0 && wordCount >= minWords) {
+        add('warning', 'NO_SUBHEADINGS', 'No subheadings (##) found. Long posts need structure for readers and for heading-based SERP features.');
+    }
+    return { ok: errors.length === 0, errors, warnings, issues: [...errors, ...warnings], wordCount };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_blog",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "SEO-optimized blogging package: posts, categories, tags, MDX content, and GA4/GSC/Bing-ready SEO.",
   "type": "module",
   "module": "./dist/index.js",
@@ -14,6 +14,10 @@
       "types": "./dist/index.client.d.ts",
       "import": "./dist/index.client.js"
     },
+    "./lib": {
+      "types": "./dist/lib/index.d.ts",
+      "import": "./dist/lib/index.js"
+    },
     "./seo": {
       "types": "./dist/seo/index.d.ts",
       "import": "./dist/seo/index.js"
@@ -44,14 +48,15 @@
     "build:test-app": "npm run build && cd test-app && npm run build"
   },
   "peerDependencies": {
-    "hazo_core": "^1.2.0",
-    "hazo_connect": "^3.9.0",
-    "hazo_api": "^2.4.0",
-    "hazo_files": "^3.1.0",
-    "hazo_ui": "^4.6.2",
-    "hazo_images": "^1.2.1",
-    "hazo_jobs": "^0.12.0",
-    "hazo_auth": "^10.0.0",
+    "hazo_core": "^1.2.1",
+    "hazo_connect": "^3.9.2",
+    "hazo_api": "^2.5.1",
+    "hazo_files": "^3.1.1",
+    "hazo_theme": "^1.0.1",
+    "hazo_ui": "^6.0.0",
+    "hazo_images": "^1.8.1",
+    "hazo_jobs": "^0.15.0",
+    "hazo_auth": "^10.8.2",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "next": "^14.0.0 || ^16.0.0"
@@ -65,6 +70,9 @@
     },
     "hazo_auth": {
       "optional": true
+    },
+    "hazo_theme": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -84,10 +92,10 @@
     "react-dom": "^19.0.0",
     "next": "^16.0.10",
     "hazo_core": "^1.2.1",
-    "hazo_connect": "^3.9.0",
+    "hazo_connect": "^3.9.2",
     "hazo_api": "^2.5.1",
     "hazo_files": "^3.1.1",
-    "hazo_ui": "^4.7.0",
+    "hazo_ui": "^6.0.0",
     "tailwindcss": "^4.2.4",
     "@tailwindcss/postcss": "^4.2.4",
     "postcss": "^8.4.49"