domfx
Add or troubleshoot domfx effects in an application, including effect choice, automatic animation, GSAP sequences, teardown, capture refresh and unavailable output. Use for consuming @domfx/browser and the optional @domfx/gsap helpers, not for developing domfx internals.
- License 许可
- MIT
- 所属仓库
- G0m1namm/domfx
- 最近更新
- 2026-11-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- domfx
- license
- MIT
- description
- Add or troubleshoot domfx effects in an application, including effect choice, automatic animation, GSAP sequences, teardown, capture refresh and unavailable output. Use for consuming @domfx/browser and the optional @domfx/gsap helpers, not for developing domfx internals.
02 资源文件 3
- 参考文档references/diagnosis.md4.8 KB
- 参考文档references/frameworks.md1.6 KB
- 参考文档references/gsap.md3.1 KB
03 SKILL.md 正文
domfx
Decorate a live element while keeping its original content, focus and interaction. Write explanations and code comments in the user's language; keep API names unchanged.
Check the installed contract
Inspect the app's manifest, lockfile and installed versions of @domfx/browser and,
when used, gsap and @domfx/gsap before choosing APIs. Do not add @domfx/core to
the install. Use the same version of every @domfx package.
This skill can describe options newer than the installed release. Check the installed
public declarations and matching documentation before using an option; explain a
mismatch rather than inventing exports or upgrading dependencies silently.
For a new installation, use the exact package versions in the public
installation guide.
Import from @domfx/browser; the published build already includes its shader transform.
No repository checkout, private imports or consumer TypeGPU plugin is needed.
Do not import @domfx/browser/experimental in app code; it can change in any
release. Replace APIs marked @deprecated with the replacement their note names. See
the stability policy.
Choose an attachment from the effect catalog.
attachFire, attachFrost and attachDither share controls, but effect-specific
options differ: remove the previous effect's geometry options when switching effects.
Read that effect's public options instead of deriving an export name from its label.
Choose strength and extent
When installed declarations expose relative options, choose the effect-owned fields:
| Effect | Creation options and reference dimension |
|---|---|
| Fire | flameReach: physical height |
| Frost | coatingDepth: shorter side; mistReach: height |
| Slime | coatingDepth: shorter side; dripReach: height |
| Burned paper | scorchDepth: shorter side; ashReach: height |
| Electricity | contourSpread: shorter side |
| Kinetic bloom | fragmentTravel: shorter side |
| Dither and shared-flow patterns | plumeReach: height; bandDepth: shorter side |
| Contour echoes | echoReach: shorter side |
| Brush fringe | fringeReach: shorter side |
Slime also accepts creation-only dripDensity (0–1, default 0.56): a normalized
density, independent of size, travel and timing. Zero disables drips; higher values
add more locations, including extra emission locations above the default. It works
in the Default appearance and relative modes and does not opt into relative geometry by itself.
When installed declarations expose ColorAttachmentOptions, every effect except
Burned paper accepts one optional main decorative color. Use #RGB, #RRGGBB,
rgb(...) or rgba(..., 1); the typed ColorEffectHandle.color getter returns
normalized rgb(...). Omit color, or assign undefined, to preserve or restore
the effect's original colors. Color writes render on the next frame without a recapture.
When installed declarations expose ColorRampEffectHandle, Fire also accepts rootColor
(base of the flame) and tipColor (ends of the flame and embers), as creation options and
writable properties in the same format. They exclude color: using both throws
invalid-fire-parameter and keeps the prior value, so assign undefined first to switch.
An unset side uses Tip #ff1701 or Root #fff5a3 and reads as undefined; neither set
keeps today's output. Colors blend in sRGB, so complementary pairs pass through gray at
their midpoint; suggest closer hues if that looks wrong. For GSAP, assign an explicit color,
then use fromTo(). Other effects do not expose the pair.
Keep creation and writable semantics distinct. Frost mistOpacity and Burned paper
emberGlow are writable normalized values (default 1): assignments clamp to 0–1,
render on the next frame and do not recapture. mistOpacity changes only Frost's
mist, not the whole effect intensity. Invalid writes throw and retain the previous
value. Fire emberDensity is creation-only (finite 0–1, default 1); dispose before
replacement to change it. The typed Fire handle exposes the resolved creation value
as read-only.
Relative extents are finite nonnegative numeric fractions of the untransformed target border
box, excluding capture padding; transparent image margins count. 0.1 means 10%,
not 10 pixels. Resolve again after resize. All omitted keeps the Default appearance;
with paired options, supplying either enables relative mode and the missing partner
is zero. All-zero extents produce transparent output.
In relative mode, intensity scales final premultiplied strength without changing
configured geometry or local fine detail. Animate intensity normally, including
with GSAP. Extents are creation-only: dispose and recreate to change them; there
are no geometry setters. Reach is an envelope, not a guaranteed visible tip, and
fixed marks can extend beyond their sampling envelope within reserved support.
Relative capture requires contained descendant boxes and paint inside the border box plus 2 CSS pixels, without shadows, filters, outlines or generated pseudo-elements. Existing pixel/memory/device limits still apply; oversized support is unavailable, never silently clipped or downsampled. Use the matching per-effect reference for exact support limits. If the installed release lacks these fields, use its earlier options and explain the version requirement instead of claiming npm support.
Attach and own the lifetime
Use the complete standalone walkthrough
with the HTML setup.
In React or Vue, read framework recipes.
For Spanish requests, link the equivalent guides under https://domfx.dev/docs/es/.
- The target is the element whose visible shape receives the effect. The effect
container is
host: a separate, positioned HTML element (position: relativeis sufficient). Both must be connected to the same document, with the target a strict descendant of the host. Leave room for the decoration. - Keep the original DOM visible and interactive. The canvas is decoration, not a replacement, screenshot UI or accessibility tree. Fade the host to fade both together; target/intermediate opacity, filters and blending have composition limits.
- One effect owns a target tree: another attachment on that target, an ancestor or a descendant conflicts. Dispose the existing effect before replacing it.
- Register cleanup synchronously on component unmount before any await, including
document.fonts.ready, imports or other setup waits. Apagehidelistener alone does not handle component unmount. Keep a disposed flag and check it after waits, before creating effects or starting animations. If an async operation returns an effect after teardown, dispose that late result immediately. - Cleanup stops owned animations, unsubscribes owned listeners and calls
effect.dispose(), including whileeffect.readyis pending. On remount, use fresh elements, state and an effect; disposal is terminal and safe to repeat.
Choose the time owner
For automatic animation, pass clock: 'auto' and motion: 'respect'.
Use pause() and resume(); resuming does not catch up hidden or paused time.
For seeking or GSAP, pass clock: 'manual' at attachment. Write effect.time
in absolute seconds, forward or backward; resume() does not advance manual time.
Manual paused stays true even while setters change. Use one driver per property.
Time and intensity must be finite and float32-representable; accepted intensity clamps to 0–1.
Control writes are batched for the next frame and do not recapture the target.
For a caller-owned GSAP sequence, read GSAP ownership. Native property tweens are the ordinary path; snapshot helpers are optional.
Refresh or recover
ready resolves when an initialization attempt finishes, including unavailability;
it does not prove visible output. Inspect lifecycle, raster, reason and
reasonDetail. Use the reason code for branching and the detail for diagnostics.
Minor releases can add EffectReason, CaptureErrorCode and EffectName values:
keep a default branch for unknown values, and never branch on reasonDetail wording.
After changing captured paint, await refresh(). It hides stale output and resolves
when this or a newer requested capture is accepted; it can reject. Observed target
mutations and resize can refresh automatically. Unobserved stylesheet, ancestor,
hover/focus or canvas paint changes need explicit refresh.
For an unavailable effect, correct the condition, then explicitly await retry()
and inspect state again. Retry retains controls and bindings; it is not an automatic
loop and cannot repair invalid shaders. Refresh cannot recover an unavailable effect.
Retry rejects after disposal; create a new effect on remount.
For missing, stale or misplaced output, read diagnosis. Check original interaction, early teardown/remount and the requested animation in the consumer app. A successful build does not establish visible GPU output or broad browser support; report what was actually observed.
04 同仓库更多 Skills
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
wayfinder
Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
wait-what
Stop. That last message did not land: re-pitch it.
triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
to-tickets
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker).