sinapse-ai 1.24.0 → 1.25.0

package/bin/utils/validate-publish.js

@@ -15,31 +15,64 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execFileSync, execSync } = require('child_process');
 
 const PROJECT_ROOT = path.join(__dirname, '..', '..');
 const MIN_FILE_COUNT = 50;
 
+function isNewerVersion(candidate, current) {
+  const left = String(candidate).replace(/^v/, '').split(/[.-]/).slice(0, 3).map(Number);
+  const right = String(current).replace(/^v/, '').split(/[.-]/).slice(0, 3).map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const delta = (left[i] || 0) - (right[i] || 0);
+    if (delta !== 0) return delta > 0;
+  }
+  return false;
+}
+
 let passed = true;
 let fileCount = 0;
 
 console.log('--- Publish Safety Gate (INS-4.10) ---\n');
 
+// Check 0: npm never accepts re-publishing an existing version. Surface the
+// collision before the expensive package scan so release readiness stays
+// honest and operators know that a semantic version bump is still required.
+try {
+  const localVersion = require(path.join(PROJECT_ROOT, 'package.json')).version;
+  const npmCli = process.env.npm_execpath;
+  const npmExecutable = npmCli ? process.execPath : (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+  const npmArgs = npmCli
+    ? [npmCli, 'view', 'sinapse-ai', 'version']
+    : ['view', 'sinapse-ai', 'version'];
+  const publishedVersion = execFileSync(npmExecutable, npmArgs, {
+    encoding: 'utf8',
+    cwd: PROJECT_ROOT,
+    timeout: 15000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+  if (!isNewerVersion(localVersion, publishedVersion)) {
+    console.error(`FAIL: local version ${localVersion} is not newer than npm latest ${publishedVersion}.`);
+    console.error('  A semantic version bump is required before publishing.');
+    passed = false;
+  } else {
+    console.log(`PASS: local version ${localVersion} is newer than npm latest ${publishedVersion}`);
+  }
+} catch (err) {
+  console.error(`FAIL: could not verify the npm version boundary: ${err.message}`);
+  passed = false;
+}
+
 // Check 1: File count threshold via npm pack --dry-run
 try {
-  const packOutput = execSync('npm pack --dry-run 2>&1', {
+  const packOutput = execSync('npm pack --dry-run --json', {
     encoding: 'utf8',
     cwd: PROJECT_ROOT,
     timeout: 30000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 32 * 1024 * 1024,
   });
-  // npm pack --dry-run outputs lines starting with "npm notice" for each file
-  const fileLines = packOutput.split('\n').filter(line =>
-    line.includes('npm notice') && !line.includes('Tarball') && !line.includes('name:') &&
-    !line.includes('version:') && !line.includes('filename:') && !line.includes('package size:') &&
-    !line.includes('unpacked size:') && !line.includes('shasum:') && !line.includes('integrity:') &&
-    !line.includes('total files:'),
-  );
-  fileCount = fileLines.length;
+  fileCount = ((JSON.parse(packOutput)[0] || {}).files || []).length;
 
   if (fileCount < MIN_FILE_COUNT) {
     console.error(`FAIL: Package has only ${fileCount} files, expected >= ${MIN_FILE_COUNT}.`);

package/docs/framework/codex-parity/codex-native-runtime-v2.md

@@ -0,0 +1,230 @@
+# Codex Native Runtime v2
+
+## Activating SINAPSE in Codex
+
+Codex uses two complementary native surfaces:
+
+- `$skill-name` selects a discoverable skill from `.agents/skills`.
+- `.codex/agents/*.toml` defines custom agents used for native delegation.
+
+Use `$snps`, `$sinapse`, `$snps-orqx`, or `$sinapse-orqx` to enter through the
+supreme orchestrator. The 32 public SINAPSE activators are available directly,
+including `$sinapse-architect`, `$sinapse-dev`, and `$sinapse-qa`.
+
+For any specialist in the complete 172-agent catalog, use
+`$sinapse-agent <agent-id>`. The parametric activator resolves the canonical
+source at runtime and rejects unknown IDs instead of guessing. For example:
+
+```text
+$sinapse-agent meta-ads-specialist
+```
+
+`.codex/catalog.json` is the registry for this Codex activation surface. The
+native `.agents/skills` tree is mirrored to `.codex/skills` for compatibility
+with older Codex builds. Clean installs and upgrades reconcile managed files
+idempotently without deleting valid user-owned skills.
+
+The default tier deliberately exposes aliases, core agents, orchestrators and
+the parametric activator, not one selector entry per specialist. Users who need
+every agent as an individual `$` entry can opt in explicitly:
+
+```bash
+node .codex/scripts/sync-codex-native.js --expanded-skills
+```
+
+Expanded individual skills are generated only under the official
+`.agents/skills` tree. They do not duplicate or alter the 172 TOML adapters.
+
+## Purpose
+
+The Codex native runtime makes SINAPSE planning and delivery contracts available
+inside a Codex session without changing the Claude Code implementation. It is an
+additive preparation layer: canonical agents, tasks, workflows, templates, and
+checklists remain the source of truth, while Codex-specific files expose those
+contracts through native agents, skills, hooks, and deterministic resolvers.
+
+The supported preparation journey is:
+
+```text
+PRD -> Epic -> Story draft -> Story validation -> Spec -> Plan -> Development -> QA
+```
+
+Implementation remains blocked until the story is validated and Ready. Push,
+pull-request, and release authority remains exclusive to DevOps.
+
+## Project-local Codex configuration
+
+`.codex/config.toml` enables hooks, multi-agent collaboration, and goals for this
+project. Native delegation is bounded to six concurrent threads and one level of
+subagent depth. The installer copies this file into the project; it does not edit
+the user's global Codex configuration.
+
+The project config and generated agent TOMLs intentionally omit `model` and
+`model_reasoning_effort`. Model choice and reasoning effort therefore inherit the
+active Codex host or user configuration instead of being frozen by SINAPSE.
+
+## Native agents
+
+`.codex/agents/` contains two additive surfaces:
+
+- 172 Markdown pointers retained for backward compatibility and source lookup.
+- 172 native TOML custom-agent adapters generated from those pointers.
+
+Run `npm run sync:ide:codex` to synchronize both surfaces. Native synchronization
+is deterministic and idempotent, preserves every Markdown pointer, derives safe
+descriptions from canonical agent metadata, and never pins a model. The
+`snps-orqx.toml` filename remains aligned with its canonical pointer while exposing
+the public `sinapse-orqx` name and aliases.
+
+Every native adapter instructs Codex to read `AGENTS.md`, load the canonical agent
+definition, respect its authority, and resolve task commands from real files. An
+orchestrator coordinates native subagents; it does not execute specialist work or
+start a nested model process.
+
+## Native skills
+
+Current Codex skill entrypoints live under `.agents/skills/`:
+
+- `sinapse-orqx` routes requests through the supreme orchestrator.
+- `sinapse-spec-driven` prepares PRD, Epic, Story, Spec, and Plan delivery.
+- `sinapse-loop` runs an explicitly requested bounded correction loop.
+
+Equivalent `.codex/skills/` copies are compatibility entrypoints for existing
+installations. New Codex discovery should use `.agents/skills/`; both locations
+resolve the same canonical SINAPSE sources.
+
+## Hook and apply_patch bridge
+
+`.codex/hooks.json` registers session, prompt, subagent, compaction, tool, and stop
+events. `.codex/hooks/claude-compat.cjs` translates Codex events into the existing
+SINAPSE safety contract without modifying any `.claude/**` file.
+
+After installing or updating SINAPSE, start a new Codex session and run `/hooks`
+to review and trust the project hook definitions. Codex intentionally does not
+activate changed project hooks until the operator has reviewed them.
+
+For `apply_patch`, the bridge extracts every Add, Update, Delete, and Move target.
+A multi-file patch is denied in full when any target is unsafe. The bridge:
+
+- blocks L1/L2 protected-path writes;
+- blocks secret-like content without echoing the secret;
+- fails closed for malformed patches;
+- enforces DevOps-only Git push authority and protected-branch rules;
+- blocks destructive SQL such as `DROP`, `TRUNCATE`, and `ALTER ... DROP`;
+- allows safe L4 edits and authorized, explicit non-protected operations.
+
+The bridge is a Node compatibility adapter, not a Claude subprocess. Existing
+Claude guards may be invoked as policy checks when present, but the Claude runtime
+is never launched. Codex documents `PreToolUse` as a guardrail rather than a
+complete security boundary, so repository permissions and normal human review
+remain required for equivalent execution paths that hooks do not intercept.
+
+## Direct sinapse-codex commands
+
+The additive helper emits deterministic JSON work packets from project-local
+sources. It prepares work for native delegation; it does not execute domain work.
+
+When installed as an npm binary, `sinapse-codex` discovers the caller's SINAPSE
+project from the current directory (including nested project folders). The
+project-local Node path below remains available for source checkouts.
+
+```powershell
+node .codex/scripts/sinapse-codex.js doctor
+node .codex/scripts/sinapse-codex.js agent sinapse-pm
+node .codex/scripts/sinapse-codex.js command project-lead create-prd
+
+node .codex/scripts/sinapse-codex.js spec <subject> --complexity STANDARD
+node .codex/scripts/sinapse-codex.js plan <subject> --complexity STANDARD
+node .codex/scripts/sinapse-codex.js orchestrate <subject> --complexity STANDARD
+```
+
+The same operations are available as `sinapse-codex doctor`, `sinapse-codex
+spec <subject>`, `sinapse-codex plan <subject>`, and `sinapse-codex orchestrate
+<subject>` after package installation.
+
+`SIMPLE`, `STANDARD`, and `COMPLEX` select the phase profile declared by the
+canonical spec workflow. The older `workflow <spec|plan|orchestrate>` form remains
+available as a compatibility alias.
+
+`spec` emits specification phases only. `plan` includes the applicable spec phases
+and the implementation-plan and analysis gates. `orchestrate` also appends the
+declared story-delivery chain:
+
+```text
+Project Lead -> Sprint Lead draft -> Product Lead validate
+-> Developer -> Quality Gate -> DevOps
+```
+
+The helper contains no `claude` invocation and never starts `codex exec`.
+
+## Task-first precedence
+
+`.sinapse-ai/development/workflows/spec-pipeline.yaml` selects phase order,
+conditions, and complexity profiles. Each referenced task Markdown file is the
+authoritative contract for inputs, outputs, elicitation, gates, and verification.
+
+When workflow metadata and a task contract differ, the task contract wins for
+inputs, outputs, and verification. Resolved phase packets expose this decision as
+`taskFirst: true`, so delegation does not silently invent or replace canonical
+requirements.
+
+## Bounded loop
+
+The loop is opt-in. It activates only when the user explicitly requests `@loop` or
+the `sinapse-loop` skill and supplies a verifiable completion criterion.
+
+```powershell
+node .codex/scripts/sinapse-codex.js loop status
+node .codex/scripts/sinapse-codex.js loop prepare --criterion "focused tests pass"
+node .codex/scripts/sinapse-codex.js loop advance --outcome continue
+```
+
+Each iteration is `inspect -> delegate -> verify`. The loop stops immediately when
+the criterion is met, the work is blocked, the user stops it, or iteration three
+finishes. Project-local state in `.sinapse/workflow-state/codex-loop.json`
+enforces the cap and rejects a fourth advance. It never runs silently or without
+a maximum.
+
+## Install, synchronize, and validate
+
+Install from the target project and select Codex support in the installer:
+
+```powershell
+npx sinapse-ai install
+```
+
+For framework development or a source checkout:
+
+```powershell
+npm run sync:ide:codex
+npm run validate:codex-native
+npm run validate:codex-sync
+npm run validate:codex-commands
+npm run validate:codex-delegation
+npm run validate:codex-skills
+npx jest tests/integration/codex-native-golden-journey.test.js --runInBand
+```
+
+`validate:codex-native` checks project TOML, 1:1 native-agent parity, native and
+compatibility skills, command targets, delegation equivalence, hooks, and the
+absence of nested Claude/Codex execution. `validate:codex-sync` runs both the
+legacy synchronization validator and the stricter native validator.
+
+Use the project-local doctor for a machine-readable summary:
+
+```powershell
+node .codex/scripts/sinapse-codex.js doctor
+```
+
+## Claude compatibility boundary
+
+The Codex runtime is additive and must not edit `.claude/**`, protected framework
+core files, or the shared Claude-backed master orchestrator. Claude Code continues
+to use its existing agents, commands, hooks, and workflows unchanged. Canonical
+SINAPSE task and workflow files are read at runtime by both integrations, so fixes
+to project-local Codex adapters do not fork business rules or replace the Claude
+surface.
+
+Codex parity means equivalent authority, reachability, gates, and operator
+outcomes. It does not promise identical model prose or provider-specific lifecycle
+behavior.

package/docs/framework/codex-parity/codex-workflow-task-parity.md

@@ -10,7 +10,7 @@ The Codex workflow bridge now lives in:
 
 - `.codex/command-registry.json`
 
-This registry is the Codex-only contract for the critical workflow path:
+This registry is the deterministic Codex contract for the critical workflow path:
 
 - `sinapse-orqx`
 - `sinapse-pm`
@@ -18,6 +18,12 @@ This registry is the Codex-only contract for the critical workflow path:
 - `sinapse-sm`
 - `sinapse-dev`
 - `sinapse-qa`
+- `sinapse-architect`
+- `sinapse-analyst`
+- `sinapse-devops`
+
+Agents and commands outside this curated path fall through to the parametric
+resolver, which reads their real source definitions and task dependencies.
 
 For each agent, it maps:
 
@@ -44,11 +50,14 @@ This is especially useful in Codex when a command exists in the agent persona bu
 Critical workflow coverage now includes:
 
 - Imperator: `onboard`, `route`, `plan`, `status`, `brief`, `resolve`, `council`
-- PM: `create-prd`, `create-brownfield-prd`, `create-epic`, `create-story`, `research`, `execute-epic`, `gather-requirements`, `write-spec`, `shard-prd`
+- PM: `create-prd`, `create-brownfield-prd`, `create-epic`, `create-story`, `research`, `execute-epic`, `gather-requirements`, `write-spec`, `clarify-spec`, `create-spec`, `shard-prd`
 - PO: `validate-story`, `validate-story-draft`, `backlog-review`, `backlog-prioritize`, `backlog-schedule`, `close-story`, `execute-checklist-po`, `sync-story`, `pull-story`, `stories-index`
 - SM: `draft`, `story-checklist`
 - Developer: `develop`, `run-tests`, `apply-qa-fixes`, `execute-subtask`, `verify-subtask`, `backlog-debt`, build commands
-- QA: `review`/`review-story`/`code-review`, `gate`, `review-build`, `create-fix-request`, `test-design`, `run-tests`, `nfr-assess`, `validate-libraries`, `security-check`, `validate-migrations`, `evidence-check`, `false-positive-check`, `console-check`
+- Architect: `assess-complexity`, `create-plan`, `create-context`
+- Analyst: `research-deps`
+- QA: `review`/`review-story`/`code-review`, `gate`, `critique-spec`, `analyze-spec`, `review-build`, `create-fix-request`, `test-design`, `run-tests`, `nfr-assess`, `validate-libraries`, `security-check`, `validate-migrations`, `evidence-check`, `false-positive-check`, `console-check`
+- DevOps: `pre-push`, `push`, `create-pr`
 
 ## Validation
 
@@ -56,6 +65,7 @@ The registry is enforced by:
 
 - `npm run validate:codex-commands`
 - `npm run validate:codex-sync`
+- `npm run validate:codex-native`
 
 The validator checks that:
 
@@ -80,8 +90,12 @@ Because the shared `sinapse-orqx` runtime is still partially broken upstream, Co
 
 These keep the workflow Codex-only and avoid risky shared-runtime edits.
 
-## Current Limit
+## Current Coverage
+
+The curated registry provides deterministic mappings for the critical delivery
+path, while the parametric resolver and native TOML adapters cover all 172 current
+agents. Spec, plan, and orchestrate preparation is resolved from canonical task
+and workflow files by `.codex/scripts/resolve-codex-workflow.js`.
 
-This layer solves deterministic command discovery and routing for the critical workflow path.
-It does not yet provide full specialist coverage across all 178 agents, and it does not replace MCP parity.
-Direct specialist routing from `.codex/agents` should still be treated as exploratory unless the path is covered by the command registry and its validators.
+MCP capabilities remain separate from agent and workflow parity. Provider output
+can differ, but authority, source artifacts, gates, and delivery order are shared.

package/docs/framework/react-bits/animations.md

@@ -0,0 +1,49 @@
+# React Bits - Animations
+
+> Snapshot oficial: `3acbd54115330a42e39f63dda2d4859e998b6684` (2026-07-14T17:21:39+03:00). Total nesta categoria: **31**.
+
+Cada item abaixo aponta para a documentacao e para o codigo TypeScript/CSS oficial fixado no commit pesquisado.
+
+| Componente                                                                                                                                                                                                      | O que faz                                                                                                                            | Dependencias                                                         | Props publicas                                                                                                                                                                                                                                                                                              | Variantes                    |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| [AnimatedContent](https://reactbits.dev/animations/animated-content) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/AnimatedContent)) | Wrapper that animates any children on scroll or mount with configurable direction, distance, duration, easing and disappear options. | `gsap@^3.13.0`                                                       | `children`, `container`, `distance`, `direction`, `reverse`, `duration`, `ease`, `initialOpacity`, `animateOpacity`, `scale`, `threshold`, `delay`, `onComplete`, `dissappearAfter`, `disappearDuration`, `disappearEase`, `onDisappearanceComplete`, `className`                                           | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [Antigravity](https://reactbits.dev/animations/antigravity) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/Antigravity))              | 3D antigravity particle field that repels from the cursor with smooth motion.                                                        | `@react-three/fiber@^9.3.0 three@^0.180.0`                           | `count`, `magnetRadius`, `ringRadius`, `waveSpeed`, `waveAmplitude`, `particleSize`, `lerpSpeed`, `color`, `autoAnimate`, `particleVariance`, `rotationSpeed`, `depthFactor`, `pulseSpeed`, `particleShape`, `fieldStrength`                                                                                | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [BlobCursor](https://reactbits.dev/animations/blob-cursor) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/BlobCursor))                | Organic blob cursor that smoothly follows the pointer with inertia and elastic morphing.                                             | `gsap@^3.13.0`                                                       | `blobType`, `fillColor`, `trailCount`, `sizes`, `innerSizes`, `innerColor`, `opacities`, `shadowColor`, `shadowBlur`, `shadowOffsetX`, `shadowOffsetY`, `filterId`, `filterStdDeviation`, `filterColorMatrixValues`, `useFilter`, `fastDuration`, `slowDuration`, `fastEase`, `slowEase`, `zIndex`          | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [ClickSpark](https://reactbits.dev/animations/click-spark) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/ClickSpark))                | Creates particle spark bursts at click position.                                                                                     | `none`                                                               | `sparkColor`, `sparkSize`, `sparkRadius`, `sparkCount`, `duration`, `easing`, `extraScale`, `children`                                                                                                                                                                                                      | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [Crosshair](https://reactbits.dev/animations/crosshair) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/Crosshair))                    | Custom crosshair cursor with tracking, and link hover effects.                                                                       | `gsap@^3.13.0`                                                       | `color`, `containerRef`                                                                                                                                                                                                                                                                                     | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [Cubes](https://reactbits.dev/animations/cubes) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/Cubes))                                | 3D rotating cube cluster. Supports auto-rotation or hover interaction.                                                               | `gsap@^3.13.0`                                                       | `gridSize`, `cubeSize`, `maxAngle`, `radius`, `easing`, `duration`, `cellGap`, `borderStyle`, `faceColor`, `shadow`, `autoAnimate`, `rippleOnClick`, `rippleColor`, `rippleSpeed`                                                                                                                           | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [CursorGrid](https://reactbits.dev/animations/cursor-grid) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/CursorGrid))                | Canvas grid whose cells light up around the cursor with configurable radius, falloff and click pulses.                               | `none`                                                               | `cellSize`, `color`, `radius`, `falloff`, `holdTime`, `fadeDuration`, `lineWidth`, `maxOpacity`, `fillOpacity`, `gridOpacity`, `cellRadius`, `clickPulse`, `pulseSpeed`, `className`                                                                                                                        | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [ElectricBorder](https://reactbits.dev/animations/electric-border) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/ElectricBorder))    | Jittery electric energy border with animated arcs, glow and adjustable intensity.                                                    | `none`                                                               | `color`, `speed`, `chaos`, `borderRadius`, `className`, `style`, `children`                                                                                                                                                                                                                                 | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [FadeContent](https://reactbits.dev/animations/fade-content) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/FadeContent))             | Simple directional fade / slide entrance / exit wrapper with threshold-based activation.                                             | `gsap@^3.13.0`                                                       | `children`, `blur`, `duration`, `delay`, `ease`, `threshold`, `initialOpacity`, `className`, `disappearAfter`, `disappearDuration`, `disappearEase`                                                                                                                                                         | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [GhostCursor](https://reactbits.dev/animations/ghost-cursor) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/GhostCursor))             | Semi-transparent ghost cursor that smoothly follows the real cursor with a trailing effect.                                          | `three@^0.180.0`                                                     | `className`, `style`, `trailLength`, `inertia`, `grainIntensity`, `bloomStrength`, `bloomRadius`, `bloomThreshold`, `brightness`, `color`, `mixBlendMode`, `edgeIntensity`, `maxDevicePixelRatio`, `targetPixels`, `fadeDelayMs`, `fadeDurationMs`, `zIndex`                                                | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [GlareHover](https://reactbits.dev/animations/glare-hover) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/GlareHover))                | Adds a realistic moving glare highlight on hover over any element.                                                                   | `none`                                                               | `width`, `height`, `background`, `borderRadius`, `borderColor`, `children`, `glareColor`, `glareOpacity`, `glareAngle`, `glareSize`, `transitionDuration`, `playOnce`, `className`, `style`                                                                                                                 | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [GradualBlur](https://reactbits.dev/animations/gradual-blur) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/GradualBlur))             | Progressively un-blurs content based on scroll or trigger creating a cinematic reveal.                                               | `none`                                                               | `position`, `strength`, `height`, `width`, `divCount`, `exponential`, `curve`, `opacity`, `animated`, `duration`, `easing`, `hoverIntensity`, `target`, `preset`, `responsive`, `zIndex`, `onAnimationComplete`, `className`, `style`                                                                       | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [ImageTrail](https://reactbits.dev/animations/image-trail) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/ImageTrail))                | Cursor-based image trail with several built-in variants.                                                                             | `gsap@^3.13.0`                                                       | `items`, `variant`                                                                                                                                                                                                                                                                                          | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [LaserFlow](https://reactbits.dev/animations/laser-flow) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/LaserFlow))                   | Dynamic laser light that flows onto a surface, customizable effect.                                                                  | `three@^0.180.0`                                                     | `horizontalBeamOffset`, `verticalBeamOffset`, `horizontalSizing`, `verticalSizing`, `wispDensity`, `wispSpeed`, `wispIntensity`, `flowSpeed`, `flowStrength`, `fogIntensity`, `fogScale`, `fogFallSpeed`, `mouseTiltStrength`, `mouseSmoothTime`, `decay`, `falloffStart`, `dpr`, `color`                   | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [LogoLoop](https://reactbits.dev/animations/logo-loop) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/LogoLoop))                      | Continuously looping marquee of brand or tech logos with seamless repeat and hover pause.                                            | `none`                                                               | `logos`, `speed`, `direction`, `width`, `logoHeight`, `gap`, `hoverSpeed`, `fadeOut`, `fadeOutColor`, `scaleOnHover`, `renderItem`, `ariaLabel`, `className`, `style`                                                                                                                                       | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [MagicRings](https://reactbits.dev/animations/magic-rings) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/MagicRings))                | Interactive magic rings effect with customizable parameters.                                                                         | `three@^0.180.0`                                                     | `color`, `colorTwo`, `ringCount`, `speed`, `attenuation`, `lineThickness`, `baseRadius`, `radiusStep`, `scaleRate`, `opacity`, `blur`, `noiseAmount`, `rotation`, `ringGap`, `fadeIn`, `fadeOut`, `followMouse`, `mouseInfluence`, `hoverScale`, `parallax`, `clickBurst`                                   | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [Magnet](https://reactbits.dev/animations/magnet) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/Magnet))                             | Elements magnetically ease toward the cursor then settle back with spring physics.                                                   | `none`                                                               | `padding`, `disabled`, `magnetStrength`, `activeTransition`, `inactiveTransition`, `wrapperClassName`, `innerClassName`, `children`                                                                                                                                                                         | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [MagnetLines](https://reactbits.dev/animations/magnet-lines) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/MagnetLines))             | Animated field lines bend toward the cursor.                                                                                         | `none`                                                               | `rows`, `columns`, `containerSize`, `lineColor`, `lineWidth`, `lineHeight`, `baseAngle`, `className`, `style`                                                                                                                                                                                               | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [MetaBalls](https://reactbits.dev/animations/meta-balls) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/MetaBalls))                   | Liquid metaball blobs that merge and separate with smooth implicit surface animation.                                                | `ogl@^1.0.11`                                                        | `color`, `speed`, `enableMouseInteraction`, `enableTransparency`, `hoverSmoothness`, `animationSize`, `ballCount`, `clumpFactor`, `cursorBallSize`, `cursorBallColor`                                                                                                                                       | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [MetallicPaint](https://reactbits.dev/animations/metallic-paint) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/MetallicPaint))       | Liquid metallic paint shader which can be applied to SVG elements.                                                                   | `none`                                                               | `imageSrc`, `seed`, `scale`, `refraction`, `blur`, `liquid`, `speed`, `brightness`, `contrast`, `angle`, `fresnel`, `lightColor`, `darkColor`, `patternSharpness`, `waveAmplitude`, `noiseScale`, `chromaticSpread`, `mouseAnimation`, `distortion`, `contour`, `tintColor`                                 | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [Noise](https://reactbits.dev/animations/noise) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/Noise))                                | Animated film grain / noise overlay adding subtle texture and motion.                                                                | `none`                                                               | `patternSize`, `patternScaleX`, `patternScaleY`, `patternRefreshInterval`, `patternAlpha`                                                                                                                                                                                                                   | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [OrbitImages](https://reactbits.dev/animations/orbit-images) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/OrbitImages))             | SVG Path customizable orbiting images effect                                                                                         | `motion@^12.23.12`                                                   | `images`, `altPrefix`, `shape`, `customPath`, `baseWidth`, `radiusX`, `radiusY`, `radius`, `starPoints`, `starInnerRatio`, `rotation`, `duration`, `itemSize`, `direction`, `fill`, `width`, `height`, `className`, `showPath`, `pathColor`, `pathWidth`, `easing`, `paused`, `centerContent`, `responsive` | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [PixelTrail](https://reactbits.dev/animations/pixel-trail) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/PixelTrail))                | Pixelated cursor trail emitting fading squares with retro digital feel.                                                              | `@react-three/fiber@^9.3.0 @react-three/drei@^10.7.4 three@^0.180.0` | `gridSize`, `trailSize`, `maxAge`, `interpolate`, `color`, `gooeyFilter`                                                                                                                                                                                                                                    | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [PixelTransition](https://reactbits.dev/animations/pixel-transition) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/PixelTransition)) | Pixel dissolve transition for content reveal on hover.                                                                               | `gsap@^3.13.0`                                                       | `firstContent`, `secondContent`, `gridSize`, `pixelColor`, `animationStepDuration`, `aspectRatio`, `once`, `className`, `style`                                                                                                                                                                             | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [Ribbons](https://reactbits.dev/animations/ribbons) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/Ribbons))                          | Flowing responsive ribbons/cursor trail driven by physics and pointer motion.                                                        | `ogl@^1.0.11`                                                        | `colors`, `baseSpring`, `baseFriction`, `baseThickness`, `offsetFactor`, `maxAge`, `pointCount`, `speedMultiplier`, `enableFade`, `enableShaderEffect`, `effectAmplitude`, `backgroundColor`                                                                                                                | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [ShapeBlur](https://reactbits.dev/animations/shape-blur) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/ShapeBlur))                   | Morphing blurred geometric shape. The effect occurs on hover.                                                                        | `three@^0.180.0`                                                     | `variation`, `pixelRatioProp`, `shapeSize`, `roundness`, `borderSize`, `circleSize`, `circleEdge`                                                                                                                                                                                                           | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [SplashCursor](https://reactbits.dev/animations/splash-cursor) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/SplashCursor))          | Liquid splash burst at cursor with curling ripples and waves.                                                                        | `none`                                                               | `SIM_RESOLUTION`, `DYE_RESOLUTION`, `CAPTURE_RESOLUTION`, `DENSITY_DISSIPATION`, `VELOCITY_DISSIPATION`, `PRESSURE`, `PRESSURE_ITERATIONS`, `CURL`, `SPLAT_RADIUS`, `SPLAT_FORCE`, `SHADING`, `COLOR_UPDATE_SPEED`, `RAINBOW_MODE`, `COLOR`, `BACK_COLOR`                                                   | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [StarBorder](https://reactbits.dev/animations/star-border) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/StarBorder))                | Animated star / sparkle border orbiting content with twinkle pulses.                                                                 | `none`                                                               | `as`, `className`, `color`, `speed`, `thickness`                                                                                                                                                                                                                                                            | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [StickerPeel](https://reactbits.dev/animations/sticker-peel) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/StickerPeel))             | Sticker corner lift + peel interaction using 3D transform and shadow depth.                                                          | `gsap@^3.13.0`                                                       | `imageSrc`, `rotate`, `peelBackHoverPct`, `peelBackActivePct`, `peelDirection`, `peelEasing`, `peelHoverEasing`, `width`, `shadowIntensity`, `lightingIntensity`, `initialPosition`, `className`                                                                                                            | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [Strands](https://reactbits.dev/animations/strands) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/Strands))                          | Glowing ribbon-like strands that ripple and weave across a transparent canvas.                                                       | `ogl@^1.0.11`                                                        | `colors`, `count`, `speed`, `amplitude`, `waviness`, `thickness`, `glow`, `taper`, `spread`, `hueShift`, `intensity`, `saturation`, `opacity`, `scale`, `glass`, `refraction`, `dispersion`, `glassSize`                                                                                                    | JS-CSS, JS-TW, TS-CSS, TS-TW |
+| [TargetCursor](https://reactbits.dev/animations/target-cursor) ([fonte](https://github.com/DavidHDev/react-bits/tree/3acbd54115330a42e39f63dda2d4859e998b6684/src/ts-default/Animations/TargetCursor))          | A cursor follow animation with 4 corners that lock onto targets.                                                                     | `gsap@^3.13.0`                                                       | `targetSelector`, `spinDuration`, `hideDefaultCursor`, `hoverDuration`, `parallaxOn`, `cursorColor`, `cursorColorOnTarget`                                                                                                                                                                                  | JS-CSS, JS-TW, TS-CSS, TS-TW |
+
+## Comandos por componente
+
+Substituir `<Component>` pelo nome exato da primeira coluna:
+
+```bash
+npx shadcn@latest add @react-bits/<Component>-TS-TW
+npx shadcn@latest add https://reactbits.dev/r/<Component>-TS-TW
+npx jsrepo@latest add https://reactbits.dev/r/<Component>-TS-TW
+```

package/docs/framework/react-bits/audit-findings.md

@@ -0,0 +1,103 @@
+# React Bits - achados de auditoria do snapshot
+
+## Cobertura e proveniência
+
+- Repositório e registry confirmados no SHA
+  `3acbd54115330a42e39f63dda2d4859e998b6684`, de 14/07/2026.
+- 139 componentes reais: 31 Animations, 23 TextAnimations, 40 Components e 45
+  Backgrounds.
+- 556 itens publicados no registry, quatro nomes de variante por componente.
+- 139 demos com PropTable e mais de 1.600 entradas documentadas de props.
+- O slogan “140+” é aproximado/promocional e não deve ser usado como contagem exata.
+
+## Gap de variante funcional
+
+`CurvedInput` tem implementação funcional apenas em `JS-CSS`. Os arquivos e os
+payloads publicados de `JS-TW`, `TS-CSS` e `TS-TW` existem, mas o código principal tem
+zero bytes. Portanto, existência no registry não prova capacidade funcional. O
+gerador SINAPSE mede bytes e registra `incompleteVariants`.
+
+## Divergências de API/documentação
+
+- `AnimatedContent`: tabela escreve `dissappearAfter`; fonte usa `disappearAfter`.
+- `GridDistortion`: tabela escreve `imgageSrc`; fonte usa `imageSrc`.
+- `ASCIIText`: `strokeColor` aparece como não implementada.
+- `FallingText`: `highlightClass` existe no JS-CSS, mas não é consistente nas outras
+  variantes; `wordSpacing` aparece na tabela sem equivalente nas fontes TS.
+- `Ferrofluid`: `backgroundColor` é duplicada na tabela.
+- `LogoLoop` fica dentro do objeto `textAnimations` em `Components.js`, mas metadata,
+  navegação e URL o tratam corretamente como Animation.
+
+Regra: em conflito, usar registry para dependências e código da variante escolhida
+para API/comportamento; tratar a PropTable como interface de documentação, não como
+prova final.
+
+## Divergências de instalação
+
+- README e o gerador das páginas usam shadcn com alias `@react-bits/...`.
+- `Installation.jsx` e `llms.txt` também mostram shadcn por URL direta. Ambos são
+  formatos oficiais, mas a documentação não é uniforme.
+- A página de instalação lista variantes jsrepo antigas (`default`, `tailwind`,
+  `ts/default`, `ts/tailwind`), enquanto o registry/comando atual usa `JS-CSS`,
+  `JS-TW`, `TS-CSS`, `TS-TW`.
+- `Lanyard` marca `dependencyResolution: manual`; seu registry não expressa todas as
+  dependências necessárias. Consultar demo e fonte.
+
+## Padrões técnicos observados
+
+Os padrões se sobrepõem; um componente pode aparecer em várias linhas:
+
+| Padrão no JS-CSS        | Componentes |
+| ----------------------- | ----------: |
+| `requestAnimationFrame` |          78 |
+| interação pointer/touch |          76 |
+| WebGL ou shader         |          43 |
+| `ResizeObserver`        |          34 |
+| OGL                     |          31 |
+| GSAP                    |          28 |
+| Three.js/R3F            |          23 |
+| Canvas 2D               |          23 |
+| Motion                  |          20 |
+| `IntersectionObserver`  |          17 |
+| SVG                     |          12 |
+| CSS `@keyframes`        |           4 |
+
+Conclusão operacional: a maior parte do catálogo exige disciplina de lifecycle,
+render loop, resize, pointer e GPU. Não tratar os snippets como CSS decorativo trivial.
+
+## Dependências com discrepância
+
+Há diferenças entre demo/manual e registry em pelo menos FadeContent, GradualBlur,
+MagicRings, ASCIIText, GradientText, ShinyText, CardNav, Carousel, Lanyard, PillNav,
+Ballpit e GridScan. Também há variantes com conjuntos diferentes, como ElasticSlider
+e Ballpit. O `inventory.json` registra dependências por variante.
+
+## Ferramentas oficiais fora dos 139 componentes
+
+- [Background Studio](https://reactbits.dev/tools/background-studio): customiza
+  backgrounds e exporta vídeo, imagem ou código.
+- [Shape Magic](https://reactbits.dev/tools/shape-magic): cria formas/blobs e exporta
+  SVG, PNG, JPG, React ou CSS clip-path.
+- [Texture Lab](https://reactbits.dev/tools/texture-lab): aplica noise, dithering,
+  halftone, ASCII e outros efeitos, com exportação/presets.
+
+As três rotas têm implementação lazy real no snapshot. O sitemap não lista `/tools`,
+as três subrotas nem `/get-started/index`; isso é omissão de SEO, não ausência.
+
+## Comandos do repositório upstream
+
+| Comando                               | Função                                           |
+| ------------------------------------- | ------------------------------------------------ |
+| `npm run dev`                         | registry watch + Vite                            |
+| `npm run build`                       | registry build + llms.txt + sitemap + Vite build |
+| `npm run new:component <tipo> <nome>` | cria estrutura inicial de componente             |
+| `npm run registry:build`              | gera `public/r` via jsrepo                       |
+| `npm run registry:dev`                | observa e regenera registry                      |
+| `npm run llms:text`                   | gera índice textual para LLMs                    |
+| `npm run sitemap`                     | gera sitemap                                     |
+| `npm run lint`                        | ESLint sem warnings                              |
+| `npm run format`                      | Prettier                                         |
+
+O gerador upstream cria árvores e arquivos, mas não garante implementação equivalente
+nas quatro variantes. Toda contribuição precisa revisar código, demo, metadata,
+registry, desktop, mobile e console.