عن المشروع

# Libraries.dev **مكتبات واجهة مصنوعة بإتقان لوكلاء الذكاء الاصطناعي.** سبع مكتبات React للتأثيرات التي تجعل الواجهة تبدو حيّة: شعاع ضوء يسير على حدود بطاقة، وكرات تفكّر بينما يعمل النموذج، وصور رمزية للروبوتات بوجوه حيّة، وأشكال تندمج كالسائل، وتوهّج يرتفع مع صوتك، ومعدن مصقول يلتقط الضوء، ومحمّل صور يذيب فسيفساء البكسلات إلى صورة حقيقية. كل واحدة تُثبَّت من npm وتُدرج في تطبيقك كمكوّن واحد يلفّ العنصر الذي لديك بالفعل. يحتفظ الترميز بدلالته، ويُعرض التأثير حوله أو خلفه، ويُضبط الأمر كله عبر الخصائص بدل كتابة WebGL يدويًا. | المكتبة | ما تفعله | npm | الصفحة | | --- | --- | --- | --- | | [Border beam](packages/border-beam) | توهّج ناعم يسير على حدود بطاقة أو زر أو حقل إدخال | `npm install border-beam` | [libraries.dev/beam](https://libraries.dev/beam) | | [Thinking orbs](packages/thinking-orbs) | كرات تفكّر بينما تنتظر — تسع حالات تحميل لواجهات الذكاء الاصطناعي | `npm install thinking-orbs` | [libraries.dev/orbs](https://libraries.dev/orbs) | | [Bot avatars](packages/bot-avatars) | صور رمزية متحركة للروبوتات بوجوه حيّة — ثمانية عشر شكلًا لامعًا، وأربع حالات، لوكلاء الذكاء الاصطناعي | `npm install bot-avatars` | [libraries.dev/avatars](https://libraries.dev/avatars) | | [Gooey](packages/liquid-gooey) | قطع تندمج كاللزوجة وتتحوّل كالهلام بينما يبقى النص واضحًا | `npm install liquid-gooey` | [libraries.dev/gooey](https://libraries.dev/gooey) | | [Voice](packages/voice-glow) | توهّج يرتفع مع صوتك من أسفل حقل محادثة أو شاشة هاتف | `npm install voice-glow` | [libraries.dev/voice](https://libraries.dev/voice) | | [Metal](packages/metal-fx) | معدن سائل للأزرار والأيقونات والنصوص والشارات، مع انعكاسات وضوء المؤشر | `npm install metal-fx` | [libraries.dev/metal](https://libraries.dev/metal) | | [Image](packages/img-fx) | محمّل يصبح الصورة — فسيفساء بكسلات WebGL تستقر في الصورة | `npm install img-fx` | [libraries.dev/image](https://libraries.dev/image) | جرّب كل واحدة على [libraries.dev](https://libraries.dev): معاينة حيّة للتجربة، وأمر التثبيت، وكود الاستخدام، وملعب ينسخ الإعداد الدقيق. ## كيفية الاستخدام كل مكتبة تأتي كموجّه نصي (prompt). انسخه، والصقه في وكيل البرمجة لديك، واجعله لك — ثلاث خطوات، دون أي إعداد. 1. **انسخ الموجّه.** كل صفحة مكتبة فيها زر *Copy prompt*. لصقة واحدة تمنح وكيلك المكتبة كاملة: مفردات معاملاتها وإعداداتك الحالية. 2. **الصقه في وكيلك.** أدرجه في Claude Code أو Cursor أو Codex. يثبّت الوكيل الحزمة ويربطها، مطابقةً لسمتك. 3. **اجعله لك.** افتح [Studio](https://libraries.dev/studio.html) مع Pro لكل مقبض ضبط، واضبطه مباشرة وانسخ النتيجة كخصائص. أو بالطريقة العادية: ```bash npm install border-beam # or thinking-orbs, bot-avatars, liquid-gooey, voice-glow, metal-fx, img-fx ``` ```tsx import { BorderBeam } from "border-beam"; <BorderBeam> <button>Get started</button> </BorderBeam> ``` ملف README لكل حزمة يوثّق خصائصها. ## الأسئلة الشائعة **ما الذي أحتاجه؟** React 18 أو أحدث. كل مكتبة حزمة مستقلة بلا تبعيات وقت التشغيل، باستثناء Image التي تحتاج أيضًا إلى `three` كتبعية نظيرة. **هل تعمل مع وكلاء البرمجة؟** نعم — هذا هو الهدف. كل مكتبة تُثبَّت وتُضبط بسلاسة من Cursor وClaude Code وCodex، وزر نسخ الموجّه في كل ملعب يمنح وكيلك مفردات معاملات المكتبة كاملة مع إعداداتك الحالية. **الوضع الفاتح والداكن؟** كلاهما، ويُكتشف لك تلقائيًا. القيمة الافتراضية `theme="auto"` تحلّ سمة `data-theme` أو صنف `dark` على عنصر سلف، ثم ترجع إلى `prefers-color-scheme`، وتتحدّث مباشرة عند تغيّر أي منهما. مرّر `theme="dark"` أو `theme="light"` لتثبيت أحدهما. **ما هما Pro وStudio؟** خطة واحدة عبر كل المكتبات. يفتح Pro الـ[Studio](https://libraries.dev/studio.html) — تخصيص عميق لكل مكتبة يتجاوز الملاعب العامة، مع تصدير الإعداد الدقيق — إضافة إلى إعدادات Pro المسبقة وكل مكتبة وتحديث مستقبليين. راجع [الأسعار](https://libraries.dev/pro.html). **المشاريع التجارية؟** المكتبات بترخيص MIT — استخدمها في أي مكان، بما في ذلك الأعمال التجارية. محتوى Pro (صادرات Studio، وإعدادات ووصفات Pro المسبقة) مرخّص لك أو لفريقك بموجب الخطة التي تشتريها، لمشاريع غير محدودة. ## العمل في هذا المستودع مساحات عمل npm: يحوي `packages/` المكتبات المنشورة (مجلد لكل حزمة npm، ولكل منها README وLICENSE خاصان)، ويحوي `sites/` مواقع العرض — و`sites/home` هو libraries.dev. ```bash npm install npm run build:site-home # every library + libraries.dev, as CI does npm run dev -w @sites/home # libraries.dev with every page and the Studio npm run typecheck # every workspace ``` موقع الرئيسية يستورد الحزم المبنية، لذا ابنِ مكتبة (`npm run build:beam`، `build:orbs`، `build:gooey`، `build:voice`، `build:metal`، `build:image`) قبل صفحتها أو مقعدها. العروض المستقلة (`@sites/beam`، `@sites/gooey`، `@sites/orbs`) تربط مكتبتها بمصدرها وتعيد التحميل الساخن دون إعادة بناء. ## الإصدار النشر لكل حزمة على حدة (`publish.yml`، `npm publish -w <package>`): شغّل سير العمل يدويًا باسم الحزمة، أو انشر إصدار GitHub تكون وسمه `<package>@<version>` (`voice-glow@0.2.0`). أي إصدار يملكه السجل بالفعل يُتخطّى. ## عمليات النشر يُستضاف الموقعان بشكل منفصل، لأن GitHub Pages يخدم نطاقًا مخصصًا واحدًا لكل مستودع: - **beam.jakubantalik.com** — GitHub Pages عبر `.github/workflows/deploy.yml`؛ وربط النطاق موجود في `sites/beam/public/CNAME`. - **gooey.jakubantalik.com** — Cloudflare Pages، يُبنى من هذا المستودع بـ`npm run build:site-gooey`، والمخرجات `sites/gooey/dist`. - **orbs.jakubantalik.com** — Cloudflare Pages، يُبنى بـ`npm run build:site-orbs`، والمخرجات `sites/orbs/dist`. - **libraries.dev** — Cloudflare Pages، يُنشر بواسطة `.github/workflows/deploy-home.yml` عند كل دفعة إلى `main` (`npm run build:site-home`، والمخرجات `sites/home/dist`). الموقع الرئيسي: صفحة هبوط، وصفحة ومقعد Studio لكل مكتبة، وأسعار Pro، وصفحات الحساب والقانونية. خلفيته `api.libraries.dev`، وهو Worker في مستودع `libraries-pro` الخاص — راجع `sites/home/README.md`. يثبّت `.node-version` الإصدار Node 20 لعمليات بناء Cloudflare، مطابقًا للإصدار الذي تستخدمه سير عمل GitHub؛ فالإصدار الافتراضي في Cloudflare أقدم. خيار **Retry deployment** في Cloudflare يعيد تشغيل نفس الالتزام بدل جلب طرف الفرع، لذا يظل البناء الذي فشل على التزام قديم يفشل. ادفع التزامًا جديدًا للحصول على واحد جديد. موقع beam وحده يحمل `public/CNAME`؛ فذلك الملف آلية من GitHub Pages. المواقع المستضافة على Cloudflare تربط نطاقها في مشروع Pages بدلًا من ذلك، وسجل DNS نفسه موجود لدى المسجّل (inetadmin)، لا لدى Cloudflare — فنطاق `jakubantalik.com` ليس على خوادم أسماء Cloudflare. وصلت `thinking-orbs` عبر `git subtree`، لذا تاريخها الكامل موجود في هذا المستودع — لكن تلك الالتزامات لمست `src/…`، لا `packages/thinking-orbs/src/…`. لذلك يتوقف `git log -- packages/thinking-orbs` عند الدمج. لقراءة التاريخ الحقيقي، سجّل من الالتزام الذي يسمّيه الدمج: ```bash git log --oneline 9c6d5c3 -- ports/ios/PillsDemo/Sources/PillsApp.swift git log --follow packages/thinking-orbs/src/index.ts ``` تحمل `thinking-orbs` أيضًا منافذ أصلية تحت [`packages/thinking-orbs/ports`](packages/thinking-orbs/ports) — حزمة React Native وحزمة SwiftUI، تُبقى متوافقة مع عارض الويب عبر المتجهات الذهبية في `spec/`. ولم يُنشر أي منهما بعد.