Hybrid Giriş

@lentystyle/hybrid, compiler ile runtime arasındaki entegrasyon katmanıdır. İkisinin yerini almaz; Node tarafında generated CSS, manifest veya payload artifact ve opsiyonel HTML rewrite akışını koordine eder.

Compiler -> Hybrid -> Runtime

Hybrid Ne Yapar

.luis kaynaklarını global, initial veya route-aware modda derler
Ortak generated CSS ile global manifest veya route runtime payload dosyaları üretir
Static-site build ve dev entegrasyonunu yürütür
Browser payload dispatch ve rescan helper'ları sunar
Framework adapter'ları için generic factory'ler sunar
Compile başlamadan önce source ve HTML envelope girdilerini @lentystyle/core/guard/hybrid ile validate eder

Guard Profili

Hybrid, compilation öncesinde @lentystyle/core/guard/hybrid çalıştırır.

HTML tabanlı akışlarda bu adapter:

varsayılan olarak balanced preset'ini kullanır
htmlMode: 'hybrid' zorlar
framework dev script'lerini SSR-only script allowlist'inin dışında tutar
geçersiz route HTML veya source envelope girdilerini compile başlamadan önce durdurabilir

Default guard akışı

Config-driven build ve dev akışlarında guard'ı ayrıca açmazsınız; hybrid bunu sizin yerinize çağırır.

import { runHybridProjectBuild } from '@lentystyle/hybrid'

await runHybridProjectBuild()

Yerleşik policy aktif build moduna göre değişir:

global: preset: 'trusted-build', allowedLocalRoots: sourceRoots
initial ve route-aware HTML: preset: 'balanced', htmlMode: 'hybrid'

Ne zaman özel guard ayarı gerekir

luis.config.mjs içindeki hybrid bloğu şu anda guardPolicy alanı sunmaz. Özel bir policy gerekiyorsa low-level compileHybridBundle() API'sine inmeniz gerekir.

import { compileHybridBundle } from '@lentystyle/hybrid/node'

await compileHybridBundle({
  routeId: '/docs/',
  html: '<html><head></head><body><div class="card"></div></body></html>',
  guardPolicy: {
    preset: 'strict',
    htmlMode: 'hybrid',
    allowedLocalRoots: ['D:/project/public/styles'],
    allowedRemoteImportOrigins: ['https://cdn.example.com'],
  },
  sources: [
    {
      sourceId: '/styles/docs.luis',
      source: '.card { color: #0f172a; }',
    },
  ],
})

Bu yol, low-level hybrid compile davranışını korurken daha sıkı ya da daha açık doğrulama istediğiniz durumlar içindir.

Önerilen Başlangıç

Node tabanlı projelerde önerilen yol config dosyası ve tek build komutudur.

@lentystyle/hybrid kurun
Proje köküne luis.config.mjs oluşturun
buildMode, sourceRoots, luisOutputDir ve ilgili ayarları tanımlayın
lentystyle-hybrid build script'i ekleyin
Aynı config'i dev middleware veya Vite plugin tarafında yeniden kullanın

import { defineLuisConfig } from '@lentystyle/core/config'

export default defineLuisConfig({
  hybrid: {
    buildMode: 'initial',
    sourceRoots: ['./public', './dist'],
    luisOutputDir: './dist/_hybrid',
    assetBaseUrl: '/_hybrid',
    globalCssFileName: 'lentystyle-global.css',
    defaultRuntimeOptions: 'debug,performance',
  },
})

{
  "scripts": {
    "build": "astro build && pnpm exec lentystyle-hybrid build"
  }
}

Build ve Dev Akışı

Build

pnpm exec lentystyle-hybrid build komutu:

luis.config.mjs dosyasını okur
buildMode: 'initial' (varsayılan): route HTML dosyalarını tarar, non-observed + ilk snapshot'ta eşleşen ?/?! observed kuralları tek ortak CSS'e yazar, source taşıyan HTML dosyalarına bu generated CSS link'ini ekler ve eşleşmeyen observed kuralları runtime'a bırakır
buildMode: 'global': tüm .luis source'larını boş HTML'e karşı derler, tek ortak CSS dosyası ve tek global manifest yazar, tüm observed kurallar runtime'a kalır ve htmlOutputDir explicit ise generated CSS link'ini HTML'e ekler
buildMode: 'route': route HTML veya source candidate'larını tarar, route payload artifact'lerini yazar
derleme öncesinde guard preflight çalıştırır
route-scope CSS dosyalarını yalnız writeRouteCssArtifacts: true ayarlanırsa yazar (yalnızca route modu)

Dev

createHybridProjectDevMiddleware() veya createHybridProjectDevIntegration():

aynı config'i yeniden kullanır
in-memory asset üretir
global veya initial modu tek in-memory CSS + manifest üzerinden servis eder
buildMode: 'route' için HTML response'larını route bazında rewrite eder
guard preflight'ı dev akışı içinde tutar

Vite

Vite projeleri aynı config'i @lentystyle/hybrid/vite üzerinden tüketebilir.

Build modu notu

buildMode: 'initial' (varsayılan) route HTML'i tarar ve her route'u gerçek ilk HTML snapshot'ına karşı derler. Non-observed kurallar ve ilk snapshot'ta eşleşen observed kurallar tek paylaşılan CSS'e girer; source taşıyan HTML dosyaları bu generated CSS link'ini alır ve orijinal .luis tag'leri observed-only fallback olarak işaretlenir. İlk snapshot'ta eşleşmeyen observed kurallar runtime manifest'inde kalır.

buildMode: 'global' route HTML'e karşı derleme yapmaz. Her .luis source'u boş HTML'e karşı derlenir ve tek paylaşılan CSS ile tek global manifest dosyası üretilir. htmlOutputDir explicit verilmiş ve mevcutsa ilk boya için generated CSS link'i ile observed-only source marker'ları route HTML dosyalarına da yazılır. Route HTML çıktısı yoksa source-only artifact build olarak kalır.

buildMode: 'route' route-aware HTML taramasını etkinleştirir. Route HTML dosyalarını default olarak ./dist olan htmlOutputDir altından okur ve route başına payload artifact yazar.

Hybrid İçinde Runtime ve Guard Ayrımı

Hybrid bu iki rolü bilinçli olarak ayrı tutar:

browser runtime yine convenience odaklı payload uygulama işini yapar
@lentystyle/core/guard/hybrid, compile başlamadan önce source ve HTML envelope girdilerini sertleştirir

Bu yüzden hybrid proje build sonrası browser runtime davranışını kullanmaya devam edebilirken, compile sınırı Node tarafında fail-closed kalır.

Sonraki Adım

Proje ayarları için Config
Browser tarafı davranışı için Browser Runtime
Fail-closed validation modeli için @lentystyle/core/guard/hybrid