hazo_blog 0.4.0 → 0.5.0

package/CHANGE_LOG.md

@@ -3,6 +3,104 @@
 All notable changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 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,192 @@ 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.
+
+## 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 +382,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 +444,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 +475,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
 

package/SETUP_CHECKLIST.md

@@ -15,6 +15,10 @@ for full code samples.
 - [ ] Apply `db_setup_sqlite.sql` or `db_setup_postgres.sql` (or add to your migration runner)
 - [ ] Confirm tables exist: `hazo_blog_posts`, `hazo_blog_categories`, `hazo_blog_tags`, `hazo_blog_post_tags`
 - [ ] If using `hazo_api`'s management API: ensure `hazo_api_keys` table exists (ships with hazo_api)
+- [ ] (0.5.0+) Confirm `hazo_blog_settings` exists — backs the `indexLayout` setting (dual-dialect,
+      same two SQL files as above). On Postgres this is a manual `psql -f` step, same convention as
+      the rest of this package's DDL. Not strictly required to boot: a missing table degrades to
+      `config.defaultIndexLayout` (read-only) rather than a 500 — see `README.md`'s Settings section
 
 ## 3. Config
 
@@ -26,6 +30,10 @@ for full code samples.
 - [ ] (per-post authors) set `getAuthor(id)`
 - [ ] (analytics) set `onAnalyticsEvent` or rely on the `window.gtag` fallback
 - [ ] (non-default paths) set `adminBasePath`, `adminApiBasePath`, `searchApiPath` if your routes differ from defaults (`/admin/blog`, `/api/admin/blog`, `/api/blog/search`)
+- [ ] (0.5.0+, index layout) set `defaultIndexLayout` (`"grid"` default | `"editorial"`), and optionally `indexTitle`/`indexDescription`
+- [ ] (0.5.0+, image uploads) set `media: { getFileManager, pathPrefix?, publicUrlBase?, toPublicUrl?, maxUploadBytes?, allowedTypes? }` — `getFileManager` must resolve a `BlogFileManager`-satisfying manager (e.g. `hazo_files`' `FileManager`/`TrackedFileManager` via `createInitializedFileManager`)
+- [ ] (0.5.0+, non-default paths) set `settingsApiPath`, `imageUploadApiPath` if your routes differ from defaults (`${adminApiBasePath}/settings`, `${adminApiBasePath}/images`)
+- [ ] (0.5.0+, optional) set `onSettingsChanged` (e.g. `() => revalidatePath("/blog")`) so an admin-panel layout switch shows up on `/blog` without waiting for the next ISR window
 
 ## 4. Routes
 
@@ -38,6 +46,8 @@ for full code samples.
 - [ ] (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`
+- [ ] (0.5.0+) `app/api/admin/blog/settings/route.ts` → `createBlogSettingsRoutes` (`GET`/`PUT`, cookie/session, guarded by `authorize`)
+- [ ] (0.5.0+, only if uploading images) `app/api/admin/blog/images/route.ts` → `createBlogImageUploadRoute` (`POST`) — needs `hazo_images` installed AND `config.media` configured, else it 501s
 
 ### Admin UI pages (sealed, recommended)
 
@@ -46,12 +56,27 @@ for full code samples.
 - [ ] `app/admin/blog/[slug]/edit/page.tsx` → `createBlogAdminEditPage` + `export const dynamic = "force-dynamic"`
 - [ ] **Note**: `dynamic` must be a static string literal — cannot re-export from the factory object
 
+### Admin panel (0.5.0+, alternative to the sealed pages — Option C)
+
+- [ ] Instead of (or alongside) the three sealed pages above, mount `<BlogAdminPanel>` from
+      `hazo_blog/ui` in your own `"use client"` admin route/shell, e.g.
+      `import { BlogAdminPanel } from "hazo_blog/ui"`
+- [ ] Pass `fetchFn` (wraps your host's auth/credentials), `basePath` (e.g. `/api/admin/blog`), and
+      optionally `blogBasePath`/`settingsPath`/`imageUploadPath` if they differ from the defaults
+- [ ] This is the shape `hazo_admin` 0.13.2 uses to lazy-`import("hazo_blog/ui")` behind a `.catch()`
+      fallback — same pattern as its `hazo_jobs/ui` integration
+
 ## 5. Next.js config (required)
 
 - [ ] `transpilePackages: ["hazo_blog", "hazo_ui", "next-mdx-remote"]` ← transpiling `next-mdx-remote` prevents the "React Element from an older version" MDX prerender error
 - [ ] `serverExternalPackages: ["better-sqlite3"]` (if using the SQLite adapter)
 - [ ] Copy `node_modules/sql.js/dist/sql-wasm.wasm` → `public/sql-wasm.wasm` (hazo_connect SQLite uses sql.js/WASM)
 - [ ] Tailwind v4: add `@source "../node_modules/hazo_blog/dist";` to your CSS
+- [ ] (0.5.0+) Confirm that single `@source` entry already covers the new `dist/ui`
+      (`BlogAdminPanel`) and `dist/components/layouts` (grid/editorial) output — it's the whole
+      `dist` directory, so no additional `@source` line is needed
+- [ ] (0.5.0+, if any post's `featured_image` is a remote URL) add it to `images.remotePatterns` —
+      required for `next/image` to render it, most visible on the `editorial` layout's featured card
 
 ## 6. Verify
 
@@ -62,4 +87,12 @@ for full code samples.
 - [ ] Admin list page shows status badges (green=published, grey=draft) and publish dates
 - [ ] Admin edit page pre-populates all fields; Save draft / Publish both work
 - [ ] Search: typing 2+ chars shows dropdown; Enter navigates to `?q=` filtered index
+- [ ] Search dropdown is legible in dark mode (0.5.0 fix — was hardcoded white/`zinc-*`, now theme tokens)
 - [ ] Paste a post's HTML into Google's Rich Results Test — no errors
+- [ ] (0.5.0+) Switch the index layout via the admin panel's layout selector, then confirm `/blog`
+      reflects it after your `onSettingsChanged` revalidate fires (or after the next ISR window)
+- [ ] (0.5.0+) Upload a featured image via the admin form/panel — the thumbnail renders immediately
+      without a manual refresh
+- [ ] (0.5.0+) Point `getHazoConnect` at a DB that hasn't run the `hazo_blog_settings` DDL — `/blog`
+      still renders (no 500), the settings panel shows a "not migrated, read-only" banner, and the
+      server logs exactly one warning (not one per request)

package/db_setup_postgres.sql

@@ -69,3 +69,16 @@ CREATE TABLE IF NOT EXISTS hazo_blog_post_tags (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_blog_post_tags_unique
   ON hazo_blog_post_tags (post_id, tag_id);
 CREATE INDEX IF NOT EXISTS idx_hazo_blog_post_tags_tag ON hazo_blog_post_tags (tag_id);
+
+-- package-owned display/behavior settings, e.g. which blog index layout is
+-- active — one row per (scope_id, setting_key)
+CREATE TABLE IF NOT EXISTS hazo_blog_settings (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  scope_id    TEXT,
+  setting_key TEXT NOT NULL,
+  payload     JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_blog_settings_scope_key
+  ON hazo_blog_settings (scope_id, setting_key);

package/db_setup_sqlite.sql

@@ -8,6 +8,7 @@
 --   hazo_blog_categories  — single category per post
 --   hazo_blog_tags        — free-form tags (many-to-many with posts)
 --   hazo_blog_post_tags   — post↔tag join
+--   hazo_blog_settings    — package-owned display/behavior settings
 --
 -- Multi-tenancy: every table carries a nullable `scope_id`. Single-tenant
 -- consumers (e.g. gotimer) leave it NULL; multi-tenant consumers populate it
@@ -75,3 +76,16 @@ CREATE TABLE IF NOT EXISTS hazo_blog_post_tags (
 CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_blog_post_tags_unique
   ON hazo_blog_post_tags (post_id, tag_id);
 CREATE INDEX IF NOT EXISTS idx_hazo_blog_post_tags_tag ON hazo_blog_post_tags (tag_id);
+
+-- package-owned display/behavior settings, e.g. which blog index layout is
+-- active — one row per (scope_id, setting_key)
+CREATE TABLE IF NOT EXISTS hazo_blog_settings (
+  id          TEXT PRIMARY KEY,
+  scope_id    TEXT,
+  setting_key TEXT NOT NULL,
+  payload     TEXT NOT NULL DEFAULT '{}',
+  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_blog_settings_scope_key
+  ON hazo_blog_settings (scope_id, setting_key);

package/dist/components/admin/featured-image-field.d.ts

@@ -0,0 +1,13 @@
+export interface FeaturedImageFieldProps {
+    /** Current featured_image URL, "" if unset. */
+    value: string;
+    onChange: (url: string) => void;
+    /**
+     * Upload handler — if absent, the field falls back to URL-only mode (no
+     * drag/drop, no Upload button, just the manual text input).
+     */
+    uploader?: (file: File) => Promise<string | null>;
+    className?: string;
+}
+export declare function FeaturedImageField({ value, onChange, uploader, className, }: FeaturedImageFieldProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=featured-image-field.d.ts.map

package/dist/components/admin/featured-image-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"featured-image-field.d.ts","sourceRoot":"","sources":["../../../src/components/admin/featured-image-field.tsx"],"names":[],"mappings":"AAMA,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,SAAS,GACV,EAAE,uBAAuB,2CA6GzB"}

package/dist/components/admin/featured-image-field.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { cn } from "hazo_ui/utils";
+import { ImageIcon, TrashIcon, UploadIcon } from "../icons.js";
+const inputCls = "w-full rounded-lg border border-border bg-background px-3 py-2 text-sm outline-none focus:ring-2 focus:ring-primary";
+export function FeaturedImageField({ value, onChange, uploader, className, }) {
+    const [uploading, setUploading] = useState(false);
+    const [error, setError] = useState("");
+    const [dragOver, setDragOver] = useState(false);
+    const fileInputRef = useRef(null);
+    async function handleFile(file) {
+        if (!file || !uploader)
+            return;
+        setUploading(true);
+        setError("");
+        try {
+            const url = await uploader(file);
+            if (url) {
+                onChange(url);
+            }
+            else {
+                setError("Upload failed — try again or paste a URL below.");
+            }
+        }
+        finally {
+            setUploading(false);
+        }
+    }
+    function onDrop(e) {
+        e.preventDefault();
+        setDragOver(false);
+        if (!uploader)
+            return;
+        void handleFile(e.dataTransfer.files?.[0]);
+    }
+    return (_jsxs("div", { className: cn("space-y-2", className), children: [_jsx("label", { className: "mb-1 block text-sm font-medium", children: "Featured image" }), value ? (_jsxs("div", { className: "flex items-start gap-3", children: [_jsx("img", { src: value, alt: "Featured", className: "h-24 w-24 rounded-lg border border-border object-cover" }), _jsxs("button", { type: "button", onClick: () => onChange(""), className: "inline-flex items-center gap-1.5 rounded-lg border border-border px-3 py-1.5 text-sm font-medium hover:bg-accent", children: [_jsx(TrashIcon, { width: 16, height: 16 }), "Clear"] })] })) : (_jsxs("div", { onDragOver: (e) => {
+                    if (!uploader)
+                        return;
+                    e.preventDefault();
+                    setDragOver(true);
+                }, onDragLeave: () => setDragOver(false), onDrop: onDrop, className: cn("flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed border-border bg-muted px-4 py-8 text-center", dragOver && "border-primary bg-accent"), children: [_jsx(ImageIcon, { width: 28, height: 28, className: "text-muted-foreground" }), _jsx("p", { className: "text-sm text-muted-foreground", children: uploader ? "Drag & drop an image, or" : "No image set — paste a URL below" }), uploader && (_jsxs("button", { type: "button", disabled: uploading, onClick: () => fileInputRef.current?.click(), className: "inline-flex items-center gap-1.5 rounded-lg border border-border px-3 py-1.5 text-sm font-medium hover:bg-accent disabled:opacity-50", children: [_jsx(UploadIcon, { width: 16, height: 16 }), uploading ? "Uploading…" : "Upload"] }))] })), uploader && (_jsx("input", { ref: fileInputRef, type: "file", accept: "image/*", className: "hidden", onChange: (e) => {
+                    void handleFile(e.target.files?.[0]);
+                    e.target.value = "";
+                } })), error && _jsx("p", { className: "text-sm text-destructive", children: error }), _jsx("input", { className: inputCls, value: value, onChange: (e) => onChange(e.target.value), placeholder: "https://\u2026" })] }));
+}

package/dist/components/admin/post-form.d.ts

@@ -10,9 +10,23 @@ export interface PostFormProps {
     onSaved?: (result: unknown) => void;
     /** MDX embeds offered in the editor toolbar (host can extend). */
     embeds?: MarkdownEmbed[];
-    /** Paste-to-upload handler wired to hazo_files by the host. */
+    /**
+     * Paste-to-upload handler wired to hazo_files by the host. Takes
+     * precedence over `imageUploadEndpoint` when both are provided (back-compat
+     * for existing callers).
+     */
     onImageUpload?: (file: File) => Promise<string | null>;
+    /**
+     * Route to POST image uploads to (see `createBlogImageUploadRoute` in
+     * ../../next/image-upload.ts). Ignored if `onImageUpload` is provided.
+     * When neither is set, the form falls back to URL-only mode.
+     */
+    imageUploadEndpoint?: string;
+    /** Injectable fetch for the built-in uploader, defaults to global `fetch`. */
+    fetchFn?: (path: string, init?: RequestInit) => Promise<Response>;
+    /** Called when the host-provided "Cancel" affordance is clicked (e.g. to close a modal). */
+    onCancel?: () => void;
     className?: string;
 }
-export declare function PostForm({ post, categories, endpoint, onSaved, embeds, onImageUpload, className, }: PostFormProps): import("react/jsx-runtime").JSX.Element;
+export declare function PostForm({ post, categories, endpoint, onSaved, embeds, onImageUpload, imageUploadEndpoint, fetchFn, onCancel, className, }: PostFormProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=post-form.d.ts.map

package/dist/components/admin/post-form.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"post-form.d.ts","sourceRoot":"","sources":["../../../src/components/admin/post-form.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EAGtB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,IAAI,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACpC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,kEAAkE;IAClE,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgBD,wBAAgB,QAAQ,CAAC,EACvB,IAAI,EACJ,UAAe,EACf,QAA4B,EAC5B,OAAO,EACP,MAAuB,EACvB,aAAa,EACb,SAAS,GACV,EAAE,aAAa,2CA+Mf"}
+{"version":3,"file":"post-form.d.ts","sourceRoot":"","sources":["../../../src/components/admin/post-form.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7D,OAAO,KAAK,EACV,YAAY,EACZ,qBAAqB,EAGtB,MAAM,sBAAsB,CAAC;AAI9B,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,IAAI,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACpC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,kEAAkE;IAClE,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;IACzB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvD;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgBD,wBAAgB,QAAQ,CAAC,EACvB,IAAI,EACJ,UAAe,EACf,QAA4B,EAC5B,OAAO,EACP,MAAuB,EACvB,aAAa,EACb,mBAAmB,EACnB,OAAO,EACP,QAAQ,EACR,SAAS,GACV,EAAE,aAAa,2CAiOf"}