‏PandaScript؛ اسکریپت اتوماسیون وب که مستقیم توی Lightpanda اجرا می‌شه

مستندات Lightpanda یه قابلیت به اسم PandaScript رو معرفی می‌کنن: اسکریپت‌های اتوماسیون وب که خود مرورگر Lightpanda با دستور lightpanda run اجراشون می‌کنه. نه Node.js لازمه، نه Puppeteer یا Playwright، نه هزینهٔ سریال‌سازی CDP (یعنی پروتکلی که ابزارها باهاش از بیرون مرورگر رو کنترل می‌کنن)، نه LLM. فقط جاوااسکریپت معمولی با متغیر، حلقه و JSON.parse به‌اضافهٔ چندتا تابع آماده. نتیجه‌ش اینه که اجرا قابل‌تکرار و قطعیه و توکنی مصرف نمی‌کنه.

نکتهٔ مهم اینه که اسکریپت توی یه V8 context جدا از خود صفحه اجرا می‌شه. یعنی window، document و localStorage اونجا وجود نداره، و require، process و fs هم نیست چون Node.js نیست. صفحه هم متغیرهای اسکریپت رو نمی‌بینه. متغیرها در طول یه اجرا، حتی بین چند ناوبری، باقی می‌مونن. فقط goto ناهمگامه و باید await بشه؛ بقیهٔ متدها مثل extract، click و fill همگام و بلاک‌کننده‌ن.

راه اصلی خوندن داده page.extract(...) هست. یه schema بهش می‌دی که فیلدهاش selector هستن و خروجی یه آبجکت جاوااسکریپتی با همون شکل برمی‌گردونه:

const page = new Page();
await page.goto("https://news.ycombinator.com/");
const data = page.extract({
  title: "title",
  stories: [{ selector: "tr.athing", limit: 5, fields: { id: { attr: "id" }, title: ".titleline > a" } }]
});
return data; // printed automatically as JSON

همهٔ مقدارها رشته یا null هستن و عدد رو باید خودت parse کنی. اگه یه فیلد آرایه‌ای چیزی پیدا نکنه [] برمی‌گرده، ولی اگه هیچ‌کدوم از فیلدها match نشن خطای no schema selector matched any element می‌ده؛ به گفتهٔ مستندات این یعنی selectorهات غلطن، نه اینکه صفحه خالیه. برای کارهایی که extract از پسش برنمیاد، page.evaluate(...) یه رشته رو توی context خود صفحه اجرا می‌کنه، ولی متغیرهای اسکریپت رو نمی‌بینه.

برای تعامل هم click، fill، press، hover، selectOption، setChecked و scroll هست، به‌اضافهٔ متدهای waitFor*. یه نکتهٔ ریز: آرگومان اول press در واقع selector هست، پس press("Enter") خطا می‌ده و باید press({ key: "Enter" }) بنویسی. برای اطلاعات حساس می‌شه از placeholderهای $LP_* استفاده کرد که داخل خود پروسهٔ Lightpanda مقدار می‌گیرن، یعنی رمزها توی اسکریپت ذخیره‌شده یا prompt مدل نمی‌مونن. خطای هر تابع هم یه Error معمولی جاوااسکریپته که با try/catch گرفته می‌شه.

نکات کلیدی:

• اجرا با lightpanda run و بدون نیاز به Node.js یا Puppeteer
• اسکریپت توی V8 context جدا از صفحه اجرا می‌شه و به document دسترسی نداره
• فقط page.goto ناهمگامه و بقیهٔ متدها همگامن
• page.extract خروجی رو هم‌شکل schema برمی‌گردونه و همهٔ مقدارها رشته یا null هستن
• خروجی اسکریپت همون چیزیه که از سطح بالا return می‌شه
• placeholderهای $LP_* رمزها رو از اسکریپت و prompt دور نگه می‌دارن