preact-stinger

Procedural arsenal for preact-worker-bee, the Hive's Preact 11 specialist. This stinger encodes the opinionated decision framework, the signals API (v2), the preact/compat compatibility surface, the third-party embed pattern, and the Astro/Fresh integration playbooks.

First-read priority: Start with guides/00-when-to-choose-preact.md. If you have already classified the scenario, jump to the relevant guide. The research summary is at research/research-summary.md.

---

When this stinger applies

Load this stinger when any of the following is true:

• The user is evaluating Preact vs React for a new project.
• The user is migrating an existing React codebase to Preact via preact/compat.
• The user is building a third-party embed widget and bundle size is a constraint.
• The user is working in an Astro project and wants to use Preact islands.
• The user is working in a Fresh 2.x project.
• The user has Preact code to review, debug, or refactor.
• The user asks about signals (signal, computed, effect, createModel).

Do NOT load for:

• Pure React architecture questions → react-worker-bee.
• Next.js App Router configuration → react-worker-bee (and warn: preact/compat + App Router is a footgun).
• Deno DevOps beyond Fresh (deploy configs, Docker, etc.) → devops-worker-bee.
• Design system or token decisions → ux-ui-svelte-worker-bee.

---

Scenario classification (read first)

Before applying any guide, classify the incoming request:

Scenario	Key signal	Primary guide
New project, evaluating Preact	"should I use Preact?", bundle size target, no existing React code	guides/00-when-to-choose-preact.md
Signals authoring	"signals", "signal()", "computed()", "createModel"	guides/01-signals-api.md
React-to-Preact migration	existing React codebase, preact/compat, alias setup	guides/02-compat-migration.md
Third-party embed widget	"embed", "third-party script", "widget", shadow DOM, bundle budget	guides/03-embed-widget.md
Astro integration	@astrojs/preact, client:* directives, Astro project	guides/04-astro-integration.md
Fresh framework	Fresh, Deno, islands/, deno.json	guides/05-fresh-framework.md

If the scenario is ambiguous, ask one targeted clarifying question before diving into code.

---

Critical directives

These are non-negotiables for preact-worker-bee. Each has a one-line "why".

• Never recommend Preact without naming the concrete benefit. Why: "smaller bundle" is not a reason; the specific size delta, embed constraint, or signals preference must be stated.
• Always check preact/compat compatibility before migrating. Why: React 19 use(), useTransition, RSC, and @types/react each break compat silently or noisily.
• @types/react must NEVER be installed alongside preact/compat. Why: type conflicts are pervasive and hard to debug; use preact's built-in types only.
• Next.js App Router + preact/compat = footgun. Stop and warn. Why: RSC requires React's fiber; compat wraps but does not replace it, producing silent failures.
• Scope signals to the specific use case. Why: mixing naive useState patterns with signals produces tracking bugs; the mental model shift must be explicit.
• Defer to react-worker-bee for React architecture. Why: the two worker-bees share JSX surface but own different mental models; crossing produces contradictory advice.

---

Version anchors (May 2026)

Package	Stable version	Notes
preact	10.x (v11 beta)	v11 beta as of Aug 2025; check for stable
@preact/signals	2.9.0	v2 API is current
preact-custom-element	4.6.0	embed/web component wrapper
@astrojs/preact	5.1.2	require >= 5.0.1 (useId bug fixed)
Fresh	2.2.2	Vite-based; Fresh 1.x is esbuild

Source: research/internal/2026-05-20-stinger-folder-context.md

---

Folder layout

preact-stinger/
├── SKILL.md                         (this file — master index)
├── README.md                        (one-page human overview)
├── guides/
│   ├── 00-when-to-choose-preact.md  (tradeoff matrix + honest "when React wins")
│   ├── 01-signals-api.md            (v1 primitives + v2 model pattern)
│   ├── 02-compat-migration.md       (alias setup, known gaps, migration checklist)
│   ├── 03-embed-widget.md           (shadow DOM, IIFE bundle, size checklist)
│   ├── 04-astro-integration.md      (client: directives, useId fix, compat in Astro)
│   └── 05-fresh-framework.md        (islands, serializable props, signals state)
├── examples/
│   ├── happy-path-signals-component.md
│   └── compat-migration-vite.md
├── templates/
│   └── migration-checklist.md
├── reports/
│   └── README.md
└── research/                        (authored by scripture-historian — do not modify)
    ├── research-plan.md
    ├── research-summary.md
    ├── index.md
    ├── external/
    └── internal/

---

Forged by stinger-forge from preact-worker-bee-command-brief.md and research/. Part of The Hive by Mario Aldayuz a.k.a @thenotoriousllama.