Last Updated: 2026-06-28 Status: Active
Lives between sdk-reference.md (ground-truth reference) and the forward-looking visions (integration-friction-vision.md, layouts-vision.md, hosted-blog-vision.md). A living queue of bugs/improvements from consumer-integration sessions — items too small for their own vision doc but worth tracking between releases.
Scorecard
Audited 2026-06-28 against packages/blog-sdk source at @vlozi/blog@2.1.6. Overall: 9.0 / 10
The SDK is the strongest codebase in the platform. The headless client design, error hierarchy, SWR caching model, and TypeScript coverage are all best-in-class. The main gaps are missing quality-of-life features (TOC hook, copy button, Atom feed) and two untested components (Carousel, MermaidBlock) blocked by jsdom limitations.
| Parameter | Score | Notes |
|---|---|---|
| API Design | 9.5 | Headless client with all operations, never throws on API errors, good abort support |
| TypeScript Quality | 9.5 | Comprehensive error hierarchy, discriminated unions, all exports typed |
| Error Handling | 9.5 | VloziError → VloziApiError → VloziAuthError/VloziRateLimitError hierarchy; descriptive fields |
| Resilience | 9.0 | Retry with exponential backoff, timeout, AbortSignal, in-flight deduplication |
| Caching | 9.0 | InMemoryCache + SWR window (5×TTL), custom CacheAdapter interface, invalidate/mutate |
| React Integration | 8.5 | 10 hooks with isFetching/isStale, 11+ components, server components; Carousel/Mermaid untested |
| Security (sanitizer) | 9.0 | Fixed-point iteration (5 passes), iframe allowlist, defense-in-depth model |
| Next.js Integration | 9.0 | ISR tags, generateStaticParams, generateMetadata, revalidation helper |
| Test Coverage | 8.0 | 89% overall; Carousel ~2%, MermaidBlock ~2% (jsdom limitation) |
| Feature Completeness | 8.5 | Core + RSS/sitemap + archive + related + neighbors; missing TOC hook, copy button, Atom |
| Internal Docs | 9.5 | sdk-reference.md, sdk-security-model.md, ai-integration-prompt.md, sdk-backlog.md all excellent |
| DX / Ergonomics | 9.0 | 4 entry points, VloziProvider, skeletons, stable hook refs; VloziConfig naming collision |
1. What just shipped — 2.1.6 ✅ (live on npm)
| Bug | Severity |
|---|---|
Mermaid hydration broken in browsers (new Function shim) |
High (regression from 2.1.5) |
| YouTube watch-URL + narrow allowlist + phantom 16:9 wrapper | High |
<p> margin-top leaking into task lists / callouts / blockquotes |
Medium (UX) |
| Syntax-highlight CSS without a tokenizer | Medium |
| 6-pack: image hydration + transformHtml + controlled search + prefetch parity + skeletons + post.id removal | Medium-Mixed |
Published. SDK 336+ tests ✅. Both databases connected. Deployed alongside blog-service Worker (YouTube URL normalization + server-side lowlight tokenization).
2. Deferred — sized and ready to pull
Items that have been triaged and have a concrete plan but aren't slotted into a release yet. Each is a complete picture: scope + estimate + where to start.
Slottable into 2.1.7 (next patch / minor)
| # | Item | Scope | Estimate | Source |
|---|---|---|---|---|
| B1 | <BlogPostingJsonLd post={post} /> SEO helper |
Add to @vlozi/blog/next — a small JSX component that emits <script type="application/ld+json"> with the BlogPosting schema for the given post. Auto-derives URL, image, datePublished, etc. |
~30 lines | W2 (final review) |
| B2 | Mermaid host-theme class observer | Built-in mermaidTheme: "follow-html-class" mode that watches <html>'s dark class via MutationObserver and re-renders. Function form already covers this — this is ergonomics for the shadcn / next-themes audience. |
~10 lines | W6 (final review) |
| B3 | Webhook helper for ISR revalidation | import { handleWebhook } from "@vlozi/blog/next" — generic handler consumers mount at /api/vlozi-webhook to revalidate paths/tags on publish. |
~20 lines | W9 (final review) |
| B4 | RSS Atom variant | generateAtom({ client, ... }) mirroring the existing generateRSS. RSS already exists; Atom is a small variant. |
~30 lines | W5 follow-up (final review) |
| B5 | Atomic copy button on <pre> blocks |
Auto-injected by <BlogContent> on hover, "Copied" feedback for 1.5s. Standard 2026 expectation in dev blogs. |
~50 lines (DOM walk + Clipboard API + animation timing) | Final review (Idea 4a, deferred earlier) |
Slottable into 2.2.0 (layouts MVP — already planned)
| # | Item | Scope | Notes |
|---|---|---|---|
| B6 | usePostHeadings(slug) for TOC |
Hook returns { id, level, text }[] derived from post body. Pairs naturally with layouts that have a sidebar. |
DX-E (final review). The body-headings derivation is parsing the same HTML the renderer already produced. |
| B7 | All of layouts-vision.md |
Editorial + Minimal MVP, <VloziBlogSite> umbrella, token system, dashboard picker, telemetry. |
~3.5 weeks per the layouts vision. |
Substantial / own vision doc when prioritized
| # | Item | Why it deserves its own doc |
|---|---|---|
| B8 | Sanitizer DOMParser refactor | Real perf + correctness improvement (~10× faster on long posts). But: DOMParser is browser-only; the sanitizer also runs server-side in <ServerBlogPost> (Workers + Node have no DOMParser). Needs threat-modeling, perf benchmark, and a parser choice (parse5 / linkedom / htmlparser2). |
| B9 | Multi-provider embeds (Twitter / X, Vimeo, Spotify, Instagram, CodePen, Gist) | Each provider is editor extension + renderer + sanitizer + test. Substantial work. |
| B10 | Author pages — client.blog.authors.list/.get + usePostsByAuthor |
API surface extension; needs blog-service backend support first. |
| B11 | Draft preview mode (?preview=true API token) |
Common headless-CMS pattern; needs preview-token API + dashboard preview link UI. |
| B12 | All of hosted-blog-vision.md |
<tenant>.vlozi.app/blog + custom-domain CNAME via Cloudflare for SaaS. |
| B13 | npx @vlozi/blog setup CLI |
Big lever for technical-customer onboarding. |
| B14 | Content importers (Substack / Medium / WordPress / Ghost / Notion / dev.to / RSS / Markdown) | Big lever for switching from competitors. |
Testing infrastructure
| # | Item | Why |
|---|---|---|
| B15 | End-to-end smoke test of <BlogContent> with a fixture post containing every documented feature |
The "half-shipped feature" pattern (mermaid CSS without runtime, syntax CSS without tokenizer, empty wrappers from sanitization) keeps recurring. A jsdom + Playwright integration test that renders a fixture post containing every documented feature and asserts the final DOM would catch all three. ~half-day to set up; permanent regression net. |
| B16 | Set up vitest in apps/seller-dashboard |
The Phase 0 markdown-importer YouTube fix couldn't ship unit tests because seller-dashboard has no test runner. Same applies to any future seller-dashboard utility/component logic. |
| B17 | Convert remaining *.stories.tsx Storybook fixtures off Tailwind |
Phase 2.1 (Tailwind decoupling) shipped for production components; some Storybook stories still reference Tailwind utility classes in user-demo wrappers. Storybook QA in CI breaks if Tailwind setup isn't there. |
Cosmetic / pure docs
| # | Item | Status |
|---|---|---|
| B18 | Update books-vision.md with a layout-chrome integration note |
Light touch when books actually start. |
| B19 | data-vlz-syntax="default" set even when no tokens exist |
Cosmetic only. After 2.1.6 syntax-highlighting fix, posts with code blocks DO have tokens; posts without are unaffected (CSS rules match nothing — zero perf cost). No-action. |
| B20 | Cross-page cache verification | The SDK's cache should already persist across navigations (module-singleton client). Reporter flagged it as a possible re-fetch issue. Worth a Storybook scenario verifying behavior, not a refactor. |
| B21 | generateStaticParamsForPosts parallelization |
Currently paginates sequentially in 100-post batches. For blogs over ~1000 posts, build time scales linearly. Perf, not correctness. |
3. Already shipped — clarifications for the consumer reporter
Items the reporter listed that were already in the SDK; worth flagging in the next round-trip so the wishlist focus stays on the real gaps.
| Item | Where it lives | Note |
|---|---|---|
| Sitemap helper | generateSitemap in @vlozi/blog |
feeds.ts:168. README documents it. |
| RSS feed builder | generateRSS in @vlozi/blog |
feeds.ts:67. README documents it. Atom variant is on the queue (B4). |
| Reading-time fallback | estimateReadingTime in client.ts |
client.ts:674. Runs automatically when post.readingTime is missing — consumer doesn't call it. |
4. Not on the roadmap (forever)
Things explicitly out of scope. Worth listing so the answer to "could we add..." is consistent.
- WYSIWYG layout editor — the layout system is opinionated by design. (Per
layouts-vision.md§16.) - Drag-drop blog page builder — same.
- AI-generated layouts from a screenshot — demo magic; unmaintainable.
- User-contributed layouts as a free open-contribution surface — six layouts forever. (
layouts-vision.md§16.) - Per-post layout overrides — confuses readers, breaks RSS, breaks OG cache.
5. How to maintain this doc
- When a B-item gets prioritized, pull it out into a focused commit + changeset, then delete the row from this doc.
- When a new bug/improvement comes in from a consumer integration, add it to the appropriate "Slottable" section.
- When something gets large enough to need its own vision doc, move it to "Substantial / own vision doc."
- When the queued 2.1.6 ships, this section becomes "What just shipped — 2.1.6 (live)" and a new "What just shipped — 2.1.7" section opens above it.
This doc should never grow indefinitely — items leave when shipped, when scope-rejected, or when promoted to vision docs.