Preact Weapon

preact-weapon

Procedural arsenal for preact-guardian — the Legion Army's Preact 11 specialist. This weapon 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 weapon applies

Load this weapon 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-guardian.
• Next.js App Router configuration → react-guardian (and warn: preact/compat + App Router is a footgun).
• Deno DevOps beyond Fresh (deploy configs, Docker, etc.) → devops-guardian.
• Design system or token decisions → ux-ui-guardian.

Scenario classification (read first)

Before applying any guide, classify the incoming request:

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

Critical directives

These are non-negotiables for preact-guardian. 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-guardian for React architecture. Why: the two guardians share JSX surface but own different mental models; crossing produces contradictory advice.

Version anchors (May 2026)

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

Folder layout

preact-weapon/
├── 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 weapon-forge from preact-guardian-command-brief.md and research/. Part of the Legion AI Tools Factory by Mario Aldayuz a.k.a @thenotoriousllama.