hazo_blog 0.4.1 → 1.1.0

package/CHANGE_LOG.md

@@ -3,6 +3,286 @@
 All notable changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 1.1.0 — 2026-09-11
+
+**`onPostSaved` config hook + `createBlogManageSlugRoutes` factory**
+
+Two additive capabilities requested by a consumer (stocktools) that needs to react to individual
+post writes/deletes and to manage a single post by slug over the programmatic (API-key) surface,
+rather than only through the collection-level `createBlogManageRoutes`.
+
+**1. `BlogConfig.onPostSaved?: (post: BlogPost | null, action: 'upsert' | 'delete') => void |
+Promise<void>`** — mirrors the existing `onSettingsChanged` hook. `BlogService.upsertBySlug` calls
+it with the saved `BlogPost` and `'upsert'` after a successful write; `BlogService.deletePost`
+calls it with `null` and `'delete'` after a successful delete. Both call sites wrap the hook in a
+`try/catch` — a throwing (or rejecting) `onPostSaved` never fails the surrounding write/delete,
+same "best-effort" contract as `onSettingsChanged`. Useful for cache invalidation
+(`revalidatePath`) or search-index sync keyed off individual posts rather than the whole settings
+blob.
+
+**2. `createBlogManageSlugRoutes(config: BlogConfig)`** — a new route-handler factory alongside
+`createBlogManageRoutes`, for a Next.js `[slug]` dynamic route on the programmatic management API.
+Returns `{ GET, PATCH, DELETE }`, each gated by `withApiKey` the same way as the collection route
+(`blog:read` for `GET`, `blog:write` for `PATCH`/`DELETE`):
+
+- `GET` — fetches one post by slug (including drafts), 404 via `fail("NOT_FOUND", ...)` when
+  missing.
+- `PATCH` — fetches the existing post by slug (404 if missing), merges the JSON body's fields onto
+  it (same field-by-field merge semantics as `createBlogManageRoutes`'s collection `PATCH`), and
+  calls `service.upsertBySlug`.
+- `DELETE` — fetches the existing post by slug (404 if missing, to resolve its `id`), calls
+  `service.deletePost(id)`, and returns `{ deleted: slug }`.
+
+Exported from the package barrel alongside the other route factories. No breaking changes.
+
+## 1.0.0 — 2026-09-05
+
+**FR-034, Part 1 — locale variants + `indexable` (schema + types + repository + service)**
+
+This is the schema/data-layer half of FR-034 (locale-variant posts, categories, and tags, plus a
+per-post `indexable` flag for excluding a post from the sitemap/robots without unpublishing it).
+The SEO layer (`src/seo/index.ts`), Next.js pages/routes, and the admin `PostForm` UI are a
+follow-up change — this release only touches schema, `src/types`, `src/repository`, and
+`src/service`. Two breaking changes warrant the major bump:
+
+**1. Database schema — new columns + a changed unique constraint**
+
+`hazo_blog_posts` gains `locale TEXT DEFAULT NULL`, `translation_of TEXT REFERENCES
+hazo_blog_posts(id) ON DELETE SET NULL` (`UUID` on Postgres), and `indexable INTEGER NOT NULL
+DEFAULT 1` (`BOOLEAN NOT NULL DEFAULT TRUE` on Postgres). `hazo_blog_categories` and
+`hazo_blog_tags` each gain `locale TEXT DEFAULT NULL`. All three tables' `(scope_id, slug)` unique
+index is replaced by `(scope_id, slug, COALESCE(locale, ''))` — the `COALESCE` folds every
+default-locale (`locale IS NULL`) row into one uniqueness bucket per `(scope_id, slug)`, since a
+plain `(scope_id, slug, locale)` unique index would let SQLite/Postgres treat every `NULL` as
+distinct from every other `NULL`, silently allowing duplicate default-locale posts. A new
+`idx_hazo_blog_posts_translation_of` index backs translation-cluster lookups.
+
+No SQLite table rebuild is required — `ALTER TABLE ... ADD COLUMN` works fine for these
+plain nullable/defaulted columns, and the old unique constraints were already separate
+`CREATE UNIQUE INDEX` statements rather than inline column constraints, so the index swap is a
+`DROP INDEX` + `CREATE UNIQUE INDEX` pair (both idempotent, safe to run on every process start).
+`db_setup_sqlite.sql`/`db_setup_postgres.sql` and their `migrations/` mirrors carry the new columns
+directly in their `CREATE TABLE IF NOT EXISTS` lists (so a fresh DB gets them immediately) plus the
+idempotent index-swap statements. An already-materialized SQLite dev DB (this package's
+`test-app/data/blog.sqlite`) won't pick up new columns from a skipped `CREATE TABLE IF NOT EXISTS`
+— `test-app/scripts/seed.mjs` gained a small `ensureColumns()` helper (guarded `PRAGMA
+table_info` + `ALTER TABLE ... ADD COLUMN`) that backfills them before the schema file's DROP/CREATE
+INDEX statements run. Postgres needs no such helper — `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`
+is natively idempotent and is included directly in `db_setup_postgres.sql`.
+
+**2. `BlogRepository`/`BlogService` breaking signature changes**
+
+- `getPostBySlug(slug, includeUnpublished?: boolean)` → `getPostBySlug(slug, opts?: {
+  includeUnpublished?: boolean; locale?: string | null })`. The old positional boolean 2nd
+  argument is gone.
+  ```ts
+  // before
+  await repo.getPostBySlug(slug, true);
+  // after
+  await repo.getPostBySlug(slug, { includeUnpublished: true });
+  ```
+- `getAllSlugs(includeUnpublished?)` now returns `Array<{ slug: string; locale: string | null }>`
+  instead of `string[]` (unfiltered by locale — every translation's slug is included).
+- New `getTranslations(postId)` on both `BlogRepository` and `BlogService`, resolving a post's full
+  translation cluster (root + every other variant, normalizing two-hop sibling→root→sibling chains
+  into one flat list) as `TranslationInfo[]`.
+- `BlogService.getPost(slug, opts?, req?)` gains `opts.locale` and `opts.fallbackToDefault`
+  (default `false`). With `fallbackToDefault: false`, a locale-specific miss returns `null` rather
+  than silently serving the default-locale post.
+- `listPosts`, `searchPosts`/`search`, `getRelatedPosts`, and `getOrCreateCategory` are all
+  locale-aware now; omitting `locale` anywhere continues to mean "default-locale only"
+  (`locale IS NULL`), so **existing single-locale consumers need no query changes** — every new
+  parameter is optional and defaults to the pre-1.0 behaviour.
+
+**Migration note for existing consumers:** the only required change is any call site using the old
+`getPostBySlug(slug, true)` positional form — switch it to `getPostBySlug(slug, {
+includeUnpublished: true })`. Everything else (locale filtering, translation clusters, `indexable`)
+is additive and opt-in.
+
+**New types:** `BlogPost.locale`/`translation_of`/`indexable` (the last is a required `boolean` —
+the repository normalizes SQLite's raw `0`/`1` `INTEGER` read-back to a real boolean so the type is
+honest on both dialects), `UpsertPostInput.locale`/`translation_of`/`indexable`,
+`ListPostsOptions.locale`, `BlogCategory.locale`, `BlogTag.locale`, `BlogPostWithRelations.translations`,
+new `TranslationInfo`, and `BlogConfig.defaultLocale` (default `'en'`, consumed by the follow-up SEO
+change).
+
+**Tests:** `src/__tests__/repository.integration.test.ts` gained a `FR-034` describe block (default
++ translated variant CRUD, DB-level uniqueness enforcement including the two-default-locale-NULLs
+case, cross-locale listing, translation-cluster resolution with two-hop normalization, unfiltered
+`getAllSlugs`). New `src/__tests__/locale.integration.test.ts` exercises the schema files directly
+against a fresh SQLite DB: new columns exist, the locale-aware unique indexes replace the old ones,
+the `COALESCE(locale, '')` NULL-folding behavior, `translation_of`'s FK (including `ON DELETE SET
+NULL`), the `indexable` default, and DDL idempotency (schema file re-run twice, no errors, no data
+loss).
+
+**FR-034, Part 2 — SEO / Next.js pages & routes / admin UI**
+
+The SEO-facing and presentation half of FR-034, building on Part 1's schema/repository/service
+layer above. Additive only — no further breaking changes on top of Part 1's major bump.
+
+- **`src/seo/index.ts`:**
+  - `isIndexable(post)` now also returns `false` when `post.indexable === false`, independent of
+    the existing draft/publish-date gate — a live published post can still be excluded from the
+    sitemap/RSS/robots via the per-post flag without being unpublished.
+  - `buildBlogPostingJsonLd`'s JSON-LD `inLanguage` is now `post.locale || config.defaultLocale ||
+    "en"` instead of a hardcoded `"en"`.
+  - `getBlogSitemapEntries` gained a new `SitemapEntry.alternates?: Array<{ locale: string; url:
+    string }>` field, populated from a post's `translations` (indexable siblings only, via
+    `postUrl`) when present. This is intentionally passive: the function does no DB lookups of its
+    own, so a host wanting hreflang alternates in its sitemap must attach `.translations` (from
+    `BlogService.getTranslations`) to each post before calling it — the existing
+    `createBlogSitemapRoute` call site doesn't do this yet, since it lists posts in bulk and
+    per-post translation lookups there are a host-level tradeoff, not this package's call to make.
+  - `getBlogRssXml`'s channel `<language>` now follows `config.defaultLocale` (default `"en"`)
+    instead of a hardcoded `"en"`. Items whose `post.locale` differs from the feed-level language
+    get a per-item `<dc:language>` element, and the `<rss>` root gains the `xmlns:dc` namespace
+    attribute only when at least one item actually needed it (an all-default-locale feed is
+    byte-identical to before this change).
+  - `src/__tests__/seo.test.ts`'s `makePost()` helper now sets the required `indexable: true` field
+    (fixes a `type-check` failure introduced by Part 1's `BlogPost.indexable: boolean` becoming
+    non-optional). New tests cover locale-aware `inLanguage`, `indexable: false` sitemap exclusion,
+    sitemap `alternates` construction (including skipping non-indexable siblings), and the RSS
+    `<language>`/`<dc:language>`/`xmlns:dc` behavior.
+
+- **`src/next/pages.tsx`** (`createBlogPostPage`):
+  - `generateMetadata` now also awaits `service.getTranslations(post.id)` and, when the cluster is
+    non-empty, adds a Next.js Metadata API `alternates.languages` map (`{ [locale]: url }`, built
+    via `postUrl`, indexable siblings only) alongside the existing `alternates.canonical`.
+  - Both `generateMetadata` and the page component now accept an optional `params.locale` (in
+    addition to the existing `params.slug`) and, when present, thread it through to
+    `service.getPost(slug, { locale })`. When absent, behavior is unchanged from before this
+    release — locale-prefixed routing remains the consuming app's concern (see `postUrl`'s
+    doc-comment); this package only adds the pass-through slot.
+
+- **`src/next/routes.ts`:**
+  - `createBlogSearchRoute` now reads an optional `?locale=` query param and passes it through to
+    `service.search(q, 20, req, locale)`.
+  - `createBlogManageRoutes`'s `PATCH` handler now accepts `locale`, `translation_of`, and
+    `indexable` in the request body and merges them into the existing-post-derived
+    `UpsertPostInput`, same pattern as every other partial field on that handler.
+
+- **`src/components/admin/post-form.tsx`:** `PostForm` gained three new fields, all sent through
+  the existing unified `save()` payload: a free-text **Locale** input (BCP-47 code, blank = default
+  locale), a free-text **Translation of (post ID)** input (labeled explicitly since
+  `translation_of` stores the parent post's `id`, not its slug — no post-picker UI exists in this
+  form to reuse), and an **Indexable** checkbox (defaults to `true`, matching the DB default). All
+  three keep the file's existing `bg-background`/`border-border` token classes per the isolation
+  rule documented in `CLAUDE.md` (this form is the one accepted exception inside the
+  otherwise-token-free `src/ui/*` boundary).
+
+- **`test-app/app/autotest/hazo_blog_scenarios.ts`:** the browser-side `POST` fixture used by the
+  `/autotest` SEO-builder scenarios gained the required `indexable: true` field (same root cause as
+  the `seo.test.ts` fix above — this only surfaces in a full test-app Next build, not `tsc
+  --noEmit`, since it's outside this package's own `tsconfig.json` project).
+
+**Out of scope for Part 2 (deliberately):** wiring `createBlogSitemapRoute`/`createBlogFeedRoute` to
+actually populate `.translations` on each post before calling `getBlogSitemapEntries`/
+`getBlogRssXml` — that requires either N+1 `getTranslations` calls per sitemap post or a new bulk
+repository method, and no call site in this package currently needs it (`SitemapEntry.alternates`
+and the RSS locale fields work correctly today for any host that already attaches `.translations`
+itself, e.g. via a custom sitemap route). A locale-prefixed URL scheme for `postUrl`/route
+generation (e.g. `/blog/fr/hello-world`) — still explicitly the consuming app's routing concern per
+existing package convention. A post-picker UI for `translation_of` in `PostForm` — the plain
+post-ID text input is the proportionate choice given no such picker exists elsewhere in this form.
+
+## 0.5.0 — 2026-08-17
+
+**Two named `/blog` index layouts — `grid` (unchanged) + new `editorial`**
+
+`BlogIndexLayout` (`src/lib/layouts.ts`) is now `"grid" | "editorial"`, with `BLOG_INDEX_LAYOUT_META`
+carrying a label + description for each. `BlogIndexGrid` is a verbatim extraction of the previous
+inline index markup — the back-compat anchor. `BlogIndexEditorial` is new: a big title/subtitle, a
+pill search box, a full-width featured split card for the latest post, then a staggered 3-column
+grid. `createBlogIndexPage` selects between them via `BLOG_INDEX_LAYOUTS`
+(`src/components/layouts/index.ts`), keyed by the host's persisted `BlogSettings.indexLayout` (or
+`BlogConfig.defaultIndexLayout` when nothing is persisted). Both layouts accept the identical
+`BlogIndexLayoutProps` — that's the point, they're swappable without touching the page factory.
+
+**Package-owned settings store (`hazo_blog_settings`, new table)**
+
+A single host-wide settings row (`BLOG_SETTINGS_KEY = "display"`, tenant-scoped like every other
+table when `scope_id` is set), read/written through three new `BlogService` methods:
+`getSettings()` (never throws — falls back to `defaultIndexLayout`), `updateSettings(patch)`
+(merge + persist, throws a typed `BlogSettingsUnavailableError` if the table can't be written),
+and `settingsAvailable()` (a cheap existence probe). Read degrades gracefully, write surfaces
+failure clearly — see "Key invariants" in `CLAUDE.md` for the reasoning. Exposed over HTTP via
+the new `createBlogSettingsRoutes` (`GET`/`PUT`, cookie/session-guarded via the newly-extracted
+`createAuthGuard` helper, now shared with `createBlogAdminRoutes`).
+
+**Real admin panel — new `./ui` export, `BlogAdminPanel`**
+
+Replaces the "coming soon" stub story for host admin shells (e.g. `hazo_admin`) with a working
+panel: `BlogAdminPanel` composes `PostListTable` + the existing `PostForm` (in a new `PanelDialog`)
++ a new `LayoutSelector` for the index-layout setting, all driven by the `useBlogAdmin` hook. The
+whole tree is pure React, `next/*`-free, and deliberately token-free Tailwind (not this package's
+usual `bg-background`-style tokens) so it renders correctly inside a host shell that may not define
+`hazo_theme`'s CSS variables — the strictest export-boundary tier in the package. See `AGENTS.md`
+for the full isolation rule.
+
+**Featured-image + MDX-image uploads — one endpoint, one policy**
+
+`createBlogImageUploadRoute` (`hazo_blog/next`) delegates to `hazo_images`' image-processing
+handler (an optional peer, dynamically imported so hosts without it installed don't crash — 501s
+with a named-package message instead) and rewrites the saved URL through the new
+`BlogConfig.media` config (`getFileManager`/`pathPrefix`/`publicUrlBase`/`toPublicUrl`). Deliberately
+one endpoint with one upload policy: a host wires the same route to both the featured-image picker
+(new `featured-image-field.tsx`, used by `PostForm`) and an MDX editor's "insert image" action,
+rather than standing up two handlers. 501s clearly when `media.getFileManager` isn't configured,
+independent of the `hazo_images`-not-installed 501.
+
+**Dark-mode search dropdown fix**
+
+`BlogSearch`'s results dropdown previously hardcoded `style={{ backgroundColor: "white" }}` plus
+raw `zinc-*` classes, which was genuinely illegible against a dark host theme. Fixed to use theme
+tokens. New optional `variant?: "default" | "pill"` prop (default preserves the exact prior
+markup/behaviour) — this is a fix, not a new feature; call it out explicitly as such.
+
+**Back-compat: zero break**
+
+Every consumer on `^0.4.x` upgrades with no code changes required. The default index layout
+(`grid`) renders byte-identical markup to the pre-0.5.0 inline implementation. Every new
+`BlogConfig` field (`defaultIndexLayout`, `media`, `settingsApiPath`, `imageUploadApiPath`,
+`onSettingsChanged`) is optional. `createBlogAdminRoutes`' `collection.GET` only gains a response
+key. A host that never migrates the new `hazo_blog_settings` table simply gets `getSettings()`
+falling back to `defaultIndexLayout` (or `"grid"`) forever, with one process-lifetime console
+warning — never a crash.
+
+**Internal**
+
+- New `src/ui/*` test coverage alongside the existing `src/__tests__/` suites.
+- `__mocks__/hazo_core.cjs` was missing `globalSingleton`/`resetGlobalSingleton` — a real
+  pre-existing gap, not something this release introduced. `hazo_connect`'s dependency chain now
+  calls both at module load, and the stale mock was blocking 2 existing test suites from loading
+  at all ("hazo_core does not provide an export named 'globalSingleton'"). Fixed with a
+  self-contained promise-cache implementation matching real `hazo_core`'s evict-on-reject
+  semantics, deliberately kept separate from the older `registerSingleton`/`getSingleton` mock
+  pair rather than unifying the two (that pair already diverges from the real factory-less API,
+  and changing it risked currently-passing tests).
+- `src/__tests__/seo.test.ts`'s `ResolvedBlogConfig` test fixture was missing `adminBasePath`/
+  `adminApiBasePath` — a pre-existing, unrelated `tsc` error, fixed incidentally while touching
+  this release's config surface.
+
+## 0.4.2 — 2026-08-14
+
+**`BlogConfig.apiKeyService` (new, optional) — fixes a `createBlogManageRoutes` contract bug**
+
+`createBlogManageRoutes` (the programmatic, hazo_api-key-guarded `/api/blog/manage` routes)
+always built its API-key validation adapter as
+`createApiKeyService({ getHazoConnect: config.getHazoConnect })`. But `getHazoConnect` is
+documented — and used elsewhere, by `createBlogRepository` — as a hazo_connect CRUD adapter,
+a *different* shape than hazo_api's raw-SQL `{dialect, query(sql, params)}` contract that
+`createApiKeyService` actually needs. Any host whose `getHazoConnect` returns the (expected)
+CRUD adapter got a route that threw on every request to `/api/blog/manage` — found while wiring
+this into stocktools, whose `getHazoConnect` returns its hazo_connect singleton.
+
+`apiKeyService?: ApiKeyService` on `BlogConfig` lets a host inject an already-built
+`ApiKeyService` — from `hazo_api`'s `createApiKeyService` (raw-SQL) or
+`createPostgrestApiKeyService` (no raw-SQL conduit needed, the better fit for a PostgREST
+backend) — that `createBlogManageRoutes` uses in preference to the old
+`getHazoConnect`-derived fallback. Fully backward-compatible: omitting the field preserves the
+exact pre-existing behaviour (and its pre-existing footgun, for hosts that happen to already
+satisfy the raw-SQL shape). New test: `src/__tests__/routes.manage-api-key.test.ts`.
+
 ## 0.4.0 — 2026-07-14
 
 **`validatePost()` — pre-publish content-quality gate (new, `hazo_blog/lib`)**

package/README.md

@@ -4,7 +4,11 @@ SEO-first blogging for Next.js App Router apps: posts, categories, tags, MDX
 content, and GA4 / Google Search Console / Bing-ready output (BlogPosting +
 BreadcrumbList + FAQPage JSON-LD, canonical, OG, sitemap, RSS). The package owns
 the page layout **and** all SEO; the host customizes via Tailwind theme tokens
-and a single `BlogConfig`.
+and a single `BlogConfig`. The `/blog` index ships two selectable layouts (grid
+and editorial — see [Layouts](#layouts)), and the admin surface can be mounted
+either as sealed pages or embedded as one framework-agnostic panel component
+(`hazo_blog/ui`'s `BlogAdminPanel` — see
+[Option C](#option-c--embed-the-panel-in-your-admin-shell)).
 
 ## Install
 
@@ -42,6 +46,13 @@ export const blogConfig: BlogConfig = {
   defaultOgImage: "https://acme.com/og.png",
   author: { name: "Acme Team", url: "https://acme.com/about" },
   getHazoConnect: () => myHazoConnectAdapter,    // SQLite or Postgres
+  // Only needed if you mount createBlogManageRoutes (step 4's `manage`
+  // export) — `getHazoConnect` above is a hazo_connect CRUD adapter, a
+  // DIFFERENT shape than the raw-SQL adapter hazo_api's API-key validation
+  // needs, so most hosts must supply this explicitly rather than relying on
+  // the (rarely-satisfiable) getHazoConnect fallback. Build one with
+  // hazo_api's `createApiKeyService`/`createPostgrestApiKeyService`:
+  // apiKeyService: createPostgrestApiKeyService({ postgrest_url, postgrest_api_key }),
   authorize: (req) => checkAdminPermission(req),  // wire to hazo_auth
   // resolveScope: (req) => orgIdFrom(req),       // multi-tenant only
   // getAuthor: (id) => lookupAuthor(id),         // per-post authors
@@ -137,6 +148,233 @@ export default async function sitemap() {
 }
 ```
 
+## Settings
+
+hazo_blog owns a small settings table (`hazo_blog_settings`) for host-configurable
+display/behavior settings. As of 0.5.0 it holds one setting — `indexLayout` (see
+[Layouts](#layouts)) — with room for more to be added later without a config or
+DDL churn for hosts already wired up.
+
+**Read** — `service.getSettings(req?)` never throws. It reads the persisted row
+and falls back to `{ indexLayout: config.defaultIndexLayout ?? "grid" }` if the
+table is missing or the read errors — logging one warning per process, not per
+request, so a fleet of requests hitting an un-migrated table doesn't spam logs.
+
+**Write** — `service.updateSettings(patch, req?)` merges `patch` into the current
+settings and persists it. Throws `BlogSettingsUnavailableError` if the table
+can't be written to (e.g. not migrated yet) — the route factory below turns
+this into a `503`.
+
+**HTTP surface** — mount `createBlogSettingsRoutes(config)` at
+`config.settingsApiPath` (default `${adminApiBasePath}/settings`):
+
+```ts
+// app/api/admin/blog/settings/route.ts
+import { createBlogSettingsRoutes } from "hazo_blog";
+import { blogConfig } from "@/lib/blog-config";
+
+const routes = createBlogSettingsRoutes(blogConfig);
+export const GET = routes.GET;
+export const PUT = routes.PUT;
+```
+
+Both `GET` and `PUT` are guarded by `config.authorize`, same as the other admin
+routes. `GET` returns:
+
+```ts
+{
+  settings: BlogSettings;               // { indexLayout: "grid" | "editorial" }
+  defaults: { indexLayout?: BlogIndexLayout }; // echoes config.defaultIndexLayout
+  layouts: typeof BLOG_INDEX_LAYOUT_META;      // id/label/description per layout
+  persisted: boolean;                   // false = table not migrated, read-only
+}
+```
+
+`PUT` accepts a `Partial<BlogSettings>` body and returns `{ settings }` on
+success, or `503 SETTINGS_UNAVAILABLE` when the table can't be written to (the
+same `BlogSettingsUnavailableError` from `getSettings`/`updateSettings` above).
+
+**Schema** — `hazo_blog_settings` (dual-dialect, defined in `db_setup_sqlite.sql`
+/ `db_setup_postgres.sql` alongside the other four tables): one row per
+`(scope_id, setting_key)` with a JSON `payload` column. Apply it the same way as
+the rest of this package's DDL — through your migration runner on SQLite, or a
+manual `psql -f` step on Postgres, per your app's own DDL convention.
+
+**`onSettingsChanged`** — fires after a successful `updateSettings` write,
+inside its own `try/catch` so a host revalidate failure can't fail the settings
+save itself:
+
+```ts
+onSettingsChanged: () => {
+  try {
+    revalidatePath("/blog");
+  } catch {
+    // No-op outside a request/render context (e.g. called from a script).
+  }
+},
+```
+
+This matters because `/blog` is typically ISR-cached (`revalidate = 3600` from
+step 3) — without a revalidate hook, switching layouts via the admin panel
+won't be visible on the public index until the next natural ISR window.
+
+## Locale variants
+
+> **Breaking change in 1.0.0** — see the migration note below if you're upgrading from 0.x.
+
+`hazo_blog_posts`/`_categories`/`_tags` each carry a nullable `locale` column, uniquely constrained per `(scope_id, slug, locale)` — a `NULL` locale is your "default" post, and only one default (and one per non-null locale) can exist per slug. Posts also carry `translation_of` (the id of the post this is a translation of) and `indexable` (excludes a post from the sitemap and marks its JSON-LD/RSS as non-indexable without unpublishing it).
+
+```ts
+// Create a translated variant of an existing post
+await service.upsertBySlug({
+  slug: "my-post",
+  locale: "fr",
+  translation_of: originalPost.id,
+  title: "Mon article",
+  // ...
+});
+
+// Fetch a specific locale — returns null (not the default post) when that
+// locale doesn't exist, unless you opt into fallback:
+const fr = await service.getPost("my-post", { locale: "fr" });
+const frOrDefault = await service.getPost("my-post", { locale: "fr", fallbackToDefault: true });
+
+// Walk a post's translation cluster (root + every sibling translation, minus itself)
+const translations = await service.getTranslations(post.id);
+// => [{ locale, slug, id, indexable }, ...]
+```
+
+`listPosts()`/`searchPosts()` default to `locale`-omitted, which returns **default-locale posts only** — existing single-locale consumers see no behavior change and never double-count translations in a listing. Pass `locale` explicitly to list/search one locale's posts.
+
+**SEO**: `buildBlogPostingJsonLd` sets `inLanguage` from `post.locale || config.defaultLocale || "en"`; `getBlogSitemapEntries` excludes `indexable: false` posts and adds an `alternates: [{ locale, url }]` entry per sitemap item when the post carries a `.translations` array (populate it yourself via `getTranslations` before calling the sitemap builder — the package doesn't do this join automatically); `getBlogRssXml` uses `config.defaultLocale` for the feed `<language>` and adds a per-item `<dc:language>` when an item's locale differs from the feed default. `generateMetadata` on the post page adds `alternates.languages` (hreflang) automatically from `getTranslations`.
+
+**Migrating from 0.x**: `getPostBySlug`'s second parameter is now an options object, not a boolean —
+
+```ts
+// before (0.x)
+await repo.getPostBySlug(slug, true);
+// after (1.0.0)
+await repo.getPostBySlug(slug, { includeUnpublished: true });
+```
+
+— and `getAllSlugs()` now returns `Array<{ slug, locale }>` instead of `string[]`. Existing single-locale data needs no migration: every current row's `locale` is `NULL` already, which *is* the default-locale bucket every existing query path reads from.
+
+## Layouts
+
+`config.defaultIndexLayout` (and the runtime override in [Settings](#settings))
+picks which component renders the `/blog` index — `BLOG_INDEX_LAYOUT_META`
+(exported from `hazo_blog` and `hazo_blog/lib`) describes both:
+
+| Layout | Looks like | Use it when |
+|---|---|---|
+| `grid` (default) | Classic responsive card grid — one flat `sm:grid-cols-2 lg:grid-cols-3` layout for every post. Byte-identical to the pre-0.5.0 index markup. | You want the plainest, safest option, or your posts don't reliably carry a `featured_image`. |
+| `editorial` | Big title + subtitle, pill search, a hairline rule, a full-width featured split card for the newest post, then a staggered 3-column grid below. | You want a more magazine-like landing page and most posts have a `featured_image`. |
+
+**Degradation behavior** (same for both layouts unless noted):
+
+- **0 posts** — empty state.
+- **1 post** — `editorial` renders the featured-card only (no grid below); `grid` renders one card.
+- **2 posts** — `editorial` renders the featured card + 1 grid card below.
+- **Active search (`?q=`)** — `editorial` drops the featured card entirely; every matching post
+  (including the newest) renders as a plain grid card, same as `grid`.
+- **`featured_image: null`** — both the featured card and grid cards render a
+  gradient + icon placeholder instead of an image block. No broken-image state either layout.
+- **Mobile** — single column; `editorial`'s featured card stacks image-over-text instead of
+  side-by-side.
+
+**Set the default** at boot via `defaultIndexLayout` in `BlogConfig` (falls back
+to `"grid"` when omitted). **Switch it live** at runtime via the admin panel's
+built-in `LayoutSelector` (see [Option C](#option-c--embed-the-panel-in-your-admin-shell)),
+which writes through `service.updateSettings({ indexLayout })` to the
+`hazo_blog_settings` table above — no redeploy required, only an ISR revalidate
+(wire `onSettingsChanged` as shown in [Settings](#settings), or wait out the
+natural `revalidate` window).
+
+> **Remote images:** the `editorial` layout's featured card leans hard on
+> `featured_image` being visible (`grid`'s thumbnails always did too, just
+> smaller). If any post's `featured_image` is a remote, non-same-origin URL,
+> configure `images.remotePatterns` in your own `next.config.js` — otherwise
+> `next/image` refuses to render it. See
+> [Required Next.js config](#required-nextjs-config).
+
+## Images
+
+Featured-image and MDX-body-image uploads share **one endpoint and one upload
+policy** — there's no separate pipeline for the two.
+
+**Server** — `createBlogImageUploadRoute(config, deps?)`, mounted at
+`config.imageUploadApiPath` (default `${adminApiBasePath}/images`):
+
+```ts
+// app/api/admin/blog/images/route.ts
+import { createBlogImageUploadRoute } from "hazo_blog";
+import { blogConfig } from "@/lib/blog-config";
+
+export const POST = createBlogImageUploadRoute(blogConfig);
+```
+
+It requires **both**:
+- `hazo_images` installed (optional peer) — `501 IMAGE_PIPELINE_UNAVAILABLE` naming the missing
+  package if it isn't.
+- `config.media` configured (see `BlogMediaConfig` below) — `501 MEDIA_NOT_CONFIGURED` if absent.
+
+On success it rewrites the saved file's URL via `config.media.toPublicUrl` (if
+given), or by joining `config.media.publicUrlBase` with the stored path
+otherwise:
+
+```ts
+interface BlogMediaConfig {
+  getFileManager: () => BlogFileManager | Promise<BlogFileManager>;
+  pathPrefix?: string;        // default "/hazo-blog"
+  publicUrlBase?: string;
+  toPublicUrl?: (saved: { path: string; url: string }) => string;
+  maxUploadBytes?: number;
+  allowedTypes?: string[];
+  processOptions?: Record<string, unknown>;
+}
+```
+
+`BlogFileManager` is a **structural** interface (`uploadFile(source, remotePath, options?)`) — you
+don't need an adapter to satisfy it with `hazo_files`' `FileManager`/`TrackedFileManager`, e.g.:
+
+```ts
+// lib/blog-config.ts
+import { createInitializedFileManager, type FileManager } from "hazo_files";
+
+let fileManagerPromise: Promise<FileManager> | null = null;
+function getFileManager(): Promise<FileManager> {
+  if (!fileManagerPromise) {
+    fileManagerPromise = createInitializedFileManager({
+      config: { provider: "local", local: { basePath: "/path/to/public/uploads" } },
+    });
+  }
+  return fileManagerPromise;
+}
+
+export const blogConfig: BlogConfig = {
+  // ...
+  media: {
+    getFileManager: () => getFileManager(),
+    pathPrefix: "/hazo-blog",
+    publicUrlBase: "/uploads",
+  },
+};
+```
+
+**Client** — `createBlogImageUploader({ endpoint, fetchFn?, processOptions? })`
+(exported from `hazo_blog/client`) returns a `(file: File) => Promise<string | null>`
+function — never throws, resolves `null` on any failure. This is exactly what
+`PostForm`'s featured-image field and its `MarkdownEditor`'s inline-image button
+call under the hood when `PostForm` is given `imageUploadEndpoint`:
+
+```tsx
+"use client";
+import { createBlogImageUploader } from "hazo_blog/client";
+
+const uploadImage = createBlogImageUploader({ endpoint: "/api/admin/blog/images" });
+const url = await uploadImage(file); // string | null
+```
+
 ## 6. Admin pages
 
 ### Option A — Sealed admin pages (recommended)
@@ -185,6 +423,51 @@ import { PostForm } from "hazo_blog/client";
 // For edit: <PostForm post={existingPost} categories={categories} ... />
 ```
 
+### Option C — embed the panel in your admin shell
+
+`hazo_blog/ui` exports `BlogAdminPanel` — a **framework-agnostic** (no `next/*`
+imports), **token-free-styled** (raw Tailwind palette classes, not this
+package's theme CSS variables) React component. Token-free means it drops into
+any host admin shell without that host needing to adopt `hazo_theme`.
+
+```ts
+interface BlogAdminPanelProps {
+  fetchFn: (path: string, init?: RequestInit) => Promise<Response>;
+  basePath: string;              // e.g. "/api/admin/blog"
+  blogBasePath?: string;         // public link base, default "/blog"
+  settingsPath?: string;         // default `${basePath}/settings`
+  imageUploadPath?: string;      // default `${basePath}/images`
+  className?: string;
+}
+```
+
+```tsx
+// A "use client" host component (fetchFn is a closure — it can't cross the
+// server→client prop boundary unless it's a Server Action, so this has to be
+// a client module, not a server component rendering a client child).
+"use client";
+import { BlogAdminPanel } from "hazo_blog/ui";
+
+export function BlogAdmin() {
+  return (
+    <BlogAdminPanel
+      fetchFn={(path, init) => fetch(path, { credentials: "include", ...init })}
+      basePath="/api/admin/blog"
+    />
+  );
+}
+```
+
+It provides: a searchable/filterable post list, create/edit via a built-in
+dialog (wraps `PostForm`), delete, and the layout selector from
+[Layouts](#layouts) (with a "not migrated, read-only" banner when settings
+persistence isn't available — see [Settings](#settings)).
+
+This is the pattern `hazo_admin` 0.13.2 uses to lazy-mount the panel (a dynamic
+`import("hazo_blog/ui")` behind a `.catch()` fallback, same shape as its
+`hazo_jobs/ui` integration) — see `hazo_admin`'s own docs/CHANGE_LOG for that
+side of the wiring, not this package's concern.
+
 ## Required Next.js config
 
 ```js
@@ -202,7 +485,13 @@ const nextConfig = {
   `node_modules/sql.js/dist/sql-wasm.wasm` to your app's `public/sql-wasm.wasm`.
 - **Tailwind v4:** add `@source "../node_modules/hazo_blog/dist";` to your CSS so
   the package's classes are compiled. The admin editor's styles load automatically
-  via `hazo_ui`'s `MarkdownEditor`.
+  via `hazo_ui`'s `MarkdownEditor`. This single, whole-`dist`-directory entry already
+  covers the 0.5.0 `dist/ui` (`BlogAdminPanel`) and `dist/components/layouts`
+  (grid/editorial index layouts) output — no extra `@source` line needed.
+- **Remote images:** if any post's `featured_image` is a non-same-origin URL, add it
+  to `images.remotePatterns` — required for `next/image` to render it, and far more
+  visible now that the `editorial` layout's featured card leans on it (see
+  [Layouts](#layouts)).
 
 ### Build resilience
 
@@ -227,6 +516,7 @@ pipelines.
 | `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` |
+| `hazo_blog/ui` | `BlogAdminPanel` — framework-agnostic, token-free admin panel component for embedding in a host admin shell (e.g. `hazo_admin`). No `next/*`, no server-only imports — pure React + Tailwind. |
 
 ### Search