fix: add scoped error logging for lexer/parser errors

- Add std.log.scoped(.pugz) to template.zig and view_engine.zig
- Log detailed error info (code, line, column, message) when parsing fails
- Log template path context in ViewEngine on parse errors
- Remove debug print from lexer, use proper scoped logging instead
- Move benchmarks, docs, examples, playground, tests out of src/ to project root
- Update build.zig and documentation paths accordingly
- Bump version to 0.3.1

examples/demo/views/includes/other.pug

@@ -0,0 +1,2 @@
+.p
+  | some other thing

examples/demo/views/includes/some_partial.pug

@@ -0,0 +1,4 @@
+.info-box
+  h3 Included Partial
+  p This content comes from includes/some_partial.pug
+  p It demonstrates the include directive for reusable template fragments.

examples/demo/views/layouts/base.pug

@@ -0,0 +1,28 @@
+doctype html
+html(lang="en")
+  head
+    meta(charset="UTF-8")
+    meta(name="viewport" content="width=device-width, initial-scale=1.0")
+    link(rel="stylesheet" href="/css/style.css")
+    block title
+      title Pugz Store
+  body
+    header.header
+      .container
+        .header-content
+          a.logo(href="/") Pugz Store
+          nav.nav
+            a.nav-link(href="/") Home
+            a.nav-link(href="/products") Products
+            a.nav-link(href="/about") About
+          .header-actions
+            a.cart-link(href="/cart")
+              | Cart (#{cartCount})
+
+    main
+      block content
+
+    footer.footer
+      .container
+        .footer-content
+          p Built with Pugz - A Pug template engine for Zig

examples/demo/views/mixins/alerts.pug

@@ -0,0 +1,12 @@
+//- Alert/notification mixins
+
+mixin alert(message, type)
+  - var alertClass = type ? "alert alert-" + type : "alert alert-info"
+  .alert(class=alertClass)
+    p= message
+
+mixin alert-dismissible(message, type)
+  - var alertClass = type ? "alert alert-" + type : "alert alert-info"
+  .alert.alert-dismissible(class=alertClass)
+    p= message
+    button.alert-close(type="button" aria-label="Close") x

examples/demo/views/mixins/buttons.pug

@@ -0,0 +1,15 @@
+//- Button mixins with various styles
+
+mixin btn(text, type)
+  - var btnClass = type ? "btn btn-" + type : "btn btn-primary"
+  button(class=btnClass)= text
+
+mixin btn-link(href, text, type)
+  - var btnClass = type ? "btn btn-" + type : "btn btn-primary"
+  a(href=href class=btnClass)= text
+
+mixin btn-icon(icon, text, type)
+  - var btnClass = type ? "btn btn-" + type : "btn btn-primary"
+  button(class=btnClass)
+    span.icon= icon
+    span= text

examples/demo/views/mixins/cart-item.pug

@@ -0,0 +1,17 @@
+//- Cart item display
+
+mixin cart-item(item)
+  .cart-item
+    .cart-item-image
+      img(src=item.image alt=item.name)
+    .cart-item-details
+      h4.cart-item-name #{item.name}
+      p.cart-item-variant #{item.variant}
+      span.cart-item-price $#{item.price}
+    .cart-item-quantity
+      button.qty-btn.qty-minus -
+      input.qty-input(type="number" value=item.quantity min="1")
+      button.qty-btn.qty-plus +
+    .cart-item-total
+      span $#{item.total}
+    button.cart-item-remove(aria-label="Remove item") x

examples/demo/views/mixins/forms.pug

@@ -0,0 +1,25 @@
+//- Form input mixins
+
+mixin input(name, label, type, placeholder)
+  .form-group
+    label(for=name)= label
+    input.form-control(type=type id=name name=name placeholder=placeholder)
+
+mixin input-required(name, label, type, placeholder)
+  .form-group
+    label(for=name)
+      = label
+      span.required *
+    input.form-control(type=type id=name name=name placeholder=placeholder required)
+
+mixin select(name, label, options)
+  .form-group
+    label(for=name)= label
+    select.form-control(id=name name=name)
+      each opt in options
+        option(value=opt.value)= opt.label
+
+mixin textarea(name, label, placeholder, rows)
+  .form-group
+    label(for=name)= label
+    textarea.form-control(id=name name=name placeholder=placeholder rows=rows)

examples/demo/views/mixins/product-card.pug

@@ -0,0 +1,38 @@
+//- Product card mixin - displays a product in grid/list view
+//- Parameters:
+//-   product: { id, name, price, image, rating, category }
+
+mixin product-card(product)
+  article.product-card
+    a.product-image(href="/products/" + product.id)
+      img(src=product.image alt=product.name)
+      if product.sale
+        span.badge.badge-sale Sale
+    .product-info
+      span.product-category #{product.category}
+      h3.product-name
+        a(href="/products/" + product.id) #{product.name}
+      .product-rating
+        +rating(product.rating)
+      .product-footer
+        span.product-price $#{product.price}
+        button.btn.btn-primary.btn-sm(data-product=product.id) Add to Cart
+
+//- Featured product card with larger display
+mixin product-featured(product)
+  article.product-card.product-featured
+    .product-image-large
+      img(src=product.image alt=product.name)
+      if product.sale
+        span.badge.badge-sale Sale
+    .product-details
+      span.product-category #{product.category}
+      h2.product-name #{product.name}
+      p.product-description #{product.description}
+      .product-rating
+        +rating(product.rating)
+        span.review-count (#{product.reviewCount} reviews)
+      .product-price-large $#{product.price}
+      .product-actions
+        button.btn.btn-primary.btn-lg Add to Cart
+        button.btn.btn-outline Wishlist

examples/demo/views/mixins/rating.pug

@@ -0,0 +1,13 @@
+//- Star rating display
+//- Parameters:
+//-   stars: number of stars (1-5)
+
+mixin rating(stars)
+  .stars
+    - var i = 1
+    while i <= 5
+      if i <= stars
+        span.star.star-filled
+      else
+        span.star.star-empty
+      - i = i + 1

examples/demo/views/pages/404.pug

@@ -0,0 +1,15 @@
+extends layouts/base.pug
+
+block title
+  title #{title} | Pugz Store
+
+block content
+  section.error-page
+    .container
+      .error-content
+        h1.error-code 404
+        h2 Page Not Found
+        p The page you are looking for does not exist or has been moved.
+        .error-actions
+          a.btn.btn-primary(href="/") Go Home
+          a.btn.btn-outline(href="/products") View Products

examples/demo/views/pages/about.pug

@@ -0,0 +1,53 @@
+extends layouts/base.pug
+
+block title
+  title #{title} | Pugz Store
+
+block content
+  section.page-header
+    .container
+      h1 About Pugz
+      p A Pug template engine written in Zig
+
+  section.section
+    .container
+      .about-grid
+        .about-main
+          h2 What is Pugz?
+          p Pugz is a high-performance Pug template engine implemented in Zig. It provides both runtime interpretation and build-time compilation for maximum flexibility.
+
+          h3 Key Features
+          ul.feature-list
+            li Template inheritance with extends and blocks
+            li Partial includes for modular templates
+            li Mixins for reusable components
+            li Conditionals (if/else/unless)
+            li Iteration with each loops
+            li Variable interpolation
+            li Pretty-printed output
+            li LRU caching with TTL
+
+          h3 Performance
+          p Compiled templates run approximately 3x faster than Pug.js, with zero runtime parsing overhead.
+
+        .about-sidebar
+          .info-card
+            h3 This Demo Shows
+            ul
+              li Template inheritance (extends)
+              li Named blocks
+              li Conditional rendering
+              li Variable interpolation
+              li Simple iteration
+
+          .info-card
+            h3 Links
+            ul
+              li
+                a(href="https://github.com/ankitpatial/pugz") GitHub Repository
+              li
+                a(href="/products") View Products
+              li
+                a(href="/include-demo") Include Demo
+              li
+                a(href="/") Back to Home

examples/demo/views/pages/cart.pug

@@ -0,0 +1,47 @@
+extends layouts/base.pug
+
+block title
+  title #{title} | Pugz Store
+
+block content
+  section.page-header
+    .container
+      h1 Shopping Cart
+      p Review your items before checkout
+
+  section.section
+    .container
+      .cart-layout
+        .cart-main
+          .cart-items
+            each item in cartItems
+              .cart-item
+                .cart-item-info
+                  h3 #{name}
+                  p.text-muted #{variant}
+                  span.cart-item-price $#{price}
+                .cart-item-qty
+                  button.qty-btn -
+                  input.qty-input(type="text" value=quantity)
+                  button.qty-btn +
+                .cart-item-total $#{total}
+                button.cart-item-remove x
+
+          .cart-actions
+            a.btn.btn-outline(href="/products") Continue Shopping
+
+        .cart-summary
+          h3 Order Summary
+          .summary-row
+            span Subtotal
+            span $#{subtotal}
+          .summary-row
+            span Shipping
+            span.text-success Free
+          .summary-row
+            span Tax
+            span $#{tax}
+          .summary-row.summary-total
+            span Total
+            span $#{total}
+          a.btn.btn-primary.btn-block(href="/checkout") Proceed to Checkout

examples/demo/views/pages/checkout.pug

@@ -0,0 +1,144 @@
+extends layouts/base.pug
+include mixins/forms.pug
+include mixins/alerts.pug
+include mixins/buttons.pug
+
+block content
+  h1 Checkout
+
+  if errors
+    +alert("Please correct the errors below", "error")
+
+  .checkout-layout
+    form.checkout-form(action="/checkout" method="POST")
+      //- Shipping Information
+      section.checkout-section
+        h2 Shipping Information
+
+        .form-row
+          +input-required("firstName", "First Name", "text", "John")
+          +input-required("lastName", "Last Name", "text", "Doe")
+
+        +input-required("email", "Email Address", "email", "john@example.com")
+        +input-required("phone", "Phone Number", "tel", "+1 (555) 123-4567")
+
+        +input-required("address", "Street Address", "text", "123 Main St")
+        +input("address2", "Apartment, suite, etc.", "text", "Apt 4B")
+
+        .form-row
+          +input-required("city", "City", "text", "New York")
+          .form-group
+            label(for="state")
+              | State
+              span.required *
+            select.form-control#state(name="state" required)
+              option(value="") Select State
+              each state in states
+                option(value=state.code)= state.name
+          +input-required("zip", "ZIP Code", "text", "10001")
+
+        .form-group
+          label(for="country")
+            | Country
+            span.required *
+          select.form-control#country(name="country" required)
+            option(value="US" selected) United States
+            option(value="CA") Canada
+
+      //- Shipping Method
+      section.checkout-section
+        h2 Shipping Method
+
+        .shipping-options
+          each method in shippingMethods
+            label.shipping-option
+              input(type="radio" name="shipping" value=method.id checked=method.id == "standard")
+              .shipping-info
+                span.shipping-name #{method.name}
+                span.shipping-time #{method.time}
+              span.shipping-price
+                if method.price > 0
+                  | $#{method.price}
+                else
+                  | Free
+
+      //- Payment Information
+      section.checkout-section
+        h2 Payment Information
+
+        .payment-methods-select
+          label.payment-method
+            input(type="radio" name="paymentMethod" value="card" checked)
+            span Credit/Debit Card
+          label.payment-method
+            input(type="radio" name="paymentMethod" value="paypal")
+            span PayPal
+
+        .card-details(id="card-details")
+          +input-required("cardNumber", "Card Number", "text", "1234 5678 9012 3456")
+
+          .form-row
+            +input-required("expiry", "Expiration Date", "text", "MM/YY")
+            +input-required("cvv", "CVV", "text", "123")
+
+          +input-required("cardName", "Name on Card", "text", "John Doe")
+
+        .form-group
+          label.checkbox-label
+            input(type="checkbox" name="saveCard")
+            span Save card for future purchases
+
+      //- Billing Address
+      section.checkout-section
+        .form-group
+          label.checkbox-label
+            input(type="checkbox" name="sameAsShipping" checked)
+            span Billing address same as shipping
+
+        .billing-address(id="billing-address" style="display: none")
+          +input-required("billingAddress", "Street Address", "text", "")
+          .form-row
+            +input-required("billingCity", "City", "text", "")
+            +input-required("billingState", "State", "text", "")
+            +input-required("billingZip", "ZIP Code", "text", "")
+
+      button.btn.btn-primary.btn-lg(type="submit") Place Order
+
+    //- Order Summary Sidebar
+    aside.order-summary
+      h3 Order Summary
+
+      .summary-items
+        each item in cart.items
+          .summary-item
+            img(src=item.image alt=item.name)
+            .item-info
+              span.item-name #{item.name}
+              span.item-qty x#{item.quantity}
+            span.item-price $#{item.total}
+
+      .summary-details
+        .summary-row
+          span Subtotal
+          span $#{cart.subtotal}
+
+        if cart.discount
+          .summary-row.discount
+            span Discount
+            span -$#{cart.discount}
+
+        .summary-row
+          span Shipping
+          span#shipping-cost $#{selectedShipping.price}
+
+        .summary-row
+          span Tax
+          span $#{cart.tax}
+
+        .summary-row.total
+          span Total
+          span $#{cart.total}
+
+      .secure-checkout
+        span Secure Checkout
+        p Your information is protected with 256-bit SSL encryption

examples/demo/views/pages/home.pug

@@ -0,0 +1,56 @@
+extends layouts/base.pug
+
+block title
+  title #{title} | Pugz Store
+
+block content
+  section.hero
+    .container
+      h1 Welcome to Pugz Store
+      p Discover amazing products powered by Zig
+      .hero-actions
+        a.btn.btn-primary(href="/products") Shop Now
+        a.btn.btn-outline(href="/about") Learn More
+
+  section.section
+    .container
+      h2 Template Features
+      .feature-grid
+        .feature-card
+          h3 Conditionals
+          if authenticated
+            p.text-success You are logged in!
+          else
+            p.text-muted Please log in to continue.
+
+        .feature-card
+          h3 Variables
+          p Title: #{title}
+          p Cart Items: #{cartCount}
+
+        .feature-card
+          h3 Iteration
+          ul
+            each item in items
+              li= item
+
+        .feature-card
+          h3 Clean Syntax
+          p Pug templates compile to HTML with minimal overhead.
+
+  section.section.section-alt
+    .container
+      h2 Shop by Category
+      .category-grid
+        a.category-card(href="/products?cat=electronics")
+          .category-icon E
+          h3 Electronics
+          span 24 products
+        a.category-card(href="/products?cat=accessories")
+          .category-icon A
+          h3 Accessories
+          span 18 products
+        a.category-card(href="/products?cat=home")
+          .category-icon H
+          h3 Home Office
+          span 12 products

examples/demo/views/pages/include-demo.pug

@@ -0,0 +1,20 @@
+extends layouts/base.pug
+
+block title
+  title Include Demo | Pugz Store
+
+block content
+  section.page-header
+    .container
+      h1 Include Demo
+      p Demonstrating the include directive
+
+  section.section
+    .container
+      h2 Content from this page
+      p The box below is included from a separate partial file.
+
+      include includes/some_partial.pug
+
+      h2 After the include
+      p This content comes after the included partial.

examples/demo/views/pages/product-detail.pug

@@ -0,0 +1,65 @@
+extends layouts/base.pug
+
+block title
+  title #{productName} | Pugz Store
+
+block content
+  section.page-header
+    .container
+      .breadcrumb
+        a(href="/") Home
+        span /
+        a(href="/products") Products
+        span /
+        span #{productName}
+
+  section.section
+    .container
+      .product-detail
+        .product-detail-image
+          .product-image-placeholder
+        .product-detail-info
+          span.product-category #{category}
+          h1 #{productName}
+          .product-price-large $#{price}
+          p.product-description #{description}
+
+          .product-actions
+            .quantity-selector
+              label Quantity:
+              button.qty-btn -
+              input.qty-input(type="text" value="1")
+              button.qty-btn +
+            a.btn.btn-primary.btn-lg(href="/cart") Add to Cart
+
+          .product-meta
+            p SKU: #{sku}
+            p Category: #{category}
+
+  section.section.section-alt
+    .container
+      h2 You May Also Like
+      .product-grid
+        .product-card
+          .product-image
+          .product-info
+            span.product-category Electronics
+            h3.product-name Smart Watch Pro
+            .product-price $199.99
+            a.btn.btn-sm(href="/products/2") View Details
+
+        .product-card
+          .product-image
+          .product-info
+            span.product-category Accessories
+            h3.product-name Laptop Stand
+            .product-price $49.99
+            a.btn.btn-sm(href="/products/3") View Details
+
+        .product-card
+          .product-image
+          .product-info
+            span.product-category Accessories
+            h3.product-name USB-C Hub
+            .product-price $39.99
+            a.btn.btn-sm(href="/products/4") View Details

examples/demo/views/pages/products.pug

@@ -0,0 +1,79 @@
+extends layouts/base.pug
+
+block title
+  title #{title} | Pugz Store
+
+block content
+  section.page-header
+    .container
+      h1 All Products
+      p Browse our selection of quality products
+
+  section.section
+    .container
+      .products-toolbar
+        span.results-count #{productCount} products
+        .sort-options
+          label Sort by:
+          select
+            option(value="featured") Featured
+            option(value="price-low") Price: Low to High
+            option(value="price-high") Price: High to Low
+
+      .product-grid
+        .product-card
+          .product-image
+            .product-badge Sale
+          .product-info
+            span.product-category Electronics
+            h3.product-name Wireless Headphones
+            .product-price $79.99
+            a.btn.btn-sm(href="/products/1") View Details
+
+        .product-card
+          .product-image
+          .product-info
+            span.product-category Electronics
+            h3.product-name Smart Watch Pro
+            .product-price $199.99
+            a.btn.btn-sm(href="/products/2") View Details
+
+        .product-card
+          .product-image
+          .product-info
+            span.product-category Accessories
+            h3.product-name Laptop Stand
+            .product-price $49.99
+            a.btn.btn-sm(href="/products/3") View Details
+
+        .product-card
+          .product-image
+            .product-badge Sale
+          .product-info
+            span.product-category Accessories
+            h3.product-name USB-C Hub
+            .product-price $39.99
+            a.btn.btn-sm(href="/products/4") View Details
+
+        .product-card
+          .product-image
+          .product-info
+            span.product-category Electronics
+            h3.product-name Mechanical Keyboard
+            .product-price $129.99
+            a.btn.btn-sm(href="/products/5") View Details
+
+        .product-card
+          .product-image
+          .product-info
+            span.product-category Home Office
+            h3.product-name Desk Lamp
+            .product-price $34.99
+            a.btn.btn-sm(href="/products/6") View Details
+
+      .pagination
+        a.page-link(href="#") Prev
+        a.page-link.active(href="#") 1
+        a.page-link(href="#") 2
+        a.page-link(href="#") 3
+        a.page-link(href="#") Next

examples/demo/views/partials/footer.pug

@@ -0,0 +1,4 @@
+footer.footer
+  .container
+    .footer-content
+      p Built with Pugz - A Pug template engine for Zig

examples/demo/views/partials/head.pug

@@ -0,0 +1,3 @@
+meta(charset="UTF-8")
+meta(name="viewport" content="width=device-width, initial-scale=1.0")
+link(rel="stylesheet" href="/css/style.css")

examples/demo/views/partials/header.pug

@@ -0,0 +1,11 @@
+header.header
+  .container
+    .header-content
+      a.logo(href="/") Pugz Store
+      nav.nav
+        a.nav-link(href="/") Home
+        a.nav-link(href="/products") Products
+        a.nav-link(href="/about") About
+      .header-actions
+        a.cart-link(href="/cart")
+          | Cart (#{cartCount})