@whittakertech/virgil 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2025-12-30
+### Added
+- Allow optional image blocks in templates via presence-based guards (`if / endif`)
+- Reconfigure template to conditionally render brand and product logos
+
+## [0.1.0] - 2025-12-29
+### Added
+- Initial Virgil specification for build-time artifact generation
+- Support for Open Graph image generation via headless Chromium (Playwright)
+- Deterministic OG image rendering from HTML/CSS templates
+- Cache-busted asset filenames for safe static deployment
+- `virgil.manifest.json` output mapping stable IDs to generated artifacts
+- Brand and product configuration support (name, color, version)
+- Page metadata support for OG images (title, URL, description)
+
+### Notes
+- This release establishes Virgil’s core philosophy: deterministic, build-time artifact generation with no runtime dependencies
+- Template rendering supports static variable substitution only (no logic or control flow)

package/dist/generators/og-image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"og-image.d.ts","sourceRoot":"","sources":["../../src/generators/og-image.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAK7E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG1D"}
+{"version":3,"file":"og-image.d.ts","sourceRoot":"","sources":["../../src/generators/og-image.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAK7E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAWD;;GAEG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAG1D"}

package/dist/generators/og-image.js

@@ -4,6 +4,15 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { ensureParentDir } from '../utils/fs.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
+function getPath(obj, path) {
+    return path
+        .split('.')
+        .reduce((acc, key) => {
+        if (acc == null || typeof acc !== 'object')
+            return undefined;
+        return acc[key];
+    }, obj);
+}
 /**
  * Generate OG image using Playwright
  */
@@ -11,11 +20,25 @@ export async function generateOGImage(ctx, outputPath) {
     // Load template
     const templatePath = ctx.templatePath || join(__dirname, '../templates/og-default.html');
     let html = await readFile(templatePath, 'utf-8');
+    const renderCtx = {
+        brand: ctx.brand,
+        product: ctx.product,
+        page: ctx.output.page,
+        output: ctx.output
+    };
+    // Omit falsy blocks
+    const IF_BLOCK = /{{\s*if\s+([a-zA-Z0-9_.]+)\s*}}([\s\S]*?){{\s*endif\s*}}/g;
+    html = html.replace(IF_BLOCK, (_, condition, body) => {
+        const value = getPath(renderCtx, condition);
+        return value !== undefined && value !== null ? body : '';
+    });
     // Replace placeholders
     html = html
         .replace(/{{brand.name}}/g, ctx.brand.name)
+        .replace(/{{brand.logo}}/g, ctx.brand.logo || '')
         .replace(/{{brand.color}}/g, ctx.brand.color)
         .replace(/{{product.name}}/g, ctx.product.name)
+        .replace(/{{product.logo}}/g, ctx.product.logo || '')
         .replace(/{{product.version}}/g, ctx.product.version)
         .replace(/{{page.title}}/g, ctx.output.page.title)
         .replace(/{{page.url}}/g, ctx.output.page.url)

package/dist/generators/og-image.js.map

@@ -1 +1 @@
-{"version":3,"file":"og-image.js","sourceRoot":"","sources":["../../src/generators/og-image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAS1D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,GAAmB,EACnB,UAAkB;IAElB,gBAAgB;IAChB,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,SAAS,EAAE,8BAA8B,CAAC,CAAC;IACzF,IAAI,IAAI,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAEjD,uBAAuB;IACvB,IAAI,GAAG,IAAI;SACR,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1C,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC;SAC5C,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;SAC9C,OAAO,CAAC,sBAAsB,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC;SACpD,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;SACjD,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;SAC7C,OAAO,CAAC,uBAAuB,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAEvE,0BAA0B;IAC1B,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;IACxC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC;QACjC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;KACvC,CAAC,CAAC;IAEH,wCAAwC;IACxC,MAAM,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC,CAAC;IAE1D,iCAAiC;IACjC,MAAM,eAAe,CAAC,UAAU,CAAC,CAAC;IAElC,aAAa;IACb,MAAM,IAAI,CAAC,UAAU,CAAC;QACpB,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IAEH,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,EAAU;IAChD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAChD,OAAO,GAAG,EAAE,IAAI,SAAS,MAAM,CAAC;AAClC,CAAC"}
+{"version":3,"file":"og-image.js","sourceRoot":"","sources":["../../src/generators/og-image.ts"],"names":[],"mappings":"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"}

package/dist/templates/og-default.html

@@ -83,7 +83,13 @@
 <body>
   <div class="container">
     <div class="header">
-      <div class="brand">{{brand.name}}</div>
+      {{ if brand.logo }}
+        <div class="image">
+          <img src="{{brand.logo}}" alt="{{brand.name}} logo">
+        </div>
+      {{ endif }}
+      <div class="product">{{product.name}}</div>
+      <div class="version">v{{product.version}}</div>
     </div>
 
     <div class="content">
@@ -92,8 +98,12 @@
     </div>
 
     <div class="footer">
-      <div class="product">{{product.name}}</div>
-      <div class="version">v{{product.version}}</div>
+      {{ if brand.logo }}
+        <div class="image">
+          <img src="{{brand.logo}}" alt="{{brand.name}} logo">
+        </div>
+      {{ endif }}
+      <div class="brand">{{brand.name}}</div>
     </div>
   </div>
 </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whittakertech/virgil",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Build-phase sigil forge for static site artifacts",
   "type": "module",
   "main": "./dist/index.js",

package/src/generators/og-image.ts

@@ -14,6 +14,15 @@ export interface OGImageContext {
   templatePath?: string;
 }
 
+function getPath(obj: unknown, path: string): unknown {
+  return path
+      .split('.')
+      .reduce((acc: any, key) => {
+        if (acc == null || typeof acc !== 'object') return undefined;
+        return acc[key];
+      }, obj);
+}
+
 /**
  * Generate OG image using Playwright
  */
@@ -25,15 +34,31 @@ export async function generateOGImage(
   const templatePath = ctx.templatePath || join(__dirname, '../templates/og-default.html');
   let html = await readFile(templatePath, 'utf-8');
 
+  const renderCtx = {
+    brand: ctx.brand,
+    product: ctx.product,
+    page: ctx.output.page,
+    output: ctx.output
+  }
+  // Omit falsy blocks
+  const IF_BLOCK =
+      /{{\s*if\s+([a-zA-Z0-9_.]+)\s*}}([\s\S]*?){{\s*endif\s*}}/g;
+  html = html.replace(IF_BLOCK, (_, condition, body) => {
+    const value = getPath(renderCtx, condition);
+    return value !== undefined && value !== null ? body : '';
+  });
+
   // Replace placeholders
   html = html
-    .replace(/{{brand.name}}/g, ctx.brand.name)
-    .replace(/{{brand.color}}/g, ctx.brand.color)
-    .replace(/{{product.name}}/g, ctx.product.name)
-    .replace(/{{product.version}}/g, ctx.product.version)
-    .replace(/{{page.title}}/g, ctx.output.page.title)
-    .replace(/{{page.url}}/g, ctx.output.page.url)
-    .replace(/{{page.description}}/g, ctx.output.page.description || '');
+      .replace(/{{brand.name}}/g, ctx.brand.name)
+      .replace(/{{brand.logo}}/g, ctx.brand.logo || '')
+      .replace(/{{brand.color}}/g, ctx.brand.color)
+      .replace(/{{product.name}}/g, ctx.product.name)
+      .replace(/{{product.logo}}/g, ctx.product.logo || '')
+      .replace(/{{product.version}}/g, ctx.product.version)
+      .replace(/{{page.title}}/g, ctx.output.page.title)
+      .replace(/{{page.url}}/g, ctx.output.page.url)
+      .replace(/{{page.description}}/g, ctx.output.page.description || '');
 
   // Launch headless browser
   const browser = await chromium.launch();

package/src/templates/og-default.html

@@ -83,7 +83,13 @@
 <body>
   <div class="container">
     <div class="header">
-      <div class="brand">{{brand.name}}</div>
+      {{ if brand.logo }}
+        <div class="image">
+          <img src="{{brand.logo}}" alt="{{brand.name}} logo">
+        </div>
+      {{ endif }}
+      <div class="product">{{product.name}}</div>
+      <div class="version">v{{product.version}}</div>
     </div>
 
     <div class="content">
@@ -92,8 +98,12 @@
     </div>
 
     <div class="footer">
-      <div class="product">{{product.name}}</div>
-      <div class="version">v{{product.version}}</div>
+      {{ if brand.logo }}
+        <div class="image">
+          <img src="{{brand.logo}}" alt="{{brand.name}} logo">
+        </div>
+      {{ endif }}
+      <div class="brand">{{brand.name}}</div>
     </div>
   </div>
 </body>