@appaflytech/zeyrek-ai-mcp 0.0.36 → 0.0.40

package/dist/platform/capture/capture.js

@@ -0,0 +1,683 @@
+import { PlatformApiError } from '../errors.js';
+import { parseDomSummary } from '../domSummary.js';
+import { INTERNAL_ROLE_SEPARATOR, knownInternalRoles } from '../../knowledge/componentCatalog.js';
+import { logStep } from '../../observability/trace.js';
+import { actionScript, activeTabScript, rootElementId, runtimePropsScript } from './actions.js';
+import { domSummaryScript } from './summary.js';
+import { createPageConsoleLog, describePageFailure, isExpressionEcho, parseRenderErrors, renderErrorsScript, splitExpressionErrors } from './console-log.js';
+import { decideReadiness, describeUnready, parseReadiness, readinessScript, runtimePath } from './readiness.js';
+/** Runtime'ın Connect Data bağlantısı için bastığı sözde akış kimliği: hata bir akış adımından değil bağlı prop'un okumasından gelir. */
+const CONNECT_DATA_FLOW_ID = 'connect-data';
+/**
+ * `runtimeErrors` yanında dönen okuma notu. Bağlantı hatasının (`flowId: 'connect-data'`) açılacak akışı yoktur:
+ * not onu bağlantının araçlarına yönlendirir (39/M-18 — `flow_get` önerisi ajanı olmayan bir akışa götürüyordu).
+ */
+export function runtimeErrorsNote(errors) {
+    const connections = errors.filter(error => error.flowId === CONNECT_DATA_FLOW_ID);
+    const flows = errors.length - connections.length;
+    const head = `Sayfa ${errors.length} yapısal hata bıraktı; kare 'çalışıyor' görünse bile bu adımlar işini YAPMADI. element/property alanı hangi komponentin hangi prop'unun yazılamadığını söyler — o komponent eski/boş değerindedir.`;
+    const flowHint = flows > 0 ? ` Akış hatasında (${flows}) adımı flow_get ile açıp ifadeyi düzeltin.` : '';
+    const connectionHint = connections.length > 0
+        ? ` Bağlantı hatasında (flowId 'connect-data': ${connections.map(error => `${error.element}.${error.property}`).join(', ')}) akış yoktur: code alanı reddin nedenidir — connect_data_get ile tanımı, connect_data_execute { op: 'list', asUserId } ile aynı isteği görün (kompleks projede 403 çoğunlukla kaynağın grant'i ya da ACC-005).`
+        : '';
+    return `${head}${flowHint}${connectionHint}`;
+}
+/**
+ * Ziyaretçinin tema tercihinin yaşadığı localStorage anahtarı — `theme-toggle` bunu yazar,
+ * `Theme` okur ve projenin kendi modunun önüne geçirir
+ * (`zeyrek-frontend/packages/ng-apps-ui/src/shared/theme/stores.ts`). Anahtar uygulama başına
+ * DEĞİL tarayıcı başına tektir.
+ */
+const VIEWER_MODE_STORAGE_KEY = 'zeyrek-viewer-theme-mode';
+/**
+ * fullPage karesi Chromium'un viewport ötesi yakalamasıyla değil, viewport'u içerik boyuna
+ * büyüterek alınır: Studio runtime'ı kendi kaydırma kabını `100vh` üzerine kuruyor ve viewport
+ * ötesi yakalama o kabı bir kez daha çiziyordu — aynı sayfa karede iki kez görünüyordu (09-04
+ * Y-23). Tek karede çekilen görüntüde o birleştirme adımı hiç yok.
+ *
+ * İç kaydırıcı için gereken viewport `innerHeight + (scrollHeight − clientHeight)`'tir, kabın
+ * `scrollHeight`'i DEĞİL: kap viewport'la birlikte büyür ama üstündeki/altındaki sabit parçalar
+ * (mobil host'ta app bar + tab bar, ZM-23 f-06) büyümez. Yalnız `scrollHeight` itilince viewport
+ * içerik boyuna çıkıyor, kap hâlâ o parçalar kadar kısa kalıyor ve uzun mobil sayfanın altı
+ * karenin dışında kalıyordu. Kap viewport kadar yüksekse iki formül aynı sonucu verir.
+ */
+export const contentHeightScript = [
+    '(function () {',
+    '  var doc = document.documentElement;',
+    '  var body = document.body;',
+    '  var viewportHeight = window.innerHeight;',
+    '  var heights = [doc ? doc.scrollHeight : 0, body ? body.scrollHeight : 0];',
+    '  var nodes = document.querySelectorAll("*");',
+    '  for (var index = 0; index < nodes.length && index < 4000; index += 1) {',
+    '    var node = nodes[index];',
+    '    if (node.clientHeight >= viewportHeight * 0.6 && node.scrollHeight > node.clientHeight + 1) heights.push(viewportHeight + node.scrollHeight - node.clientHeight);',
+    '  }',
+    '  return { contentHeight: Math.max.apply(null, heights), viewportHeight: viewportHeight };',
+    '})()'
+].join('\n');
+/**
+ * Kırpma kutusu CSS pikselinde okunur; kare çekilirken Chromium onu `scale` ile çarpar
+ * (ölçüldü 2026-09-16: viewport 1280x800 · scale 0.5 · clip 300x100 → 150x50 raster).
+ * `null` düğüm yok demektir — tool bunu HATAYA çevirir, boş kare döndürmez.
+ */
+export function clipRectScript(elementId) {
+    return `(function () { /* clipRect */
+    var node = document.querySelector(${JSON.stringify(`[data-element-id="${elementId}"]`)});
+    if (!node) return null;
+    var rect = node.getBoundingClientRect();
+    var x = rect.x + (window.scrollX || 0);
+    var y = rect.y + (window.scrollY || 0);
+    // Negatif kenar kırpılırken BOY da kısalır; yoksa kutu aşağı kayar ve kare düğümün altını gösterir.
+    return { x: Math.max(x, 0), y: Math.max(y, 0), width: rect.width + Math.min(x, 0), height: rect.height + Math.min(y, 0) };
+  })()`;
+}
+/**
+ * Karenin raster boyu başlıktan okunur: PNG'de IHDR, JPEG'de ilk SOF işaretçisi. Ölçeğin
+ * gerçekten uygulandığı yanıtta SAYIYLA görünsün diye var — "yarı çözünürlük istedim" ile
+ * "yarı çözünürlük aldım" arasındaki farkı başka hiçbir alan söylemiyor.
+ */
+export function imageSize(buffer) {
+    if (buffer.length > 24 && buffer.subarray(1, 4).toString() === 'PNG') {
+        return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+    }
+    if (buffer.length > 4 && buffer[0] === 0xff && buffer[1] === 0xd8) {
+        let offset = 2;
+        while (offset + 9 < buffer.length) {
+            if (buffer[offset] !== 0xff) {
+                offset += 1;
+                continue;
+            }
+            const marker = buffer[offset + 1] ?? 0;
+            const length = buffer.readUInt16BE(offset + 2);
+            // SOF0-SOF3 · SOF5-SOF7 · SOF9-SOF11 · SOF13-SOF15 boyutu taşır; DHT/DRI gibi işaretçiler atlanır.
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { height: buffer.readUInt16BE(offset + 5), width: buffer.readUInt16BE(offset + 7) };
+            }
+            offset += 2 + length;
+        }
+    }
+    return undefined;
+}
+/**
+ * Kare taşmayı gösterir ama ölçmez: aynı sayfa yüklemesinden neredeyse bedavaya çıkan ikinci
+ * çıktı her runtime düğümünün efektif piksel kutusudur. Düğümler `data-element-id` taşımıyorsa
+ * (F-04 dev'e çıkana dek) liste boş döner — tool uydurmaz, layoutReportUnavailable der.
+ */
+export const layoutReportScript = [
+    '(function () {',
+    'var nodes = Array.from(document.querySelectorAll("[data-element-id]")).slice(0, 500);',
+    'return nodes.map(function (node) {',
+    '  var rect = node.getBoundingClientRect();',
+    '  var parent = node.parentElement ? node.parentElement.closest("[data-element-id]") : null;',
+    '  var parentIndex = parent ? nodes.indexOf(parent) : -1;',
+    '  var style = window.getComputedStyle(node);',
+    '  var painted = function (color) { return color !== "transparent" && !/rgba\\([^)]*,\\s*0\\)$/.test(color); };',
+    '  var bordered = ["Top", "Right", "Bottom", "Left"].some(function (side) {',
+    '    return parseFloat(style["border" + side + "Width"]) > 0 && style["border" + side + "Style"] !== "none" && painted(style["border" + side + "Color"]);',
+    '  });',
+    '  return {',
+    '    elementId: node.getAttribute("data-element-id"),',
+    '    x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height),',
+    '    overflowX: node.scrollWidth > node.clientWidth + 1,',
+    '    overflowY: node.scrollHeight > node.clientHeight + 1,',
+    '    type: node.getAttribute("data-component-type"),',
+    '    parentId: parent ? parent.getAttribute("data-element-id") : null,',
+    '    parentIndex: parentIndex < 0 ? null : parentIndex,',
+    '    surface: painted(style.backgroundColor) || bordered || style.boxShadow !== "none"',
+    '  };',
+    '});',
+    '})()'
+].join('\n');
+/** Mobil çizicinin hata sınırı işaretleri; betik düşerse boş (çekimi düşürmez). */
+async function readRenderErrors(page) {
+    return page.evaluate(renderErrorsScript).then(parseRenderErrors).catch(() => []);
+}
+/**
+ * F-09 — sayfa akışı yalnız tarayıcıda koşar, bu yüzden bir setter iteratee'sinin
+ * patlamasının gateway'e ulaşan HİÇBİR yolu yoktu: akış 200 dönüyor, hedef prop
+ * yazılmıyor ve tek belirti yığında kaybolan bir bildirim oluyordu. Runtime artık
+ * yapısal hata defterini bu global anahtarda yayınlıyor (`@ng-apps/flow` →
+ * flow-runtime-errors.ts); kare çekilirken bedavaya okunur.
+ */
+export const flowRuntimeErrorsScript = 'Array.isArray(window.__ngAppsFlowRuntimeErrors) ? window.__ngAppsFlowRuntimeErrors.slice(0, 50) : []';
+const maxCaptureHeight = 16384;
+const navigationTimeoutMs = 20000;
+const apiResponseTimeoutMs = 15000;
+const settleMs = 600;
+/** Akış bittikten sonra Svelte'in son render'ına bırakılan pay. */
+const flowSettleGraceMs = 250;
+const flowPollMs = 120;
+const idleCloseMs = 60000;
+/** Etkileşim adımındaki `wait` üst sınırı; delayMs tavanıyla aynı çizgide. */
+const maxActionWaitMs = 15000;
+/** Viewport büyütmesinden sonra yeniden yerleşme için tanınan üst süre (B-4). */
+const resizeSettleBudgetMs = 3000;
+/**
+ * Navigasyon zaman aşımında toplam deneme sayısı. Soğuk Studio'da ilk `page.goto` Vite
+ * derlemesini ISITIR; ikinci deneme neredeyse her zaman geçer (09-08 S-8: aynı kare üç
+ * çağrıya ve ~3.5 dakikaya mal oldu). İkiden fazlası turu uzatır, bir şey kazandırmaz.
+ */
+const navigationAttempts = 2;
+/**
+ * Yalnız zaman aşımı yeniden denenir. `net::ERR_CONNECTION_REFUSED` / DNS gibi hızlı düşen
+ * hatalarda Studio ayakta değildir; tekrar yalnız bekleme süresini iki katına çıkarır ve
+ * çağırana yanlış ipucu verir.
+ */
+function isNavigationTimeout(message) {
+    return /timeout/i.test(message);
+}
+async function measureContentHeight(page) {
+    const measured = await page.evaluate(contentHeightScript).catch(() => undefined);
+    const height = measured?.contentHeight;
+    return typeof height === 'number' && Number.isFinite(height) && height > 0 ? Math.ceil(height) : undefined;
+}
+/**
+ * Kırpma kutusunu çözer. Bulunamayan ya da çizilmemiş düğüm BOŞ KARE değil HATA döndürür:
+ * "yan sütunu kırptım" deyip bomboş bir PNG almak sessiz yanlıştır.
+ */
+async function resolveClip(page, clip) {
+    if (!('element' in clip))
+        return clip;
+    const raw = await page.evaluate(clipRectScript(clip.element)).catch(() => null);
+    if (raw === null || raw === undefined) {
+        throw new PlatformApiError(`page_screenshot: clip.element '${clip.element}' sayfada yok — kırpılacak kutu bulunamadı. elementId'leri page_schema_get ile doğrulayın; bir komponentin İÇ kontrolünü kırpıyorsanız <elementId>__<rol> biçimini kullanın.`);
+    }
+    if (!(raw.width > 0 && raw.height > 0)) {
+        throw new PlatformApiError(`page_screenshot: clip.element '${clip.element}' ÇİZİLMEMİŞ (${Math.round(raw.width)}x${Math.round(raw.height)} px) — kırpma boş kare üretirdi. Düğüm gizli ya da sıfır boyutlu olabilir; layoutReport: true ile kutusuna bakın.`);
+    }
+    return { x: Math.round(raw.x), y: Math.round(raw.y), width: Math.round(raw.width), height: Math.round(raw.height) };
+}
+/**
+ * Playwright bağlamı ve tarayıcısı bu sınıfta PAYLAŞILIR. İki çekim aynı anda koştuğunda
+ * 2026-09-06 koşusunda ikisi de `Target page, context or browser has been closed` ile düştü
+ * (çağrı #204/#205, 64 sn kayıp, ajan yeniden giriş yapmak zorunda kaldı — `S-3`). Kök neden
+ * iki yerdeydi: (1) paylaşılan tarayıcı üstünde eşzamanlı bağlam açma, (2) her çekimin `finally`
+ * bloğunda ÖNCEKİ boşta-kapatma zamanlayıcısı temizlenmeden yenisinin kurulması — kaçan
+ * zamanlayıcı sonraki çekimin ortasında tarayıcıyı kapatıyordu.
+ *
+ * Çözüm bir seri kuyruk: çekimler tek tek koşar, bekleyen çağrı `queuedMs` ile ne kadar
+ * beklediğini söyler. Sıcak tarayıcı havuzu bu işin dışıdır (Ç2 · tur ekonomisi).
+ */
+export class StudioScreenshotter {
+    config;
+    launcher;
+    browserPromise;
+    idleTimer;
+    queue = Promise.resolve();
+    pending = 0;
+    recycleNext = false;
+    constructor(config, launcher) {
+        this.config = config;
+        this.launcher = launcher;
+    }
+    /**
+     * Kuyruk sınırsız birikmesin: bekleme üst sınırı aşılırsa çağrı tarayıcıya HİÇ girmeden
+     * anlaşılır bir hatayla döner ve sırasını öndekine zincirleyip çıkar, böylece kuyruğun geri
+     * kalanı serileşmiş kalır (Kısıt: tek yavaş çekimin arkasında kuyruk şişmemeli).
+     */
+    async capture(request) {
+        const queuedAt = Date.now();
+        // Sayaç SENKRON artar: `Promise.all` ile aynı turda gelen iki çağrıda ikincisi beklediğini
+        // ancak böyle bilebilir (async bir bayrak o turda henüz kurulmamış olurdu).
+        const waited = this.pending > 0;
+        const previous = this.queue;
+        this.pending += 1;
+        let release;
+        this.queue = new Promise(resolve => {
+            release = resolve;
+        });
+        let timer;
+        const capExceeded = await Promise.race([
+            previous.then(() => false, () => false),
+            new Promise(resolve => {
+                timer = setTimeout(() => resolve(true), this.config.screenshotQueueWaitMs);
+                timer.unref?.();
+            })
+        ]);
+        if (timer)
+            clearTimeout(timer);
+        if (capExceeded) {
+            this.pending -= 1;
+            void previous.then(release, release);
+            throw new PlatformApiError(`Ekran görüntüsü kuyruğunda ${Date.now() - queuedAt} ms beklendi ve üst sınır (${this.config.screenshotQueueWaitMs} ms) aşıldı — çekim başlatılmadı. Çekimleri seri çağırın ya da SCREENSHOT_QUEUE_WAIT_MS ile sınırı yükseltin.`, 503);
+        }
+        const queuedMs = Date.now() - queuedAt;
+        const recycled = this.recycleNext;
+        this.recycleNext = false;
+        if (waited)
+            logStep('tarayıcı ⏸', `çekim kuyrukta ${queuedMs} ms bekledi — eşzamanlı çekimler seri koşar`);
+        try {
+            const result = await this.captureOne(request);
+            return {
+                ...result,
+                ...(waited ? { queuedMs: Math.max(queuedMs, 1) } : {}),
+                ...(recycled ? { contextRecycled: true } : {})
+            };
+        }
+        catch (error) {
+            // Bağlam/tarayıcı bozulduysa bir sonraki çağrı TEMİZ bir tarayıcıyla başlasın; hata
+            // kuyruktaki komşuya bulaşmasın.
+            if (/browser has been closed|target (page|closed)|context.*closed/i.test(error instanceof Error ? error.message : String(error))) {
+                this.recycleNext = true;
+                const expired = this.browserPromise;
+                this.browserPromise = undefined;
+                expired?.then(instance => instance.close()).catch(() => undefined);
+            }
+            throw error;
+        }
+        finally {
+            this.pending -= 1;
+            release();
+        }
+    }
+    async launch() {
+        if (this.launcher)
+            return this.launcher();
+        let chromium;
+        try {
+            chromium = (await import('playwright-core')).chromium;
+        }
+        catch {
+            throw new PlatformApiError('playwright-core paketi yüklü değil — zeyrek-mcp dizininde `npm install playwright-core` çalıştırın, ardından tarayıcı için `npx playwright-core install chromium`.');
+        }
+        logStep('tarayıcı →', 'chromium başlatılıyor (ilk çağrı — sonraki çağrılar önbellekteki tarayıcıyı kullanır)');
+        try {
+            return await chromium.launch({
+                headless: true,
+                ...(this.config.screenshotBrowserPath ? { executablePath: this.config.screenshotBrowserPath } : {})
+            });
+        }
+        catch (firstError) {
+            try {
+                return await chromium.launch({ headless: true, channel: 'chrome' });
+            }
+            catch {
+                const message = firstError instanceof Error ? firstError.message : String(firstError);
+                throw new PlatformApiError(`Chromium başlatılamadı: ${message}. \`npx playwright-core install chromium\` ile indirin; alternatif olarak sistemdeki tarayıcının yolunu SCREENSHOT_BROWSER_PATH ile verin (alpine imajında \`apk add chromium\` + /usr/bin/chromium-browser).`);
+            }
+        }
+    }
+    /**
+     * Bekleme stratejisi bilinçli olarak `networkidle` DEĞİL: Studio'nun kök layout'u
+     * office-lite.zeyrek.dev'den dış bir script yükler ve ağ hiç durulmayabilir. SSR kabuğu yalnız
+     * spinner bastığı için domcontentloaded da tek başına yetmez. Bunun yerine sayfanın kendi veri
+     * isteği (`/{app}/p/{slug}`) gözlenir; yanıt hiç gelmezse bu hata SAYILMAZ — renderWaitTimedOut
+     * işaretlenir ve kare yine çekilir, çünkü bozuk/boş sayfayı görmek de bir doğrulamadır. Veri
+     * yanıtından sonra fontlar + kısa yerleşme beklemesi Svelte hydrate'ine alan bırakır.
+     */
+    async runActions(page, request, consoleLog) {
+        if (!request.actions || request.actions.length === 0)
+            return undefined;
+        const outcomes = [];
+        for (const [index, action] of request.actions.entries()) {
+            if (action.action === 'wait') {
+                await page.waitForTimeout(Math.min(Math.max(Number(action.ms ?? settleMs), 0), maxActionWaitMs));
+                outcomes.push({ index, action: 'wait', found: true, applied: true, requests: 0 });
+                continue;
+            }
+            const snapshotBefore = parseReadiness(await page.evaluate(readinessScript).catch(() => undefined));
+            const activityBefore = snapshotBefore?.activity ?? null;
+            const raw = await page.evaluate(actionScript(action, request.target)).catch(error => ({
+                found: false,
+                applied: false,
+                note: error instanceof Error ? error.message : String(error),
+                requests: 0
+            }));
+            const before = (raw ?? {});
+            // Hedef bulunamadıysa ajan neyi yanlış yazdığını KAREDEN çıkaramaz. `__` taşıyan hedef bir
+            // iç rol denemesidir: bilinen roller sayılır. Kök hedefi bulunamadıysa sorun elementId'nin
+            // kendisindedir, şemayı okumaya yönlendirilir (P1-3 Step 3).
+            if (before.found === false && !before.note && typeof action.target === 'string') {
+                before.note = action.target === '__tabs' || action.target.startsWith(`__tabs${INTERNAL_ROLE_SEPARATOR}`)
+                    ? `'${action.target}' sayfada yok: bu sayfa sekme çubuğunda değil ya da uygulamada sekmeler kapalı (application_get → properties.mobile.tabs). Sekme öğesinin kimliği __tabs__item-<sayfa slug'ı>.`
+                    : action.target.includes(INTERNAL_ROLE_SEPARATOR)
+                        ? `'${action.target}' sayfada yok. Bu bir İÇ ROL hedefi: biçim <elementId>__<rol> ve bilinen roller — ${knownInternalRoles().join(' · ')}. Kolon rolleri kolonun SLUG'ından türer (başlığından değil); satır sırası 0 tabanlıdır ve sayfa değişince yeniden numaralanır.`
+                        : `'${action.target}' elementId'si sayfada yok. page_schema_get ile elementId'leri listeleyin; bir komponentin İÇ kontrolünü hedefliyorsanız <elementId>__<rol> biçimini kullanın (component_get çıktısındaki internalRoles).`;
+            }
+            // Olay akışı uç çağırıyor: yerleşme beklemeden sonraki istek sayısını ölçmek "istek gitti mi"
+            // sorusunu cevaplar — koşuda kusuru kesinleştiren gözlem buydu.
+            //
+            // Bekleme ana yükleme döngüsüyle AYNI hazırlık kararıdır: akış koştuysa bitince, hiç akış
+            // tetiklenmediyse (metin alanına `set`) DOM durulunca, eylem sayfayı değiştirdiyse yeni
+            // sayfa hazır olunca çıkar. Eskiden akış tetiklemeyen her eylem `settleMs + delayMs`'in
+            // tamamını bekliyordu: 09-06·2 koşusunda üç eylemli giriş denemesi 47 sn (B-6).
+            const readiness = await this.waitForReady(page, {
+                budgetMs: apiResponseTimeoutMs + request.delayMs,
+                baselineUrl: snapshotBefore?.href ?? request.url,
+                completedBefore: activityBefore?.completed ?? Number.POSITIVE_INFINITY
+            });
+            if (readiness.state === 'not-ready' && request.captureUnready !== true) {
+                const failure = consoleLog ? describePageFailure(consoleLog, await readRenderErrors(page)) : '';
+                throw new PlatformApiError(`Etkileşim adımı ${index} (${action.action}${action.target === undefined ? '' : ` '${action.target}'`}) sonrasında sayfa ${readiness.waitedMs} ms içinde durulmadı, kare ALINMADI — ${describeUnready(readiness)}.${failure} Bekleme bütçesi ${apiResponseTimeoutMs + request.delayMs} ms; akış gerçekten uzun sürüyorsa delayMs ile büyütün. Yüklenmemiş hâli yine de görmek için captureUnready: true verin (kare pageState: 'not-ready' ile döner).`, 504);
+            }
+            const after = await page.evaluate("performance.getEntriesByType('resource').length").catch(() => undefined);
+            const requests = typeof after === 'number' && typeof before.requests === 'number' ? Math.max(after - before.requests, 0) : 0;
+            // Yerel bir akış (yalnız prop yazan setter) hiç uca gitmez ama işini YAPAR. Sayaç bu ayrımı
+            // veren tek kanıttır; sayaç yoksa flowRuns bilinmez kalır. Eylem sayfayı değiştirdiyse
+            // yeni sayfanın sayacı sıfırdan başlar, orada biten her akış bu eyleme yazılır.
+            const activityAfter = readiness.snapshot?.activity ?? null;
+            const navigated = snapshotBefore !== undefined && readiness.snapshot !== undefined && runtimePath(readiness.snapshot.href) !== runtimePath(snapshotBefore.href);
+            const flowRuns = activityAfter === null
+                ? undefined
+                : navigated
+                    ? activityAfter.completed
+                    : activityBefore === null ? undefined : Math.max(activityAfter.completed - activityBefore.completed, 0);
+            // `tab` adımının KANITI tıklama değil, sonuçta hangi sekmenin açık olduğudur: bileşen
+            // seçimi kendi prop'una yazmadıysa kare hâlâ eski sekmeyi gösterir ve rapor bunu söyler.
+            const activeTab = action.action === 'tab' && typeof action.target === 'string'
+                ? await page.evaluate(activeTabScript(action.target)).catch(() => undefined)
+                : undefined;
+            // G-14 — DOM'a yazmak değerin prop'a ulaştığını kanıtlamaz. İz yalnız okuyucu yayınlanıyor ve
+            // makine düğümü tanıyorsa (dize) karşılaştırılır; aksi hâlde propWritten bilinmez kalır.
+            const propsAfter = typeof before.propsBefore === 'string' && before.applied === true && !navigated
+                ? await page.evaluate(runtimePropsScript(rootElementId(String(action.target ?? '')))).catch(() => undefined)
+                : undefined;
+            const propWritten = typeof propsAfter === 'string' ? propsAfter !== before.propsBefore : undefined;
+            const applied = before.applied === true && propWritten !== false;
+            const note = propWritten === false
+                ? `değer DOM'a yazıldı ama '${rootElementId(String(action.target ?? ''))}' düğümünün runtime prop'ları DEĞİŞMEDİ — bileşen olayı kendi change yoluna çevirmedi ya da değer zaten aynıydı. Çok alanlı bileşende <elementId>__<rol> kutusunu hedefleyin (component_get → internalRoles).`
+                : before.note;
+            outcomes.push({
+                index,
+                action: String(action.action),
+                ...(action.target === undefined ? {} : { target: action.target }),
+                ...(action.to === undefined ? {} : { to: action.to }),
+                found: before.found === true,
+                applied,
+                ...(propWritten === undefined ? {} : { propWritten }),
+                ...(note === undefined ? {} : { note }),
+                requests,
+                ...(flowRuns === undefined ? {} : { flowRuns }),
+                ...(before.matchedBy === undefined ? {} : { matchedBy: before.matchedBy }),
+                ...(typeof activeTab === 'string' ? { activeTab } : {}),
+                ...(before.optionsSeen === undefined ? {} : { optionsSeen: before.optionsSeen }),
+                ...(before.waitedMs === undefined ? {} : { waitedMs: before.waitedMs }),
+                ...(before.submitVia === undefined ? {} : { submitVia: before.submitVia }),
+                pageState: readiness.state
+            });
+        }
+        logStep('tarayıcı ⤵', `${outcomes.length} etkileşim adımı koştu`, outcomes.map(outcome => `${outcome.index}. ${outcome.action}${outcome.target ? ` '${outcome.target}'` : ''}${outcome.to ? ` ⇒ '${outcome.to}'` : ''} → ${outcome.found ? (outcome.applied ? 'uygulandı' : 'bulundu ama uygulanamadı') : 'hedef BULUNAMADI'} · ${outcome.requests} ağ isteği`));
+        return outcomes;
+    }
+    /**
+     * Sayfa hazır olana kadar yoklar; hazır kararını `decideReadiness` verir. Karar verildikten
+     * sonra kısa bir pay bırakılır ve görüntü BİR KEZ DAHA doğrulanır: giriş akışının son adımı
+     * yönlendirmeyse "bitti" sinyali yeni sayfa açılırken gelir ve doğrulama olmadan kare o
+     * geçişte alınırdı. Adres değiştiyse sayaç yeni sayfada sıfırdan başlar; baz da sıfırlanır.
+     *
+     * Döngü hem süreyle hem TUR sayısıyla sınırlıdır: sahte saatle koşan testte `Date.now()`
+     * ilerlemez ve yalnız süreye bakan bir döngü hiç bitmezdi.
+     */
+    async waitForReady(page, options) {
+        const startedAt = Date.now();
+        const deadline = startedAt + options.budgetMs;
+        const maxPolls = Math.ceil(options.budgetMs / flowPollMs) + 1;
+        let completedBefore = options.completedBefore;
+        let previousKey;
+        let quiet = 0;
+        let last;
+        for (let poll = 0; poll < maxPolls; poll++) {
+            const snapshot = parseReadiness(await page.evaluate(readinessScript).catch(() => undefined));
+            if (snapshot === undefined) {
+                // Yönlendirme sırasında evaluate düşer: sessizlik sayacı sıfırlanır, yoklama sürer.
+                previousKey = undefined;
+                quiet = 0;
+            }
+            else {
+                last = snapshot;
+                if (runtimePath(snapshot.href) !== runtimePath(options.baselineUrl))
+                    completedBefore = 0;
+                const key = JSON.stringify(snapshot);
+                quiet = key === previousKey ? quiet + 1 : 0;
+                previousKey = key;
+                const state = decideReadiness(snapshot, quiet, completedBefore, options.baselineUrl);
+                if (state !== undefined) {
+                    await page.waitForTimeout(flowSettleGraceMs);
+                    const confirmed = parseReadiness(await page.evaluate(readinessScript).catch(() => undefined));
+                    if (confirmed !== undefined && !confirmed.skeleton && confirmed.href === snapshot.href && (confirmed.activity === null || confirmed.activity.running === 0)) {
+                        return { state, waitedMs: Date.now() - startedAt, snapshot: confirmed };
+                    }
+                    previousKey = undefined;
+                    quiet = 0;
+                }
+            }
+            if (Date.now() >= deadline || poll === maxPolls - 1)
+                break;
+            await page.waitForTimeout(flowPollMs);
+        }
+        return { state: 'not-ready', waitedMs: Date.now() - startedAt, ...(last === undefined ? {} : { snapshot: last }) };
+    }
+    /**
+     * Viewport büyütmesinden sonra sayfanın YENİDEN YERLEŞMESİNİ bekler. Eski sırada (ölç → büyüt →
+     * eylemler) büyütme sonrası render'ı her eylemin kendi hazırlık döngüsü soğuruyordu; sıra
+     * eylemlerden sonraya alınınca geriye yalnız 600 ms kalmıştı ve `onResize`'a bağlı ya da
+     * sanallaştırılmış bir tablo o pay içinde yeni satırlarını çizmeyebilirdi — özet ve kare
+     * büyütme ÖNCESİ gerçeği anlatırdı (B-4).
+     */
+    async settleAfterResize(page, baselineUrl) {
+        await page.waitForTimeout(settleMs);
+        // Yeni akış beklenmiyor: karar DOM durulmasından çıkar (`ready-no-flows` / `ready-no-counter`).
+        await this.waitForReady(page, { budgetMs: resizeSettleBudgetMs, baselineUrl, completedBefore: Number.POSITIVE_INFINITY });
+    }
+    async captureOne(request) {
+        const startedAt = Date.now();
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.browserPromise ??= this.launch();
+        let browser = await this.browserPromise.catch(error => {
+            this.browserPromise = undefined;
+            throw error;
+        });
+        let context;
+        // Donuk kare (plans/mobil-animasyon-sistemi A6): sonsuz döngülü sayfanın iki karesi hiç aynı
+        // çıkmıyordu. Runtime "hareketi azalt"ı dondurma sebebi sayar ve onu matchMedia'dan canlı okur
+        // (A10); tercih bağlamda verilir ki ilk kareden itibaren geçerli olsun.
+        const contextOptions = {
+            viewport: request.viewport,
+            deviceScaleFactor: (request.dpr ?? 1) * (request.scale ?? 1),
+            ...(request.motion === 'play' ? {} : { reducedMotion: 'reduce' })
+        };
+        try {
+            context = await browser.newContext(contextOptions);
+        }
+        catch {
+            this.browserPromise = this.launch();
+            browser = await this.browserPromise.catch(error => {
+                this.browserPromise = undefined;
+                throw error;
+            });
+            context = await browser.newContext(contextOptions);
+        }
+        logStep('tarayıcı →', `GET ${request.url} · viewport ${request.viewport.width}x${request.viewport.height}${request.fullPage ? ' · fullPage' : ''}${request.token ? '' : ' · gateway jetonu YOK'}${(request.cookies ?? []).length > 0 ? ` · caller çerezleri: ${(request.cookies ?? []).map(cookie => cookie.name).join(', ')}` : ''}${request.token || (request.cookies ?? []).length > 0 ? '' : ' · ANONİM (çerez YOK)'}${request.colorScheme ? ` · tema ${request.colorScheme}` : ''}${request.motion === 'play' ? ' · hareket oynar' : ''}${request.headers ? ` · başlık: ${Object.keys(request.headers).join(', ')}` : ''}`);
+        try {
+            const cookies = new Map();
+            if (request.token)
+                cookies.set('NG_AccessToken', request.token);
+            for (const cookie of request.cookies ?? [])
+                cookies.set(cookie.name, cookie.value);
+            if (cookies.size > 0) {
+                await context.addCookies([...cookies].map(([name, value]) => ({ name, value, url: request.cookieUrl, httpOnly: false })));
+            }
+            // Kullanıcı gözü başlığı sayfa açılmadan kurulur: ilk veri isteği de o kullanıcının gözüyle gitmeli. Yeteneği
+            // olmayan bağlamda kare SESSİZCE gateway kimliğiyle çekilmez, hata verir.
+            if (request.headers && Object.keys(request.headers).length > 0) {
+                if (!context.setExtraHTTPHeaders) {
+                    throw new PlatformApiError(`Başlıklar (${Object.keys(request.headers).join(', ')}) uygulanamadı: tarayıcı bağlamı setExtraHTTPHeaders desteklemiyor. Kare gateway kimliğiyle çekilir ve bu sessizce yanlış olurdu.`);
+                }
+                await context.setExtraHTTPHeaders(request.headers);
+            }
+            // Tema tercihi çerezde değil localStorage'da yaşar ve tema store'u değerini modül İLK
+            // değerlendirildiğinde okur: sayfa açıldıktan sonra yazmak bir sonraki yüklemeye kadar
+            // etkisizdir. Bu yüzden tercih, sayfanın script'lerinden önce koşan bağlam script'iyle
+            // ekilir. Yeteneği olmayan bağlamda çağrı SESSİZCE açık temada kare almaz, hata verir.
+            if (request.colorScheme) {
+                if (!context.addInitScript) {
+                    throw new PlatformApiError(`colorScheme='${request.colorScheme}' uygulanamadı: tarayıcı bağlamı addInitScript desteklemiyor. Tema tercihi sayfa açılmadan ekilmek zorunda; desteksiz bağlamda kare projenin varsayılan modunda çıkardı ve bu sessizce yanlış olurdu.`);
+                }
+                await context.addInitScript(`try { localStorage.setItem(${JSON.stringify(VIEWER_MODE_STORAGE_KEY)}, ${JSON.stringify(request.colorScheme)}) } catch (error) { /* localStorage kapalıysa proje varsayılanı çizilir */ }`);
+            }
+            const page = await context.newPage();
+            // Konsol ve istisna dinleyicileri navigasyondan ÖNCE takılır: modül yüklenirken patlayan
+            // bileşenin hatası ilk karede düşer ve sonradan takılan dinleyici onu kaçırırdı (g-06).
+            const consoleLog = createPageConsoleLog();
+            page.on?.('console', message => consoleLog.onConsole(message));
+            page.on?.('pageerror', error => consoleLog.onPageError(error));
+            // Soğuk Vite derlemesinde sayfanın kendi veri isteği 15 sn'yi aşabiliyor; delayMs bu
+            // bütçeyi de uzatır (09-02 E-2). Yanıt hazırlık döngüsünü BLOKLAMAZ: runtime dışına
+            // yönlendirilen sayfa bu isteği hiç atmaz ve eskiden 15 sn boşa bekleniyordu.
+            const readyBudgetMs = apiResponseTimeoutMs + request.delayMs;
+            const watchApiResponse = () => page
+                .waitForResponse(response => response.url().includes(request.apiPathMarker), { timeout: readyBudgetMs })
+                .then(response => response.status(), () => undefined);
+            // `delayMs` navigasyon bütçesini de uzatır. Eskiden sabit 20 sn'ydi ve soğuk Studio'da
+            // ajanın elinde tek çıkış çağrıyı tekrarlamaktı (09-08 S-8) — "sabrım bu kadar" demenin
+            // tek anlamı olsun diye iki bütçe de aynı düğmeye bağlı.
+            const navigationTimeout = navigationTimeoutMs + request.delayMs;
+            let observedApiStatus = watchApiResponse();
+            let navigationRetried = false;
+            for (let attempt = 1;; attempt++) {
+                try {
+                    await page.goto(request.url, { waitUntil: 'domcontentloaded', timeout: navigationTimeout });
+                    break;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    const timedOut = isNavigationTimeout(message);
+                    if (!timedOut || attempt >= navigationAttempts) {
+                        const attemptNote = attempt > 1 ? ` (${attempt} deneme)` : '';
+                        const budgetNote = timedOut
+                            ? ` Navigasyon bütçesi ${navigationTimeout} ms'ydi; soğuk Studio'da delayMs'i büyütün — o değer artık navigasyonu da uzatır.`
+                            : '';
+                        throw new PlatformApiError(`Studio'ya ulaşılamadı${attemptNote}: ${request.url} — ${message}.${budgetNote} STUDIO_BASE_URL doğru mu, arayüz ayakta mı? (yerelde zeyrek-frontend/apps/studio içinde \`pnpm dev\`)`);
+                    }
+                    navigationRetried = true;
+                    // Veri isteği gözlemi de sıfırlanır: ilk denemeyi bekleyen sayaç çoktan dolmuş olur ve
+                    // yeniden denenen navigasyonun yanıtını kaçırıp boş loader karesi damgalardı.
+                    observedApiStatus = watchApiResponse();
+                    logStep('tarayıcı ⟳', `navigasyon ${navigationTimeout} ms'de düştü, bir kez daha deneniyor — ilk deneme soğuk derlemeyi ısıttı`);
+                }
+            }
+            const readiness = await this.waitForReady(page, { budgetMs: readyBudgetMs, baselineUrl: request.url, completedBefore: 0 });
+            // Gözlendiyse dolu, hâlâ bekleniyorsa (yönlendirme, hata) undefined — ikinci vaat hemen çözülür.
+            const apiStatus = await Promise.race([observedApiStatus, Promise.resolve(undefined)]);
+            const apiNote = apiStatus === undefined ? 'sayfanın veri isteği gözlenmedi' : `veri isteği HTTP ${apiStatus}`;
+            if (readiness.state === 'not-ready' && request.captureUnready !== true) {
+                const failure = describePageFailure(consoleLog, await readRenderErrors(page));
+                throw new PlatformApiError(`Sayfa ${readiness.waitedMs} ms içinde yüklenmedi, kare ALINMADI — ${describeUnready(readiness, apiNote)}.${failure} Bekleme bütçesi ${readyBudgetMs} ms; sayfa yalnız yavaşsa delayMs ile büyütün. Sayfa gerçekten bozuksa page_runtime_get ile şemayı, STUDIO_BASE_URL ve slug'ları doğrulayın. Yüklenmemiş hâli yine de görmek için captureUnready: true verin (kare pageState: 'not-ready' ile döner).`, 504);
+            }
+            await page.evaluate('document.fonts.ready.then(() => true)').catch(() => undefined);
+            const flowsSettled = readiness.state === 'ready' || readiness.state === 'ready-no-flows'
+                ? true
+                : readiness.state === 'not-ready' ? false : undefined;
+            const finalHref = readiness.snapshot?.href;
+            const finalUrl = finalHref !== undefined && runtimePath(finalHref) !== runtimePath(request.url) ? finalHref : undefined;
+            const actions = await this.runActions(page, request, consoleLog);
+            // Ölçüm EYLEMLERDEN SONRA: eylem sekme değiştirir, filtre uygular, panel açar — içerik
+            // boyu o zaman kesinleşir. Eskiden ölçüm eylemlerden önceydi ve ikinci sekmede 40 satırlık
+            // tablo açan bir çekim viewport boyunda kalıyordu; `contentHeight` ilk sekmenin boyuydu
+            // (S-1, 2026-09-16 raporu madde 6). Yalnız YÜKSEKLİK büyür, genişlik sabittir: `hideOn`
+            // kırılım noktaları ve duyarlı yerleşim kareyi çekerken kaymaz (K4).
+            // Doku sınırı RASTER pikseldir: mobil kare @2-3 çekilir, CSS tavanı ölçekle bölünür (web'de
+            // ölçek ≤ 1, tavan 16384 kalır).
+            const heightLimit = Math.floor(maxCaptureHeight / Math.max(1, (request.dpr ?? 1) * (request.scale ?? 1)));
+            const measured = request.fullPage ? await measureContentHeight(page) : undefined;
+            const captureHeight = measured === undefined ? undefined : Math.min(measured, heightLimit);
+            let viewportHeight = request.viewport.height;
+            if (captureHeight !== undefined && captureHeight > viewportHeight) {
+                await page.setViewportSize({ width: request.viewport.width, height: captureHeight });
+                viewportHeight = captureHeight;
+                await this.settleAfterResize(page, readiness.snapshot?.href ?? request.url);
+            }
+            // K7 — kırpma kutusu katlanmış alanın ALTINDAYSA kare boş çıkardı: viewport kutuyu
+            // kapsayana kadar büyütülür (fullPage ile aynı yol) ve kutu YENİDEN okunur, çünkü
+            // büyüyen viewport yerleşimi kaydırabilir.
+            let clip;
+            if (request.clip) {
+                clip = await resolveClip(page, request.clip);
+                if (clip.y + clip.height > viewportHeight) {
+                    const wanted = Math.ceil(clip.y + clip.height) + 8;
+                    if (wanted > heightLimit) {
+                        throw new PlatformApiError(`page_screenshot: kırpma kutusu ${Math.round(clip.y)}+${Math.round(clip.height)} px'te bitiyor ve Chromium'un ${maxCaptureHeight} px'lik doku sınırının${heightLimit === maxCaptureHeight ? '' : ` (bu ölçekte ${heightLimit} CSS px)`} altına sığmıyor — viewport o kadar büyütülemez ve kare kutunun tamamını gösteremezdi. Kutuyu elle daraltın ({ x, y, width, height }) ya da sayfayı bölerek doğrulayın.`);
+                    }
+                    const grown = Math.min(wanted, heightLimit);
+                    await page.setViewportSize({ width: request.viewport.width, height: grown });
+                    viewportHeight = grown;
+                    await this.settleAfterResize(page, readiness.snapshot?.href ?? request.url);
+                    clip = await resolveClip(page, request.clip);
+                }
+            }
+            const layout = request.layoutReport === true
+                ? await page.evaluate(layoutReportScript).then(value => Array.isArray(value) ? value : []).catch(() => [])
+                : undefined;
+            const ledger = await page.evaluate(flowRuntimeErrorsScript)
+                .then(value => Array.isArray(value) ? value : [])
+                .catch(() => []);
+            const { flowErrors: runtimeErrors, expressionErrors } = splitExpressionErrors(ledger);
+            const renderErrors = await readRenderErrors(page);
+            const consoleErrors = consoleLog.consoleErrors(record => isExpressionEcho(expressionErrors, record.text));
+            const pageErrors = consoleLog.pageErrors();
+            // Özet kareden ÖNCE ve büyütmeden SONRA: ikisi de aynı yerleşmiş sayfayı anlatsın.
+            const summaryRaw = request.summary === false
+                ? undefined
+                : await page.evaluate(domSummaryScript(request.viewport.height)).then(value => ({ value })).catch(error => ({ error: error instanceof Error ? error.message : String(error) }));
+            const summary = summaryRaw && 'value' in summaryRaw ? parseDomSummary(summaryRaw.value) : undefined;
+            const summaryUnavailable = summaryRaw === undefined
+                ? undefined
+                : 'error' in summaryRaw
+                    ? summaryRaw.error
+                    : summary === undefined ? 'tarayıcı özet döndürmedi (beklenmeyen biçim)' : undefined;
+            // Olgu doğrulamasında kare HİÇ çekilmez: maliyetin tamamı buradadır (S-5).
+            const format = request.format ?? 'png';
+            const png = request.image === 'none'
+                ? undefined
+                : await page.screenshot({
+                    type: format,
+                    ...(format === 'jpeg' && request.quality !== undefined ? { quality: request.quality } : {}),
+                    fullPage: false,
+                    ...(clip === undefined ? {} : { clip })
+                });
+            const elapsedMs = Date.now() - startedAt;
+            logStep('tarayıcı ←', `${png === undefined ? 'kare YOK (image:none)' : `PNG ${png.byteLength} B`} · ${elapsedMs} ms · hazırlık ${readiness.state} (${readiness.waitedMs} ms) · sayfa API yanıtı ${apiStatus === undefined ? 'gözlenmedi' : `HTTP ${apiStatus}`}${finalUrl === undefined ? '' : ` · yönlendi → ${finalUrl}`}`);
+            if (runtimeErrors.length > 0) {
+                logStep('akış hatası ✕', `${runtimeErrors.length} akış adımı hata bıraktı — sayfa yine 200 döndü`, runtimeErrors.map(error => `${error.step?.name ?? '?'}${error.element ? ` → ${error.element}.${error.property ?? '?'}` : ''}: ${error.message ?? ''}`));
+            }
+            return {
+                ...(png === undefined ? {} : { png, mimeType: format === 'jpeg' ? 'image/jpeg' : 'image/png' }),
+                ...(png === undefined ? {} : (size => size === undefined ? {} : { imageSize: size })(imageSize(png))),
+                ...(clip === undefined ? {} : { clip }),
+                ...(summary === undefined ? {} : { summary }),
+                ...(summaryUnavailable === undefined ? {} : { summaryUnavailable }),
+                apiStatus,
+                renderWaitTimedOut: apiStatus === undefined,
+                elapsedMs,
+                pageState: readiness.state,
+                readyAfterMs: readiness.waitedMs,
+                ...(finalUrl === undefined ? {} : { finalUrl }),
+                ...(measured === undefined ? {} : { contentHeight: measured }),
+                ...(measured !== undefined && measured > heightLimit ? { fullPageTruncated: true } : {}),
+                ...(layout === undefined ? {} : { layout }),
+                ...(actions === undefined ? {} : { actions }),
+                ...(runtimeErrors.length > 0 ? { runtimeErrors } : {}),
+                ...(expressionErrors.length > 0 ? { expressionErrors } : {}),
+                ...(consoleErrors.length > 0 ? { consoleErrors } : {}),
+                ...(pageErrors.length > 0 ? { pageErrors } : {}),
+                ...(renderErrors.length > 0 ? { renderErrors } : {}),
+                ...(flowsSettled === undefined ? {} : { flowsSettled }),
+                ...(navigationRetried ? { navigationRetried: true } : {})
+            };
+        }
+        finally {
+            await context.close().catch(() => undefined);
+            // Zamanlayıcı ÖNCE temizlenir: eskiden her çekim yenisini kurup eskisini bırakıyordu ve
+            // kaçan zamanlayıcı sonraki çekimin ortasında tarayıcıyı kapatıyordu (S-3).
+            if (this.idleTimer)
+                clearTimeout(this.idleTimer);
+            this.idleTimer = setTimeout(() => {
+                const expired = this.browserPromise;
+                this.browserPromise = undefined;
+                expired?.then(instance => instance.close()).catch(() => undefined);
+            }, idleCloseMs);
+            this.idleTimer.unref?.();
+        }
+    }
+}