Post/013 vnode

.husky/pre-commit

@@ -0,0 +1 @@
+yarn lint-staged

package.json

@@ -13,7 +13,12 @@
     "preview": "astro preview",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "format": "prettier --write ."
+    "format": "prettier --write .",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{js,ts,astro}": "eslint --fix",
+    "*": "prettier --write --ignore-unknown"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -33,6 +38,8 @@
     "@types/node": "^25.3.3",
     "eslint": "^10.0.2",
     "eslint-plugin-astro": "^1.6.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
     "typescript": "^5.9.3",

src/components/ReadNext.astro

@@ -1,32 +1,46 @@
 ---
 import PostCard from './PostCard.astro';
-import ReadNextCard from './ReadNextCard.astro';
 import type { CollectionEntry } from 'astro:content';
 
 interface Props {
   currentSlug: string;
-  tags: string[];
   relatedPosts: CollectionEntry<'posts'>[];
   prevPost?: CollectionEntry<'posts'> | null;
   nextPost?: CollectionEntry<'posts'> | null;
 }
 
-const { currentSlug, tags, relatedPosts, prevPost, nextPost } = Astro.props;
-const showRelatedPosts = relatedPosts.length > 1;
-const hasContent = showRelatedPosts || prevPost || nextPost;
+const { currentSlug, relatedPosts, prevPost, nextPost } = Astro.props;
+
+const MAX_CARDS = 3;
+const seen = new Set<string>([currentSlug]);
+const cards: CollectionEntry<'posts'>[] = [];
+
+for (const post of relatedPosts) {
+  if (cards.length >= MAX_CARDS) break;
+  if (!seen.has(post.id)) {
+    seen.add(post.id);
+    cards.push(post);
+  }
+}
+
+for (const post of [prevPost, nextPost]) {
+  if (cards.length >= MAX_CARDS) break;
+  if (post && !seen.has(post.id)) {
+    seen.add(post.id);
+    cards.push(post);
+  }
+}
 ---
 
 {
-  hasContent && (
+  cards.length > 0 && (
     <aside class="read-next">
       <div class="read-next-inner">
         <h3 class="read-next-heading">Read Next</h3>
         <div class="read-next-feed">
-          {showRelatedPosts && (
-            <ReadNextCard currentSlug={currentSlug} tags={tags} relatedPosts={relatedPosts} />
-          )}
-          {prevPost && <PostCard post={prevPost} />}
-          {nextPost && <PostCard post={nextPost} />}
+          {cards.map(post => (
+            <PostCard post={post} />
+          ))}
         </div>
       </div>
     </aside>

src/content/posts/013-shades-vnode-refactor.md

@@ -0,0 +1,90 @@
+---
+title: 'Shades 12: The VNode Refactor'
+author: [gallayl]
+tags: ['shades']
+date: '2026-03-05T18:00:00.000Z'
+draft: false
+image: img/013-vnode.jpg
+excerpt: Shades v12 replaces the rendering engine with a VNode-based reconciler and drops lifecycle callbacks in favor of hooks — here's the full story.
+---
+
+## Why rewrite the renderer
+
+Shades had a beautifully dumb rendering model: your `render()` function spits out real DOM elements, the framework diffs them against what's already on screen, and patches the differences. Simple, honest, easy to reason about... and wasteful. Every single render cycle spun up a full shadow DOM tree _just to throw it away after comparison_. That's a lot of garbage collection for what often boils down to changing one text node.
+
+v12 rips that out and replaces it with a **VNode-based reconciler**. Now the JSX factory produces lightweight descriptor objects — plain JS, no DOM involved. The reconciler diffs the old VNode tree against the new one and pokes the real DOM only where something actually changed. No throwaway trees. No phantom elements. Just surgical updates.
+
+## Hooks in, lifecycle callbacks out
+
+The old API had three separate lifecycle hooks: `constructed`, `onAttach`, and `onDetach`. Three places to scatter your setup and teardown logic, three sets of timing semantics to keep in your head. In v12, they're all gone — consolidated into one composable primitive: **`useDisposable`**.
+
+```typescript
+// Before — lifecycle spaghetti
+Shade({
+  shadowDomName: 'my-component',
+  constructed: ({ element }) => {
+    const listener = () => { /* ... */ }
+    window.addEventListener('click', listener)
+    return () => window.removeEventListener('click', listener)
+  },
+  render: () => <div>Hello</div>,
+})
+
+// After — setup and cleanup live together, right where you use them
+Shade({
+  shadowDomName: 'my-component',
+  render: ({ useDisposable }) => {
+    useDisposable('click-handler', () => {
+      const listener = () => { /* ... */ }
+      window.addEventListener('click', listener)
+      return { [Symbol.dispose]: () => window.removeEventListener('click', listener) }
+    })
+    return <div>Hello</div>
+  },
+})
+```
+
+The `element` parameter is also gone. Reaching into the host element and mutating it imperatively was always a bit... rebellious for a declarative framework. Say hello to **`useHostProps`** instead — it lets you declare attributes, styles, CSS custom properties, ARIA attrs, and event handlers without ever touching the DOM yourself:
+
+```typescript
+render: ({ useHostProps, props }) => {
+  useHostProps({
+    'data-variant': props.variant,
+    style: { '--color': colors.main },
+  })
+  return <button>{props.label}</button>
+}
+```
+
+And for those moments when you _do_ need a handle on a child element (focusing an input, measuring a bounding rect), there's **`useRef`** — no more `querySelector` treasure hunts through the shadow DOM:
+
+```typescript
+render: ({ useRef }) => {
+  const inputRef = useRef<HTMLInputElement>('input')
+  return <input ref={inputRef} />
+  // Later: inputRef.current?.focus()
+}
+```
+
+## Batched updates (a.k.a. stop re-rendering so much)
+
+`updateComponent()` used to be synchronous. Fire three observable changes in a row? Enjoy your three render passes. In v12, updates go through `queueMicrotask` and get coalesced — hammer as many observables as you want within a synchronous block and the component renders _once_. The new `flushUpdates()` utility lets tests await pending renders properly, so you can finally delete those sketchy `sleepAsync(50)` calls.
+
+## SVG — for real this time
+
+Shades now handles SVG elements as first-class citizens. Elements are created with `createElementNS` under the correct namespace, attributes go through `setAttribute` instead of property assignment (because SVG is picky like that), and there's a full set of typed interfaces covering shapes, gradients, filters, and animations. Your editor's autocomplete will thank you.
+
+## Migration cheat sheet
+
+| Gone                            | Use this instead                         |
+| ------------------------------- | ---------------------------------------- |
+| `constructed` callback          | `useDisposable` in `render`              |
+| `element` in render options     | `useHostProps` hook                      |
+| `onAttach` / `onDetach`         | `useDisposable`                          |
+| Synchronous `updateComponent()` | Async batched updates + `flushUpdates()` |
+
+## What's next
+
+The v12.x train keeps rolling — we've already shipped dependency tracking for `useDisposable`, a `css` property for component-level styling with pseudo-selectors, and a brand new routing system. Stay tuned for a dedicated post on the `NestedRouter`.
+
+Want to take it for a spin? `npm install @furystack/shades@latest` and check the [changelog](https://github.com/furystack/furystack/blob/develop/packages/shades/CHANGELOG.md#1220---2026-02-22) for all the gory details.

src/layouts/PostLayout.astro

@@ -89,7 +89,6 @@ const primaryTag = tags?.[0];
 
   <ReadNext
     currentSlug={post.id}
-    tags={tags || []}
     relatedPosts={relatedPosts}
     prevPost={prevPost}
     nextPost={nextPost}

src/pages/posts/[...slug].astro

@@ -13,10 +13,21 @@ export async function getStaticPaths() {
   return sorted.map((post, index) => {
     const prev = index > 0 ? sorted[index - 1] : null;
     const next = index < sorted.length - 1 ? sorted[index + 1] : null;
-    const primaryTag = post.data.tags?.[0];
-    const relatedPosts = primaryTag
-      ? sorted.filter(p => p.data.tags?.includes(primaryTag) && p.id !== post.id)
-      : [];
+    const currentTags = post.data.tags ?? [];
+    const relatedPosts =
+      currentTags.length > 0
+        ? sorted
+            .filter(p => p.id !== post.id && p.data.tags?.some(t => currentTags.includes(t)))
+            .map(p => ({
+              post: p,
+              overlap: (p.data.tags ?? []).filter(t => currentTags.includes(t)).length,
+            }))
+            .sort(
+              (a, b) =>
+                b.overlap - a.overlap || b.post.data.date.valueOf() - a.post.data.date.valueOf(),
+            )
+            .map(r => r.post)
+        : [];
     const authorData = post.data.author
       .map(authorId => authors.find(a => a.data.id === authorId)?.data)
       .filter(Boolean);