@appaflytech/zeyrek-ai-mcp 0.0.5 → 0.0.7

package/dist/platform/screenshot.js

@@ -1,18 +1,344 @@
 import { PlatformApiError } from './errors.js';
+import { INTERNAL_ROLE_SEPARATOR, knownInternalRoles } from '../knowledge/componentCatalog.js';
 import { logStep } from '../observability/trace.js';
+/**
+ * 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';
+/**
+ * G-24 — gateway sayfayı kurabiliyor, okuyabiliyor ve çizdirebiliyordu ama üzerinde OLAY
+ * TETİKLEYEMİYORDU: "filtre değişince veri yenileniyor" iddiası yalnız şema okumasıyla
+ * kanıtlanabiliyordu. 09-05 koşusunda üç olay bağının ikisi şemada "bağlı" görünüp gerçekte
+ * çalışmıyordu (form submit hiç doğmuyordu, `code` adımının gövdesi kaydedilmemişti) ve ikisi de
+ * yalnız gerçek tıklamayla görüldü.
+ *
+ * Değer yazarken NATIVE setter kullanılır ve `input`+`change` olayları bubbles ile atılır: DOM
+ * value'sunu düz atamak framework'ün duyduğu olayı üretmez, alan dolu görünür ama akış çalışmaz.
+ * `resource` sayacı "istek gerçekten gitti mi" sorusunu cevaplar — koşuda kusuru kesinleştiren
+ * gözlem tam olarak buydu (ağ kaydında hiç istek yoktu).
+ */
+export function actionScript(action) {
+    const selector = JSON.stringify(`[data-element-id="${String(action.target ?? '')}"]`);
+    const value = JSON.stringify(action.value ?? '');
+    if (action.action === 'click') {
+        return `(function () {
+      var count = performance.getEntriesByType('resource').length;
+      var node = document.querySelector(${selector});
+      if (!node) return { found: false, applied: false, requests: count };
+      var target = node.matches('button, a, [role="button"]') ? node : (node.querySelector('button, a, [role="button"]') || node);
+      target.click();
+      return { found: true, applied: true, requests: count };
+    })()`;
+    }
+    return `(function () {
+    var count = performance.getEntriesByType('resource').length;
+    var node = document.querySelector(${selector});
+    if (!node) return { found: false, applied: false, requests: count };
+    var wanted = String(${value});
+
+    // Açılır kutu (dropdown / multi-select) NATIVE alan değildir: değeri yazmak
+    // hiçbir şey yapmaz, seçeneğe TIKLANMASI gerekir. Liste ancak kutu açıkken
+    // basılır, o yüzden önce kutu açılır, sonra data-value ile seçenek bulunur
+    // (bulunamazsa görünen metinle eşlenir).
+    var combobox = node.querySelector('[role="combobox"], .ng-select__value-container, .ng-multiselect__value-container');
+    if (combobox) {
+      combobox.click();
+
+      // Liste tıklamadan SONRA basılır; aynı tick'te sorgulamak boş sonuç verir.
+      // evaluate döndürülen promise'i bekler, o yüzden seçim bir sonraki tur yapılır.
+      return new Promise(function (resolve) {
+        setTimeout(function () {
+          var options = Array.prototype.slice.call(document.querySelectorAll('[role="treeitem"][data-value]'));
+          var match = options.filter(function (option) { return option.getAttribute('data-value') === wanted; })[0]
+            || options.filter(function (option) { return (option.textContent || '').trim() === wanted; })[0];
+          if (!match) {
+            resolve({ found: true, applied: false, note: "açılır kutu açıldı ama bu değere karşılık gelen seçenek yok: " + wanted + " — options listesini page_runtime_get ile doğrulayın; seçenek sayısı: " + options.length, requests: count });
+            return;
+          }
+          (match.querySelector('button') || match).click();
+          resolve({ found: true, applied: true, requests: count });
+        }, 300);
+      });
+    }
+
+    var field = node.matches('input, select, textarea') ? node : node.querySelector('input, select, textarea');
+    if (!field) return { found: true, applied: false, note: 'düğümde input/select/textarea yok — bu komponent native alan kullanmıyor olabilir, click ile deneyin', requests: count };
+    var proto = field instanceof HTMLSelectElement ? HTMLSelectElement.prototype
+      : (field instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype);
+    if (field instanceof HTMLInputElement && (field.type === 'checkbox' || field.type === 'radio')) {
+      var shouldCheck = wanted === 'true' || wanted === '1' || wanted === 'on';
+      if (field.checked !== shouldCheck) field.click();
+      return { found: true, applied: true, requests: count };
+    }
+    var setter = Object.getOwnPropertyDescriptor(proto, 'value').set;
+    setter.call(field, ${value});
+    field.dispatchEvent(new Event('input', { bubbles: true }));
+    field.dispatchEvent(new Event('change', { bubbles: true }));
+    return { found: true, applied: true, requests: count };
+  })()`;
+}
+/**
+ * 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.
+ */
+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(node.scrollHeight);',
+    '  }',
+    '  return { contentHeight: Math.max.apply(null, heights), viewportHeight: viewportHeight };',
+    '})()'
+].join('\n');
+/**
+ * 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 = [
+    'Array.from(document.querySelectorAll("[data-element-id]")).slice(0, 500).map(function (node) {',
+    '  var rect = node.getBoundingClientRect();',
+    '  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',
+    '  };',
+    '})'
+].join('\n');
+/**
+ * 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) : []';
+/**
+ * Kare ne zaman hazır? (G-30 → B-6, 2026-09-07)
+ *
+ * `delayMs` TAHMİNDİ; 09-05'te runtime koşan akış sayacını yayınlamaya başladı (`@ng-apps/flow`
+ * → flow-runtime-errors.ts) ve bekleme "running sıfır, completed > 0" olunca bitiyordu. Bu şart
+ * mount akışı OLMAYAN sayfada (giriş ekranı) hiç sağlanmaz; akış tetiklemeyen `set` eylemi de
+ * `completed`'ı artırmaz. 09-06·2 koşusunda üç eylemli giriş denemesi bu yüzden 47 sn sürdü;
+ * sentetik ölçümde sayfa 0.3 sn'de hazırken aynı çağrı 48 sn'ydi — süre sayfanın değil, bu
+ * döngünün. Hazırlık artık TEK anlık görüntüden okunur: akış sayacı + Studio'nun yükleme
+ * iskeleti (`ViewDetail.svelte` → `.view-detail > .bx--skeleton__placeholder`) + runtime
+ * düğümleri (`[data-element-id]`) + hata/bulunamadı hâli + adres. Karar `decideReadiness`'ta.
+ *
+ * Yüklenmemiş kare ASLA dönmez: bütçe dolduğunda sayfa hâlâ hazır değilse çağrı hatayla düşer
+ * (`captureUnready: true` teşhis kipi dışında). Bozuk sayfayı görmek istiyorsan hata mesajı
+ * neyin görüldüğünü zaten söyler.
+ */
+export const readinessScript = `(function () { /* readinessSnapshot */
+  var activity = window.__ngAppsFlowActivity;
+  return {
+    activity: activity && typeof activity.running === 'number' && typeof activity.completed === 'number' ? { running: activity.running, completed: activity.completed } : null,
+    runtimeNodes: document.querySelectorAll('[data-element-id]').length,
+    skeleton: !!document.querySelector('.view-detail > .bx--skeleton__placeholder'),
+    viewDetail: !!document.querySelector('.view-detail'),
+    errorState: !!document.querySelector('.view-detail__error, .view-detail .error-page'),
+    readyState: String(document.readyState),
+    href: String(location.href)
+  };
+})()`;
+/** Okunan değer gerçekten sayaç mı; değilse sayfa sayaç yayınlamıyordur (eski runtime). */
+export function isFlowActivity(activity) {
+    if (!activity || typeof activity !== 'object')
+        return false;
+    const { running, completed } = activity;
+    return typeof running === 'number' && typeof completed === 'number';
+}
+/** Tarayıcıdan dönen değer anlık görüntü mü; yönlendirme sırasında evaluate düşer ve undefined kalır. */
+export function parseReadiness(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const value = raw;
+    if (typeof value.runtimeNodes !== 'number' || typeof value.href !== 'string')
+        return undefined;
+    return {
+        activity: isFlowActivity(value.activity) ? { running: value.activity.running, completed: value.activity.completed } : null,
+        runtimeNodes: value.runtimeNodes,
+        skeleton: value.skeleton === true,
+        viewDetail: value.viewDetail === true,
+        errorState: value.errorState === true,
+        readyState: String(value.readyState ?? ''),
+        href: value.href
+    };
+}
+/** `/dev` ve `/view` aynı sayfadır (Studio `hooks.ts` reroute); yönlendirme kararı yalnız yoldan verilir. */
+export function runtimePath(url) {
+    try {
+        return new URL(url).pathname.replace(/^\/dev\//, '/view/').replace(/\/+$/, '');
+    }
+    catch {
+        return url;
+    }
+}
+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;
+/** "Hiç akış koşmadı" kararı için DOM'un kaç yoklama değişmemesi gerekir (~600 ms = eski settleMs). */
+const quietPolls = 5;
+/** Sayaç yayınlanmayan runtime'da tek kanıt DOM durulmasıdır; daha uzun beklenir (~1 sn). */
+const legacyQuietPolls = 8;
+/** Runtime dışına yönlendirme: hedef sayfanın kendi JS'i çizmeyi bitirsin (~1.5 sn). */
+const redirectQuietPolls = 12;
 const idleCloseMs = 60000;
+/** Etkileşim adımındaki `wait` üst sınırı; delayMs tavanıyla aynı çizgide. */
+const maxActionWaitMs = 15000;
+/**
+ * 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);
+}
+/**
+ * Tek anlık görüntüden "kare alınabilir" kararı; iki uçta da yanlış beklememek için tek yerde.
+ * `quiet` görüntünün kaç yoklamadır değişmediğidir, `completedBefore` bu beklemenin başındaki
+ * bitmiş akış sayısı (sayfa değiştiyse çağıran sıfırlar). İskelet görünüyorsa hiçbir karar yok.
+ */
+export function decideReadiness(snapshot, quiet, completedBefore, baselineUrl) {
+    if (snapshot.skeleton)
+        return undefined;
+    const { activity } = snapshot;
+    const idle = activity !== null && activity.running === 0;
+    if (idle && activity.completed > completedBefore && snapshot.runtimeNodes > 0)
+        return 'ready';
+    if (idle && snapshot.runtimeNodes > 0 && quiet >= quietPolls)
+        return 'ready-no-flows';
+    if (activity === null && snapshot.runtimeNodes > 0 && quiet >= legacyQuietPolls)
+        return 'ready-no-counter';
+    if (idle && snapshot.errorState && quiet >= quietPolls)
+        return 'error';
+    if (!snapshot.viewDetail && snapshot.readyState === 'complete' && baselineUrl !== undefined && runtimePath(snapshot.href) !== runtimePath(baselineUrl) && quiet >= redirectQuietPolls)
+        return 'redirected';
+    return undefined;
+}
+/** Hata mesajı için: bütçe dolduğunda sayfada NE görüldü. */
+export function describeUnready(readiness, apiNote) {
+    const snapshot = readiness.snapshot;
+    const suffix = apiNote === undefined ? '' : ` · ${apiNote}`;
+    if (!snapshot)
+        return `tarayıcı sayfayı hiç değerlendiremedi (sürekli yönlendirme ya da bağlam düştü)${suffix}`;
+    if (snapshot.skeleton)
+        return `sayfa hâlâ yükleme iskeletinde${suffix}`;
+    if (snapshot.activity && snapshot.activity.running > 0)
+        return `${snapshot.activity.running} akış hâlâ koşuyor (${snapshot.activity.completed} bitti)${suffix}`;
+    if (snapshot.runtimeNodes === 0)
+        return `runtime hiç render olmadı — data-element-id taşıyan düğüm yok${snapshot.viewDetail ? '' : ', .view-detail kabı da yok'}${suffix}`;
+    return `sayfa durulmadı (${snapshot.runtimeNodes} düğüm, sayaç ${snapshot.activity ? `${snapshot.activity.running} koşan / ${snapshot.activity.completed} biten` : 'yok'})${suffix}`;
+}
+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;
+}
+/**
+ * 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();
@@ -48,7 +374,124 @@ export class StudioScreenshotter {
      * 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 capture(request) {
+    async runActions(page, request) {
+        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)).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.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) {
+                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)}. 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);
+            outcomes.push({
+                index,
+                action: String(action.action),
+                ...(action.target === undefined ? {} : { target: action.target }),
+                found: before.found === true,
+                applied: before.applied === true,
+                ...(before.note === undefined ? {} : { note: before.note }),
+                requests,
+                ...(flowRuns === undefined ? {} : { flowRuns }),
+                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.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 }) };
+    }
+    async captureOne(request) {
         const startedAt = Date.now();
         if (this.idleTimer)
             clearTimeout(this.idleTimer);
@@ -69,32 +512,117 @@ export class StudioScreenshotter {
             });
             context = await browser.newContext({ viewport: request.viewport, deviceScaleFactor: 1 });
         }
-        logStep('tarayıcı →', `GET ${request.url} · viewport ${request.viewport.width}x${request.viewport.height}${request.fullPage ? ' · fullPage' : ''}${request.token ? '' : ' · ANONİM (çerez YOK)'}`);
+        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}` : ''}`);
         try {
-            if (request.token) {
-                await context.addCookies([{ name: 'NG_AccessToken', value: request.token, url: request.cookieUrl, httpOnly: false }]);
+            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 })));
+            }
+            // 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();
-            const observedApiStatus = page
-                .waitForResponse(response => response.url().includes(request.apiPathMarker), { timeout: apiResponseTimeoutMs })
+            // 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);
-            try {
-                await page.goto(request.url, { waitUntil: 'domcontentloaded', timeout: navigationTimeoutMs });
+            // `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ı`);
+                }
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                throw new PlatformApiError(`Studio'ya ulaşılamadı: ${request.url} — ${message}. STUDIO_BASE_URL doğru mu, arayüz ayakta mı? (yerelde zeyrek-frontend/apps/studio içinde \`pnpm dev\`)`);
+            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) {
+                throw new PlatformApiError(`Sayfa ${readiness.waitedMs} ms içinde yüklenmedi, kare ALINMADI — ${describeUnready(readiness, apiNote)}. 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);
             }
-            const apiStatus = await observedApiStatus;
             await page.evaluate('document.fonts.ready.then(() => true)').catch(() => undefined);
-            await page.waitForTimeout(settleMs + request.delayMs);
-            const png = await page.screenshot({ type: 'png', fullPage: request.fullPage });
+            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 measured = request.fullPage ? await measureContentHeight(page) : undefined;
+            const captureHeight = measured === undefined ? undefined : Math.min(measured, maxCaptureHeight);
+            if (captureHeight !== undefined && captureHeight > request.viewport.height) {
+                await page.setViewportSize({ width: request.viewport.width, height: captureHeight });
+                await page.waitForTimeout(settleMs);
+            }
+            const actions = await this.runActions(page, request);
+            const layout = request.layoutReport === true
+                ? await page.evaluate(layoutReportScript).then(value => Array.isArray(value) ? value : []).catch(() => [])
+                : undefined;
+            const runtimeErrors = await page.evaluate(flowRuntimeErrorsScript)
+                .then(value => Array.isArray(value) ? value : [])
+                .catch(() => []);
+            const png = await page.screenshot({ type: 'png', fullPage: false });
             const elapsedMs = Date.now() - startedAt;
-            logStep('tarayıcı ←', `PNG ${png.byteLength} B · ${elapsedMs} ms · sayfa API yanıtı ${apiStatus === undefined ? 'gözlenmedi' : `HTTP ${apiStatus}`}`);
-            return { png, apiStatus, renderWaitTimedOut: apiStatus === undefined, elapsedMs };
+            logStep('tarayıcı ←', `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,
+                apiStatus,
+                renderWaitTimedOut: apiStatus === undefined,
+                elapsedMs,
+                pageState: readiness.state,
+                readyAfterMs: readiness.waitedMs,
+                ...(finalUrl === undefined ? {} : { finalUrl }),
+                ...(measured === undefined ? {} : { contentHeight: measured }),
+                ...(measured !== undefined && measured > maxCaptureHeight ? { fullPageTruncated: true } : {}),
+                ...(layout === undefined ? {} : { layout }),
+                ...(actions === undefined ? {} : { actions }),
+                ...(runtimeErrors.length > 0 ? { runtimeErrors } : {}),
+                ...(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;

package/dist/platform/secrets.js

@@ -0,0 +1,40 @@
+/**
+ * Desen `trace.ts`'in eski kopyasından DARALTILDI: `pass` parçası `passed`/`bypass` gibi
+ * anahtarları da yakalıyordu. Günlükte zararsızdı, tool yanıtında veri kaybı olurdu.
+ */
+export const secretKeyPattern = /password|passwd|secret|token|authorization|api[-_]?key|credential|connection[-_]?string/i;
+import { looksLikeJwt, rememberToken } from './tokenVault.js';
+const maskedValue = '***';
+const maxPaths = 20;
+const maxDepth = 12;
+function walk(value, path, masked, refs, depth) {
+    if (depth > maxDepth)
+        return value;
+    if (Array.isArray(value))
+        return value.map((entry, index) => walk(entry, `${path}[${index}]`, masked, refs, depth + 1));
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, entry] of Object.entries(value)) {
+            const child = path === '' ? key : `${path}.${key}`;
+            if (secretKeyPattern.test(key) && entry !== null && entry !== undefined && entry !== '') {
+                if (masked.length < maxPaths)
+                    masked.push(child);
+                // Maskelenen değer bir JWT ise kimlik testinin yolu kapanmasın: jeton kasada tutulur ve
+                // yanıta yalnız referansı döner (page_screenshot/page_runtime_get asUser onu çözer).
+                // Parola ve API anahtarı bu şekle uymadığı için referans almaz.
+                if (looksLikeJwt(entry) && Object.keys(refs).length < maxPaths)
+                    refs[child] = rememberToken(entry);
+                result[key] = maskedValue;
+                continue;
+            }
+            result[key] = walk(entry, child, masked, refs, depth + 1);
+        }
+        return result;
+    }
+    return value;
+}
+export function maskSecrets(payload) {
+    const masked = [];
+    const tokenRefs = {};
+    return { payload: walk(payload, '', masked, tokenRefs, 0), masked, tokenRefs };
+}