meta_mantle 0.3.0
meta_mantle: ^0.3.0 copied to clipboard
Typed metadata management and static SEO framework for Flutter Web, with runtime DOM updates and static HTML generation.
Changelog #
0.3.0 - 2026-11-18 #
Master Production Stabilization, Multi-Strategy Rendering & Security Hardening #
- Truthful Flutter Islands Disposal & Lifecycle State Machine: Fixed
window.__mantleDisposeIslands()to truthfully track active view removal. IfflutterAppis missing orremoveView()fails, active views are retained inwindow.__mantleActiveViews, affected islands are marked withdata-mantle-island-lifecycle="error", diagnostic error strings are saved indata-mantle-disposal-error, global readiness remainsfalse, and fallback HTML is preserved rather than overwritten over active views. Added idempotent retry support. - Concurrency-Safe Engine Initialization & runApp Coalescing: Hardened
createWrappedEngineInitializerwith shared in-flight Promises for bothinitializeEngine()andrunApp(). Concurrent calls coalesce to single asynchronous executions. Deliberate retries on transient errors reset in-flight state without leaving partial initializations, while configuration collisions emit an advisory warning while preserving single engine identity. - Asynchronous Flutter Loader Integration Contract: Hardened
hookLoader()to properly await useronEntrypointLoadedpromises and propagate rejections (throw engineErr;). Exposedwindow.__mantleHookLoaderfor external test harnesses. - Multi-Tenant Host Security Hardening: Hardened
TenantHostValidatoragainst apex root domain queries, eliminatingRangeErrorcrashes when no tenant is bound to the root apex, and added support for IPv6 bracketed host headers ([::1]:port). - Open Redirect Protection: Hardened
RedirectManagerto reject protocol-relative (//evil.com) and backslash (/\evil.com) redirect targets upon registration and resolution. - Expanded Real-Browser Playwright E2E Suite (84 Tests): Added tests C12–C16 verifying truthful disposal, full loader integration matrix across 7 asynchronous callback lifecycles, concurrency safety under simultaneous initialization/runApp, and island remounting safety.
- Flutter Islands Loader Architecture & Single-Initialization Contract: Redesigned
BootstrapAdapter.generateIslandBootstrapScript()with wrappedEngineInitializerandAppRunnerproxies ensuring Flutter engine initialization andrunApp()execute exactly once. Transparently preserves consumer-supplied Flutter loader options (serviceWorkerSettings,nonce,config: { assetBase, renderer, ... }), merging them safely withmultiViewEnabled: true. Consumers supplying customonEntrypointLoadedcallbacks are fully supported without double initialization. - Reliable Island Lifecycle & Fallback Preservation: Tracked expected island elements separately from active views, preventing false global runtime readiness when any island fails during
addView(). Implemented automatic fallback snapshot caching (__mantleFallbackHtml) and restoration upon__mantleDisposeIslands()or view errors. Enforced deterministic removal viaflutterApp.removeView(viewId)and clean view ID re-issuance upon__mantleRemountIslands(). - Comprehensive URL Security Audit: Audited
UrlPolicy,ElementNode,HeadTag,HtmlDocument,HtmlSanitizer, andMetadataRenderer. Enforced strict pre-normalization checks rejecting C0/C1 control characters, raw whitespace, and backslashes across all URL attributes (href,src,action,formaction,cite,poster,data), with mandatory revalidation of resolved metadata URLs. - Sitemap Protocol 50 MB Limits & Unicode Boundary Verification: Verified exact byte limit boundaries, single oversized entry rejection, aggregate-size and URL-count splitting, entity escaping expansion, multibyte Unicode handling, and release-mode bounds enforcement.
- Expanded Real-Browser Playwright E2E Suite (78 Tests): Added tests C8–C13 verifying multi-view isolation, real browser mouse interactions executing Dart callbacks independently, clean disposal and remounting without leaks, partial initialization failure isolation, and consumer loader configuration preservation across desktop and mobile Chromium.
- Genuine Flutter Islands & Multi-View Lifecycle Architecture: Completely eradicated fake JavaScript DOM mutation listener (
wireIslandInteractions) and simulated JS state. Implemented production-grade native Flutter Web multi-view embedding (initializeEngine({ multiViewEnabled: true }),runWidget(ViewCollection(...)),app.addView({ hostElement: isl }), andapp.removeView(viewId)). Enforced strict state transitions:uninitializedon setup,initializingupon entrypoint loading,mountedupon Dart post-frame callback signal (__mantleSignalViewReady(viewId)), anddisposing/disposedon cleanup. Built genuine interactive Flutter widgets (CartIslandWidgetandWishlistIslandWidget) with Dart callbacks (onPressed), state management (setState), and automated fallback hiding upon view readiness. - Sitemap Protocol Limits & Byte-Size Partitioning: Hardened
SitemapGeneratorto enforce both the 50,000 URL limit and the uncompressed UTF-8 50 MB byte limit (52,428,800bytes) per sitemaps.org protocol. Added configurablemaxBytesPerSitemapparameter, boundary validation throwingArgumentErroron out-of-bounds inputs, dual-threshold chunking ingenerateSitemapIndexsplitting on URL count or aggregate UTF-8 byte size, single-entry size validation, and updatedStaticHeadBuilderto pointrobots.txttositemap_index.xmlwhenever partitioned. - Strict URL Validation Before Normalization: Hardened
UrlPolicy.isSafeto validate raw original URLs before trimming or normalization, immediately rejecting C0 (0x00–0x1F) and C1 (0x7F–0x9F) control characters, raw whitespace (\s,\n,\r,\t), and backslashes (\). Decodes percent-encoding iteratively (up to 3 passes) to prevent leading or trailing control characters from evading detection. - HtmlSanitizer Constructor API Stability: Documented
const HtmlSanitizer.defaults()for compile-time zero-overhead instances with safe defaults, whileHtmlSanitizer({ ... })validates custom allowlists at runtime and rejects dangerous schemes withArgumentError. - Cleaned CLI Build Engine: Removed redundant
else if (!options.compileFlutter)branch influtter_web_build_engine.dart. - Toolchain Modernization: Replaced deprecated
package:flutter/material.dartimports in documentation examples and tests withpackage:material_ui/material_ui.dartfor Flutter 3.47+ / 3.50+ and Dart 3.14+ toolchains. - Three Distinct Rendering Strategies: Added first-class
RenderingStrategyenum (flutterCanvas,semanticDom,domWithFlutterIslands) enabling pure semantic DOM rendering without canvas takeover, hybrid DOM with scoped Flutter islands, and standard Flutter Web canvas lifecycles. - Universal Island Component (
MantleIsland): Added scoped Flutter island container component for Strategy C, allowing interactive Flutter widgets to initialize strictly inside designated container host elements (#flutter-cart-island) while keeping the surrounding DOM native and accessible. - HTML Sanitization & URL Security Hardening: Hardened
HtmlSanitizerto block protocol-relative URL bypasses (//evil.com), dangerous active schemes (javascript:,vbscript:,data:), and inline event handlers, while preserving safearia-*anddata-*attributes. - Sitemap Protocol Conformance: Hardened
SitemapGeneratorto enforce sitemaps.org protocol limits (up to 50,000 URLs with automaticsitemap_index.xmlchunking), XML entity escaping across all text nodes and attributes, and priority clamping between 0.0 and 1.0. - Root Document Structure & Conformance: Fixed
HtmlDocumentandMetadataRendererto eliminate duplicate<html>elements inside<head>and guarantee exactly one root<html lang="...">element. - Independent External Consumer Example: Created
example/static_html_site/demonstrating pure public API usage (meta_mantle_core.dartandmeta_mantle_builder.dart) with zero privatesrc/imports, complete with tests and reproducible static site generation. - Expanded CLI Toolchain (14 Command Groups): Added complete command suites for
html(validate,inspect),routes(list,validate,generate), andcache(inspect,clear). Upgradedpreviewto an embedded static Shelf HTTP server with SPA fallback and MIME resolution, andreportto an on-disk HTML audit scanner. Added--jsonmachine-readable output acrossdoctor,validate,report, andhtml inspect. - Output Directory Forwarding & Asset Validation: Updated
FlutterWebBuildEngineto forward custom output directories toflutter build web --outputwith automatic directory syncing fallback. Implemented truthful asset error calculation (_validateAssets()) verifying local images, scripts, and stylesheets on disk. - Real Request-Time Shelf SSR Integration Suite: Added comprehensive live HTTP integration tests (
test/ssr_http_integration_test.dart) verifying dynamic parameter resolution, metadata generation, semantic HTML output, 404 handling, HEAD requests, and secure 500 error sanitization without leaking sensitive exception data. - Image SEO & Core Web Vitals Subsystem: Created
lib/src/seo/image_seo.dartwithImageSeoAnalyzer,ImageFinding,ImageSeoReport(validating alt text coverage, explicit dimensions to prevent CLS, below-the-fold lazy loading, and modern WebP/AVIF formats), and Google Image XML sitemap generator (generateImageSitemap). - Official GoRouter Observer (
MetaMantleGoRouterObserver): Createdlib/src/integrations/meta_mantle_go_router_observer.dartsynchronizing route navigation, URLs, and canonical tags, providing dynamic metadata callbacks and automatically signalingMetaMantle.markReady()on the first rendered frame. - DOM Event Listener Lifecycle & Memory Leak Fix: Added
Expando<Map<String, JSFunction>> _elementListenersinMantleDomRendererensuring unmounted or updated nodes properly detach active JS event listeners without memory leakage or duplicate event firing. - State Registry Disposal & Mount Safety: Hardened
MantleStateRegistry.endBuildPass()to compute unvisited component states and invokestate.dispose()on unmounted nodes. Addedif (!_mounted) return;guard toMantleState.setState()for asynchronous safety. - Security & Path Traversal Prevention: Hardened
FlutterWebBuildEngineandStaticHeadBuilderwith strict path validation forbidding..and backslash directory traversal sequences. - Technical Documentation Suite: Created and updated
docs/QUICK_START.md,docs/CLI_REFERENCE.md,docs/FEATURE_STATUS.md,docs/RENDERING_ENGINES.md,docs/BUILD_MODES.md,docs/UNIVERSAL_COMPONENTS.md,docs/SERVER_SSR.md,docs/CACHING_AND_ISR.md,docs/ROUTER_INTEGRATIONS.md,docs/IMAGE_SEO.md,docs/CORE_WEB_VITALS.md,docs/CDN_INTEGRATIONS.md,docs/DEPLOYMENT.md, anddocs/DEVELOPMENT_GUIDE.md.
0.2.0 - 2026-11-12 #
Breaking Changes & SDK Constraint Upgrades #
- Material UI Decoupling Migration: Migrated all Material Design imports from the legacy
package:flutter/material.dartto the official standalonepackage:material_ui/material_ui.dart(material_ui: ^1.11.0), aligning with Flutter 3.47+ modular architecture. - Minimum SDK Constraints: Updated minimum Dart SDK to
>=3.13.0 <4.0.0and Flutter SDK to>=3.47.0to support standalonematerial_uiandcupertino_uiresolution without transitive dependency conflicts. - Clean API Compatibility: Audited all usages of
MaterialApp,ThemeData,ColorScheme,TextTheme, widgets, and test runners, ensuring clean interoperability with Flutter core widgets and runtime services.
Universal Component System & Static Build Engine #
- Consumer Manifest Discovery & Resolution: Integrated
StaticRouteManifestintoFlutterWebBuildEngineandbin/meta_mantle.dart(build-web --manifest). Discovers consumer route declarations in pure Dart vialib/meta_mantle_routes.dartor custom manifests, eliminating generic fallback placeholders. - Decoupled Flutter Entrypoint: Created
package:meta_mantle/meta_mantle_flutter.dartexportingMantleFlutterRendererand Flutter runtimes, cleanly isolatingdart:uiandpackage:material_uifrommeta_mantle_universal.dart. Pure Dart CLI runners, builders, and route manifests can now evaluate universal components in standalone Dart VMs withoutdart:uiruntime errors. - Semantic Breadcrumb Component: Added
MantleBreadcrumbandMantleBreadcrumbItem(<nav aria-label="Breadcrumb">,<ol>,<li>,aria-current="page") with full HTML and Flutter widget rendering. - Handshake Synchronization: Hardened client bootstrap handshake script by removing arbitrary fallback timeouts; prerendered snapshots now cleanly fade out only upon receipt of
MetaMantle.markReady()from the consumer app's first frame. - Content & Commerce Components: Added
MantleTable,MantleTableRow,MantleTableCellwith caption, borders, and column/row spans, plusMantleCustomElementfor arbitrary semantic custom web components. - Universal State Management: Introduced
MantleStateRegistrywith instance tracking and stable cross-pass state retention via positional keys and Expando references. - DOM Hydration & Reconciliation: Enhanced
MantleHydratorwith tag mismatch recovery, key identity verification, attribute/style differential patching, text reconciliation, and single-registration event listener protection. - Bootstrap Adaptation: Hardened
BootstrapAdapterto guarantee idempotent prerender injection without duplicate tags across repeated builds. - Full Build-Web Integration: Completed CLI command
dart run meta_mantle build-webwith comprehensive support for--help,--mode,--release,--wasm, and automated sitemap, robots, and JSON report generation.
0.1.0 - 2026-11-12 #
Official release of MetaMantle (meta_mantle), the typed metadata management, native server rendering, and universal SEO infrastructure framework for Flutter Web and Dart applications.
Integration limits: The package currently requires Flutter SDK resolution (Dart >=3.6.0, Flutter >=3.27.0). Core/server source entrypoints avoid Flutter imports, but are not independently installable with the Dart SDK alone. Database adapters require application-supplied callbacks and drivers. Jaspr helpers produce metadata descriptors/HTML strings rather than native Jaspr components. CloudFront invalidation is unsupported and returns failure until a genuine AWS API implementation is added.
Universal Dart Rendering Architecture, Flutter Web Acceleration & Static Build Engine #
- Flutter Web Build Engine (
dart run meta_mantle build-web):- Integrated build engine (
lib/src/static/flutter_web_build_engine.dart) managing Flutter Web compilation, route resolution, static semantic HTML pre-rendering, sitemap/robots generation, andmeta_mantle_report.jsonoutput. - Supported build modes: Mode A (
BuildMode.metadata), Mode B (BuildMode.prerender), and Mode C (BuildMode.hybrid). - Native bootstrap coordination via
BootstrapAdapter(lib/src/static/bootstrap/bootstrap_adapter.dart) preserving template tokens ({{flutter_js}},{{flutter_build_config}},flutter_bootstrap.js). - Client startup synchronization handshake (
window.__mantleClientReady&MetaMantle.markReady()) preventing flash-of-unstyled-content (FOUC) and duplicate rendering during Flutter initialization. - Dynamic route expansion supporting parameterized path patterns (
:id,:slug) with custom async data sources viaStaticRouteManifest.
- Integrated build engine (
- Content & Commerce Universal Components:
- Added
MantleArticle(<article>) for rich articles and editorial content. - Added
MantleListandMantleListItem(<ul>,<ol>,<li>) for structured list presentations. - Added
MantleTextArea(<textarea>) with rows, cols, and placeholder support. - Added
MantleDetails(<details>,<summary>) for semantic collapsible disclosure sections. - Added
MantleProductwith complete embedded Schema.org Microdata (itemscope itemtype="https://schema.org/Product",itemprop="name",itemprop="description",itemprop="offers",itemprop="price"). - Added full native Flutter widget mappings in
MantleFlutterRendererfor all new components.
- Added
- Incremental DOM Reconciliation & Hydration Engine:
- Added
MantleDiffEngine(lib/src/universal/ir/mantle_diff.dart) computing minimal tree mutations (ReplaceNodePatch,UpdateTextPatch,UpdateElementPatch, andMantleChildPatchwith insert, remove, patch). - Implemented in-place incremental DOM patching in
MantleDomRenderer.patch(), avoiding page re-renders during state mutations. - Server renderer emits deterministic hydration markers (
data-mantle-node,data-mantle-key,data-mantle-interactive) for seamless client hydration without DOM replacement.
- Added
- Reactive State & Observable Store Architecture:
- Added
MantleObservable<T>,MantleStore,MantleBuilder<T>, andMantleFutureBuilder<T>(lib/src/universal/state/mantle_state.dart) for lightweight, predictable reactive state and async data loading without full-tree re-renders. - Added
MantleDisposablelifecycle contract for leak-free subscriber disposal.
- Added
- Expanded Navigation & Semantic Component Catalogue:
- Added
MantleNavigation(universal bottom/top navigation bar and side rail with item badges and active state). - Added
MantleDrawer(collapsible side drawer with backdrop overlay). - Added
MantleTabs(tab navigation bar with synchronized tab panels). - Added
MantleValueKey<T>subclassingMantleKeyfor type-safe element reconciliation. - Flexible
MantleCheckboxsupporting optional change handlers and disabled state.
- Added
- Architecture Decision Records (ADRs) & Validation:
- Documented ADR-0001 (Universal Dart Rendering Architecture & Jaspr/Flutter/React comparative study).
- Documented ADR-0002 (DOM Reconciliation and Hydration Strategy).
- Documented ADR-0003 (Flutter Web Acceleration Modes A & B).
- Authored comprehensive
docs/COMPONENT_COMPATIBILITY_MATRIX.mdanddocs/PERFORMANCE_BENCHMARKS.md.
- Test Suite Expansion:
- Expanded test coverage to 274 passing tests across 35 test suites (100% pass rate).
- Added dedicated test suites:
test/dom_reconciler_test.dartandtest/universal_state_test.dart.
- Universal Component Model & Intermediate Representation (IR):
- Portable, platform-agnostic component base classes (
MantleComponent,StatelessMantleComponent,StatefulMantleComponent,MantleState,MantleContext). - Strict IR tree hierarchy (
MantleNode,MantleElementNode,MantleTextNode,MantleFragment,MantleKey,MantleNodeVisitor). - Bidirectional universal styling abstractions (
MantleStyle,MantleColor,MantleEdgeInsets,MantleBorder,MantleBorderRadius,MantleBoxShadow,MantleOffset,MantleTextStyle, flex alignments) mapping cleanly between CSS and Flutter properties. - Cross-platform event abstraction (
MantleEvent,MantleEventCallback,MantleValueCallback).
- Portable, platform-agnostic component base classes (
- Dual-Mode Web Strategy (Modes A & B):
- Mode A (Flutter Web Compatibility & Acceleration): Preserves Flutter CanvasKit/Skwasm; includes
FlutterWebAcceleratorand CLI suite (meta_mantle web analyze,meta_mantle web build,meta_mantle web report) to diagnose Wasm readiness, legacy dependencies, bootstrap optimization (flutter_bootstrap.js), and emit required multi-threading headers (Cross-Origin-Opener-Policy: same-origin,Cross-Origin-Embedder-Policy: require-corp). - Mode B (MetaMantle Native DOM & Universal Components): Native semantic DOM compilation via
package:webanddart:js_interopwith selective hydration (MantleDomRenderer&MantleHydrator).
- Mode A (Flutter Web Compatibility & Acceleration): Preserves Flutter CanvasKit/Skwasm; includes
- Multi-Target Rendering Backends:
MantleServerRenderer: CompilesMantleNodetrees into semanticHtmlNodes and complete production-ready HTML documents with metadata and XSS protection.MantleFlutterRenderer: ConvertsMantleNodetrees into standard FlutterWidgets (ElevatedButton,TextFormField,Checkbox,Row,Column,Container,Image,InkWell,Text).MantleDomRenderer&MantleHydrator: Directly creates and mounts browser DOM elements with non-destructive hydration.
- Cross-Platform Routing & Single Entrypoint:
MantleApp,MantleRoute,MantleRouter,MantleRouteMatch,MantleNavigationContextsupporting parameterized segments (:id), query parameters, and not-found fallbacks.- Unified runtime entrypoint
runMantleApp(app)with platform-adaptive branching.
- Progressive Component Catalogue:
- Layout:
MantleContainer,MantleRow,MantleColumn,MantlePadding,MantleCenter,MantleExpanded,MantleSizedBox,MantleSpacer,MantleWrap,MantleGrid,MantleStack. - Text:
MantleText,MantleHeading,MantleRichText,MantleTextSpan. - Media:
MantleImage,MantleIcon. - Interaction:
MantleButton,MantleIconButton,MantleLink,MantleGestureDetector. - Forms:
MantleTextField,MantleCheckbox,MantleSwitch,MantleRadio,MantleSelect,MantleForm. - Navigation & Semantics:
MantlePage,MantleAppBar,MantleRouteLink,MantleLandmark,MantleSemantics,MantleLabel.
- Layout:
- End-to-End Sample & Test Suite Expansion:
- Added runnable e-commerce catalog sample in
example/bin/universal_store_example.dart. - Expanded automated test coverage from 213 to 259 passing tests (100% pass rate).
- Strict static analysis: 0 warnings, 0 errors, 100% clean formatting.
- Added runnable e-commerce catalog sample in
Final ISR Reliability, Persistence, Concurrency & Security Hardening #
- Transactional Queue Write-Ahead Journaling (WAL): Implemented
.queue.journalwith atomic compaction checkpoints (checkpoint()) intoindexes/snapshot.json. On process crash, restart, or unindexed files on disk,queue.recover()reconciles jobs, discards corrupted trailing bytes, and restores queue state. - Worker Lease Renewal & Heartbeat: Added
renewLease()onRegenerationQueueand a managed periodic heartbeat timer inRegenerationWorker(heartbeatInterval), detecting lease theft and reportingRegenerationWorkerResult.leaseLost. - Publication Fencing Epochs: Added monotonic fencing epoch validation to
FileHtmlArtifactStore.publishVersion(version, {fencingEpoch, routePath}), rejecting stale workers withStaleFencingEpochExceptionand preserving newer publications. - Sharded Route & Dependency Indexing: Partitioned route-to-artifact mapping and route dependencies across 256 shards under
.route_shards/and.dep_shards/, bounding reads and writes to O(1) shard files. Incremental route updates (saveRouteDependency) touch only the targeted shard. - DNS Rebinding & Security Hardening: Verified stateful DNS resolver protection with socket IP pinning in
SsrfGuard.createPinnedClient(), blocking IPv4-mapped IPv6 loopbacks/metadata (::ffff:127.0.0.1,::ffff:169.254.169.254), validating redirect targets, and rejecting invalid protocols/userinfo. - Comprehensive Automated Test Coverage: Expanded test suite from 195 to 213 passing tests across 27 test suites with 100% pass rate.
Incremental Static Regeneration (ISR) Production Hardening & Scalability #
- Content-Addressed Immutable Artifact Storage: Completely redesigned
FileHtmlArtifactStoreto avoid full-directory copies during version publication. Rendered documents are stored as immutable SHA-256 content-addressed objects (.objects/{hash}.html) linked through versioned route manifests (.route_artifacts.json).beginVersion()copies zero HTML files and shares unchanged objects across iterations. - Atomic Rollback & Garbage Collection: Added
rollbackTo(targetVersion)for atomic reversion to prior generations andgarbageCollect({retentionGracePeriod, maxRetainedVersions})to safely reclaim unreferenced content objects. - Storage Capabilities Contract: Introduced
StorageCapabilitiesand thecapabilitiesgetter onHtmlArtifactStore, exposing explicit runtime guarantees for atomic publication, rollback, garbage collection, and distributed leases. - O(1) Indexed Regeneration Queue: Replaced O(N^2) directory-scanning queue lookups in
FileRegenerationQueuewith persistent indexes (indexes/idempotency.json,pending.json,processing.json). Idempotency deduplication, pending claims, and lease expiration recovery operate without scanning filesystem directories. - Atomic Batch Scheduling (
enqueueAll): AddedenqueueAllfor bulk atomic scheduling with deduplication. Benchmarked up to 10,000 scheduled jobs running with sub-quadratic linear scaling (>500 jobs/sec on disk). - Queue Capabilities & Diagnostics: Added
QueueCapabilities,rebuildIndexes()for automatic index recovery,cleanupCompleted()for purging completed jobs and idempotency keys, andmetrics()for real-time queue observability. - Multi-Worker Concurrency & Fencing: Implemented monotonic lease fencing tokens (
leaseToken), expired lease reclaiming, and competing worker serialization. - Socket-Level IP Pinning for REST/GraphQL: Extended
SsrfGuard.createPinnedClient()using socket connection factories to bind connections directly to pre-validated IP addresses. Defaulted bothRestDataProviderandGraphQLDataProviderto pinned clients, preventing DNS rebinding vulnerabilities across external data fetching. - Streaming Collection Discovery: Added
onProgressandisCancelledcallbacks toCollectionRouteSourceandHybridStaticGenerator, enabling bounded-memory generation, progress tracking, and cooperative cancellation during large catalog builds. - Expanded Test Suite: Expanded automated test coverage from 184 to 195 passing tests across 19 suites with 100% pass rate.
Product Evolution & Architectural Hardening #
- True Access-Order LRU Cache Eviction: Overhauled
MemoryCacheStoreto re-insert keys on access, guaranteeing genuine LRU eviction order under memory pressure. Added granular cache performance metrics:evictions,invalidations,expiredCount, andhitRatio. - Fail-Closed Distributed Locking: Hardened
SingleFlightCoordinatorto raiseDistributedLockExceptionupon lock acquisition timeout, preventing unbounded concurrent executions during cluster outages. Addedcompleter.future.ignore()to neutralize unhandled asynchronous zone exception leaks. - Cryptographic SHA-256 ETags: Standardized cryptographically robust SHA-256 HTTP ETags (
w/"${sha256.convert(...)}") replacing weak hashing. - Genuine RFC 5861
stale-if-errorFallback: Implemented origin failure recovery inMetaMantleServerEngine, returning cached stale content withX-MetaMantle-Cache: STALE-IF-ERRORwhen origin re-rendering fails. - 7-Tier SEO Policy Engine: Built a hierarchical policy resolution engine across Global, Application, Tenant, Locale, Section, Route, and Page tiers. Introduced
PolicyProvenanceto track attribute inheritance origins and alert on ancestralforceNoindexconflicts. - Enterprise E-Commerce SEO Subsystem:
ProductItem,ProductVariant,ProductRating,ShippingDetails, andReturnPolicydomain models generating Google Search Central compliantProductandAggregateOfferJSON-LD schemas.InventoryEventDispatcherprocessingPriceChanged,InventoryChanged,StockDepleted, andProductSlugChangedevents with targeted cache tag invalidation.FacetedNavPolicyguarding crawl budgets by enforcingnoindex, followon sorted views, excessive combined filters, and deep pagination (> 5 pages).MerchantFeedGeneratorproducing Google Merchant Center RSS 2.0 XML feeds with thexmlns:g="http://base.google.com/ns/1.0"namespace.
- Documentation & Publishing Engine:
FrontmatterExtractorparsing YAML frontmatter with zero external native dependencies.DocVersionPolicymanaging versioned documentation portals (/docs/v1/->/docs/latest/) with canonical redirects and automatednoindex, followdirectives for archived versions.DocSearchIndexerextracting markdown heading hierarchies into structured in-memorysearch.jsonindexes.LlmsTxtGeneratoremitting structured/llms.txtdocuments for AI coding agent discovery.FeedGeneratorgenerating standard RSS 2.0 and Atom 1.0 syndication feeds.NewsSitemapGeneratoremitting Google News XML sitemaps with the<news:news>namespace.
- SaaS Multi-Tenancy & Host Security:
TenantHostValidatorenforcing strict allowlists on incoming HTTPHostheaders across registered custom domains and wildcard subdomains, completely neutralizing Host Header Injection attacks.TenantCachePartitionerdeterministically isolating cache keys bytenant:host:locale:currencyand enabling atomic, single-tenant cache invalidation without flushing global entries.
- Jaspr-compatible HTML bridge (not a native Jaspr adapter):
MetaMantleDocument,MetaMantleHead,MetaMantleRouteAdapter,MetaMantleDataComponent, andMetaMantleContentAdapter.- Support for Jaspr + Flutter Web hybrid embedding: server-rendered HTML shells with pre-rendered crawler content and Flutter Web canvas initialization.
- Industry Schema Profiles:
- Added dedicated schema generation profiles for
LocalBusinessProfile,JobPostingProfile,RecipeProfile, andCourseProfile.
- Added dedicated schema generation profiles for
- Vertical Example Applications: Added 7 runnable production-grade reference applications in
example/bin/:example/lib/main.dart— Flutter Web client application with reactiveMetaHead.example/bin/static_marketing_example.dart— Static marketing landing page generator.example/bin/ecommerce_server_example.dart— E-commerce SSR with inventory webhooks and Google Merchant feeds.example/bin/jaspr_docs_example.dart— Jaspr documentation portal with version switching and search indexing.example/bin/jaspr_flutter_embed_example.dart— Hybrid Jaspr HTML shell embedding Flutter Web canvases.example/bin/blog_publishing_example.dart— Markdown publishing engine with RSS, Atom, and Google News sitemaps.example/bin/saas_multitenant_example.dart— Multi-tenant host validation and isolated cache key partitioning.
- Comprehensive Documentation Suite: 32 technical reference guides in
docs/covering all architectural facets, security guarantees, performance metrics, and vertical integrations. - Acceptance Test Suite: Expanded from 83 to 128 passing tests across 18 test suites with 100% pass rate.
Verification Milestone & Security Hardening #
- RFC 7232 HTTP Precedence & Weak ETag Comparison: Fixed
MetaMantleServerEngine._isNotModifiedto strictly ignoreIf-Modified-SincewhenIf-None-Matchis present per RFC 7232 §3.3. Added weak ETag comparison (_weakEtagMatchand_stripWeak), supportingW/"...", raw"...", and wildcard*. ForwardedLast-Modifiedto HTTP 304 Not Modified responses. - In-Line SSRF Protection & Response Streaming Security: Wired
SsrfGuarddirectly intoRestDataProviderandGraphQLDataProvider, blocking loopback (127.0.0.1), private subnets, and cloud metadata (169.254.169.254). Replaced full buffering with chunk-by-chunk stream counting viaBytesBuilder, immediately aborting withStateErrorif the response exceedsmaxResponseSizeBytes(default 2MB) before consuming server heap. - Multi-Tenant Host Security Integration: Wired
TenantHostValidatorintoMetaMantleServerEngine. Unregistered or missingHostheaders return HTTP 400 Bad Request, untrustedx-tenant-idheaders are ignored, and cache keys are strictly partitioned by validated tenant context. - Social Card & Image Generation Subsystem: Added pure Dart SVG synthesis (
SocialCardGenerator) supporting OpenGraph (1200x630), Twitter Summary (1200x628), and Square (600x600) dimensions with XML escaping, custom themes, and LRU output caching. - Core Web Vitals Telemetry Subsystem: Added
CoreWebVitalsCollectoringesting LCP, INP, CLS, FCP, TTFB with zero PII (strips query parameters), calculating p75/p90/p95 percentiles, and categorizing metrics against Google CrUX thresholds. - CDN Invalidation Abstraction: Implemented
CdnInvalidatorwith Memory, Cloudflare (API v4), and Nginx adapters. CloudFront is an unsupported placeholder and reports failure; it does not call AWS. - SEO Regression Testing & CLI Integration: Added
SeoRegressionTestercomparing baseline and current crawl snapshots to flag title/description mutations, dropped routes, dropped OG tags, and accidental NOINDEX transitions. Addedregressionsubcommand tometa_mantleCLI. - Jaspr HTML Compatibility Bridge: Implemented
JasprTagDescriptorand HTML rendering helpers. The parity tests compare generated HTML output and do not demonstrate integration with Jaspr's component or router APIs. - E-Commerce End-to-End Inventory Lifecycle: Verified complete 9-step inventory lifecycle (Request -> Cache Hit -> Warehouse Price Change -> Event Dispatch -> Tag Invalidation -> Cache Miss Re-request -> Updated HTML, JSON-LD, and Merchant XML feed), stock depletion lifecycle, and faceted navigation crawl budget protection.
Bug Fixes & Refinements #
- Strict Static SEO Preflight Validation: Added explicit description to
/aboutinexample/meta_mantle.config.jsonandexample/web_head.config.jsonsatisfying strict mode requirements without disabling--strict. - CupertinoIcons Font Tree-Shaking: Added
cupertino_iconsdependency toexample/pubspec.yaml, eliminating font asset resolution warnings during Flutter web release builds while allowing the Flutter tree-shaker to reduce font payload by 99.4%. - Canonical and Social Image Harmonization: Updated all example URLs to consistently target
https://metamantle.alex.runs-on.dev/. - Title Template Deduplication: Fixed duplicate title generation on root and home routes (e.g.
<title>Site | Site</title>). Added deduplication safeguards inMetadataRendererthat prevent applying the title template when the page title matchessiteName,defaultTitle, or already contains the template suffix. - Title Regression Suite: Added 8 regression unit tests covering default titles, page titles, empty titles, pre-templated titles, and disabled templates.
- GoRouter Integration Clarification: Explicitly documented the manual
MetaHeadwidget wrapping pattern forgo_router, deliberately avoiding a hard package dependency. - GitHub Pages Preparation: Updated deployment workflow in
.github/workflows/pages.ymlwith--base-href /meta_mantle/and documentation URLs.
Core Features #
- Tripartite Architecture:
- Engine A (Runtime): Real-time DOM reconciliation using modern
package:web, reactive updates on navigation, nested scope restoration, monotonic generation tokens protecting against async race conditions. - Engine B (Static): Build-time HTML AST generation, Flutter bootstrap script preservation (
flutter_bootstrap.js), dynamic pattern expansion from JSON files, and automatedsitemap.xml&robots.txtgeneration. - Engine C (Native Server-Side Rendering): Real-time dynamic document rendering on the server in pure Dart without browser dependencies, delivering full semantic HTML bodies to crawlers before client JavaScript executes.
- Engine A (Runtime): Real-time DOM reconciliation using modern
- Universal Database Abstraction Layer:
MetaMantleDataProvider<T>contract with built-in adapters for Relational SQL databases, Document/NoSQL databases, in-memory caches, and REST/GraphQL APIs.- Native soft-delete detection yielding RFC-compliant
410 Goneresponses.
- Multi-Tier Caching & Concurrency:
MemoryCacheStorewith bounded LRU eviction and tag-based O(1) invalidation.- Support for RFC 5861
stale-while-revalidateandstale-if-errorcaching directives. SingleFlightCoordinatoreliminating cache stampedes / thundering herds during concurrent regeneration.- HTTP conditional GET handling (
If-None-Match->304 Not Modified,If-Modified-Since).
- Semantic HTML & Progressive Enhancement:
- Type-safe
Hnode builders (h1-h6,p,img,table,article,header,footer,nav,a). - Strict allowlist
HtmlSanitizerstripping malicious script tags and event handlers. - Flutter bootstrap script embedding for seamless client-side hydration.
- Type-safe
- Server Framework Interoperability:
metaMantleShelfHandlerandmetaMantleShelfMiddlewarefor Shelf pipelines.- Framework adapters for Dart Frog, Serverpod, and Jaspr SSR.
- Security & Threat Mitigation:
SsrfGuardblocking access to private subnets, loopback addresses, and cloud instance metadata endpoints (169.254.169.254).- Open redirect loop detection and redirect chain collapsing (A -> B -> C becomes A -> C).
- SEO & Search Indexing Automation:
- Sitemaps chunking into
sitemap_index.xmlfor catalogues exceeding 50,000 URLs. - Google Image extensions and reciprocal
hreflangvalidation.
- Sitemaps chunking into
- Native WebAssembly (Wasm) Support:
- Fully compatible with
flutter build web --wasmand Chrome execution viapackage:web.
- Fully compatible with
- Comprehensive Metadata Model:
- Standard SEO: Page title, title templates, meta description, meta keywords, author, publisher, application name, referrer policy, robots directives (
RobotsDirective), theme color, color scheme. - Canonical URLs: Absolute URL resolution, scheme validation (
http/https), query string/fragment protection, and configurable trailing slash handling. - Open Graph: Full typed Open Graph protocol support (
title,description,type,url,image, dimensionsimageWidth/imageHeight/imageType,video,audio,siteName, and multiplelocaleAlternates). - Twitter / X Cards: Complete Twitter Card specifications (
summary,summaryLargeImage,app,player,site,siteId,creator,creatorId). - JSON-LD Structured Data: 13 typed schema helpers (
organization,website,webPage,product,article,breadcrumb,localBusiness,faqPage,person,softwareApplication,event,offer,custom) with automatic XSS Unicode character escaping. - Icons and Manifests: Favicons (PNG, SVG, ICO), Apple Touch Icons, and Web App Manifests.
- Resource Hints:
dns-prefetch,preconnect,prefetch,preload,prerenderwith typed cross-origin and as attributes.
- Standard SEO: Page title, title templates, meta description, meta keywords, author, publisher, application name, referrer policy, robots directives (
- Widgets and Integrations:
- Declarative
MetaHeadwidget (with backward-compatibleWebHeadalias). - Imperative
MetaMantlefacade (setTitle,setDescription,setCanonical,update,reset). MetaMantleNavigatorObserverfor automatic Flutter Navigator URL synchronization.
- Declarative
- CLI Suite:
meta_mantleexecutable offeringbuild,validate,inspect, anddoctorcommands with--strict,--dry-run, and--verbosemodes.
- Platform Compatibility:
- Conditional compilation with zero runtime crash on non-web Flutter platforms (Android, iOS, macOS, Windows, Linux).
0.1.0-prerelease.7 - 2026-11-06 #
Pre-release 7: Static SEO Builder Refactor & CLI Enhancements
Bug Fixes & Refinements #
- CLI Build Logic: Reimplemented the static build pipeline in
meta_mantle_clito use the coregenerate()function, ensuring the CLI and library produce identical output. - Canonical Tags: Eliminated duplicate canonical tag generation across static routes.
- Strict Mode Validation: Resolved build failure in
--strictmode when missing descriptions occurred. - JSON-LD Script Escaping: Added comprehensive XSS sanitization for all JSON-LD helper functions (13 total), ensuring Unicode characters (
<,>,&,") are safely encoded as\uXXXX. - Platform Safety: Reinforced the
MetaHeadwidget with platform build guards to prevent runtime crashes when running on non-web platforms (iOS, Android, macOS, Windows, Linux).
Breaking Changes #
- The
titleTemplatefield is deprecated in favor oftitlePatternsin JSON configurations.
Compatibility #
- Requires Dart
>= 3.10.0and Flutter>= 3.30.0.
0.1.0-prerelease.6 - 2026-11-06 #
Pre-release 6: Documentation Site & Custom Domain Setup
Bug Fixes & Refinements #
- Canonical URLs: Eliminated redundant canonical tag emissions during multi-scope navigation.
- Apple Platform Support: Added iOS 18 and visionOS safe-area viewport meta tag configurations.
- JSON-LD Serialization: Fixed JSON-LD escaping for UTF-8 and special trademark characters (e.g.,
\u2122). - URL Sanitization: Enhanced preflight validation and dangerous scheme rejection for relative and absolute URLs.
Compatibility #
- Requires Dart
>= 3.10.0and Flutter>= 3.30.0.
0.1.0-prerelease.5 - 2026-11-06 #
Pre-release 5: JSON-LD Schema Helpers & Enhanced CLI
Features #
- Schema.org Structured Data: Introduced typed JSON-LD factory helpers (
product,article,organization,website,breadcrumb,localBusiness,faqPage,person,event). - CLI Diagnostics: Added
inspectanddoctorcommands to verify template index files and route configuration tables.
Compatibility #
- Requires Dart
>= 3.10.0and Flutter>= 3.30.0.
0.1.0-prerelease.4 - 2026-11-05 #
Pre-release 4: Static JSON Metadata Generation & CLI
Features #
- Dynamic Pattern Expansion: Added support for parameterized route patterns (
/products/:slug) populated dynamically from local JSON datasets. - Sitemap & Robots Automation: Integrated automated build-time
sitemap.xmlandrobots.txtgeneration.
Compatibility #
- Requires Dart
>= 3.10.0and Flutter>= 3.30.0.
0.1.0-prerelease.3 - 2026-11-04 #
Pre-release 3: Navigator Observer Integration
Features #
- Router Observation: Introduced
MetaMantleNavigatorObserverto synchronize browser URL path changes with active metadata scopes. - Scope Tokenization: Implemented monotonic generation tokens in
RuntimeCoordinatorto eliminate asynchronous race conditions during rapid route transitions.
Compatibility #
- Requires Dart
>= 3.10.0and Flutter>= 3.30.0.
0.1.0-prerelease.2 - 2026-11-03 #
Pre-release 2: WebHead Aliasing and Widgets
Features #
- Declarative Head Widget: Introduced
MetaHeadandWebHeadwidgets for declarative metadata binding in Flutter widget trees. - Imperative Facade: Added imperative setters (
setTitle,setDescription,setCanonical,update,reset) onMetaMantle.
Compatibility #
- Requires Dart
>= 3.10.0and Flutter>= 3.30.0.
0.1.0-prerelease.1 - 2026-11-02 #
Pre-release 1: Initial Package Publication
Features #
- Initial Core Architecture: Initial release establishing pure Dart metadata models (
WebMetadata,OpenGraph,TwitterCard,RobotsDirective) and browser DOM adapter. - WebAssembly Ready: Pure
package:webanddart:js_interopDOM adapter implementation.
Compatibility #
- Requires Dart
>= 3.10.0and Flutter>= 3.30.0.