@techninja/clearstack 0.4.15 → 0.4.17

package/docs/OG_METADATA_SPEC.md

@@ -24,14 +24,14 @@ Both are driven by the same `clearstack.routes.json` config and data sources.
   "/trait/:slug": {
     "title": "{slug.name}",
     "description": "{slug.description}",
-    "image": "{slug.cover_image.url}",
-    "data": "src/data/trait_manifest.json:traits",
+    "image": "{slug.image}",
+    "data": "data/traits-og.json",
     "ogTemplate": "trait"
   },
   "/shop/product/:sku": {
     "title": "{sku.name} | {store.name}",
     "description": "{sku.description}",
-    "image": "{store.url}{sku.images.0}",
+    "image": "{sku.images.0}",
     "data": "src/data/products.json",
     "ogTemplate": "product"
   }
@@ -111,6 +111,53 @@ clearstack build all --url=https://mysite.com --site=MySite --out=dist
 | `--logo` | Logo path or URL                   |
 | `--slug` | Single item slug (fast iteration)  |
 
+## Cloudflare Pages Routing
+
+Cloudflare Pages evaluates `_redirects` **before** checking the filesystem.
+The standard SPA catch-all `/* /index.html 200` will intercept all pre-rendered
+pages before they can be served. Since CF Pages serves `.html` files natively
+for extensionless URLs when a matching file exists on the filesystem, no extra
+rewrite rules are needed — just ensure the catch-all is the **only** rule and
+that it comes after any explicit redirects:
+
+```
+/old-path /new-path 301
+/* /index.html 200
+```
+
+The pre-rendered files (`shop/product/SM-TEE.html`) will be served directly by
+CF Pages' static file layer before the `_redirects` rules are evaluated.
+
+## Canonical Tags
+
+Inject `<link rel="canonical">` into every pre-rendered page so Google
+deduplicates the static HTML shell from the SPA view at the same URL. Do this
+as a post-processing step in `build.js` after `buildOG` runs:
+
+```js
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function injectCanonicals(distDir, baseUrl) {
+  const prefixes = ['shop/product', 'trait', 'gene'];
+  for (const prefix of prefixes) {
+    const dir = resolve(distDir, prefix);
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.html')) continue;
+      const slug = file.slice(0, -5);
+      const url = `${baseUrl}/${prefix}/${slug}`;
+      const filePath = resolve(dir, file);
+      let html = readFileSync(filePath, 'utf-8');
+      if (!html.includes('rel="canonical"')) {
+        html = html.replace('</head>', `  <link rel="canonical" href="${url}" />\n  </head>`);
+        writeFileSync(filePath, html);
+      }
+    }
+  }
+}
+```
+
 ## Requirements
 
 - Zero config for basic cases (route title + description → OG tags)

package/lib/watch-runner.js

@@ -38,6 +38,7 @@ export function runKeys(specRows, keys, ctx) {
       render(rows, lastCheck.value, watchDirs, currentViolations.value);
     };
     const raw = await row.run({ quiet: true, onProgress });
+    if (raw?.pass === null) { setImmediate(next); return; } // cancelled — leave row as-is
     const elapsed = ((Date.now() - t0) / 1000).toFixed(1) + 's';
     row.result = typeof raw === 'boolean' ? { pass: raw } : raw;
     row.pass = row.result.pass;

package/lib/watch.js

@@ -52,7 +52,16 @@ export async function startWatch(projectDir) {
     const extra = keyBound.map(({ keyBinding, name }) => `  ${keyBinding} ${name.replace(/\s*\(.*\)/, '')}`).join('  ');
     outer.setLabel(` {blue-fg}\u2665{/blue-fg} Clearstack Spec Watch  q quit  \u2191\u2193 scroll  c copy  f fix${extra} `);
     for (const row of keyBound) {
-      screen.key([row.keyBinding], () => run(new Set([row.key])));
+      screen.key([row.keyBinding], () => {
+        if (row.pass === null && row.cancel) {
+          row.cancel();
+          row.pass = false;
+          row.detail = 'cancelled';
+          render(rows, lastCheck.value, watchDirs, currentViolations.value);
+        } else {
+          run(new Set([row.key]));
+        }
+      });
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

package/templates/shared/docs/clearstack/OG_METADATA_SPEC.md

@@ -24,14 +24,14 @@ Both are driven by the same `clearstack.routes.json` config and data sources.
   "/trait/:slug": {
     "title": "{slug.name}",
     "description": "{slug.description}",
-    "image": "{slug.cover_image.url}",
-    "data": "src/data/trait_manifest.json:traits",
+    "image": "{slug.image}",
+    "data": "data/traits-og.json",
     "ogTemplate": "trait"
   },
   "/shop/product/:sku": {
     "title": "{sku.name} | {store.name}",
     "description": "{sku.description}",
-    "image": "{store.url}{sku.images.0}",
+    "image": "{sku.images.0}",
     "data": "src/data/products.json",
     "ogTemplate": "product"
   }
@@ -111,6 +111,53 @@ clearstack build all --url=https://mysite.com --site=MySite --out=dist
 | `--logo` | Logo path or URL                   |
 | `--slug` | Single item slug (fast iteration)  |
 
+## Cloudflare Pages Routing
+
+Cloudflare Pages evaluates `_redirects` **before** checking the filesystem.
+The standard SPA catch-all `/* /index.html 200` will intercept all pre-rendered
+pages before they can be served. Since CF Pages serves `.html` files natively
+for extensionless URLs when a matching file exists on the filesystem, no extra
+rewrite rules are needed — just ensure the catch-all is the **only** rule and
+that it comes after any explicit redirects:
+
+```
+/old-path /new-path 301
+/* /index.html 200
+```
+
+The pre-rendered files (`shop/product/SM-TEE.html`) will be served directly by
+CF Pages' static file layer before the `_redirects` rules are evaluated.
+
+## Canonical Tags
+
+Inject `<link rel="canonical">` into every pre-rendered page so Google
+deduplicates the static HTML shell from the SPA view at the same URL. Do this
+as a post-processing step in `build.js` after `buildOG` runs:
+
+```js
+import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function injectCanonicals(distDir, baseUrl) {
+  const prefixes = ['shop/product', 'trait', 'gene'];
+  for (const prefix of prefixes) {
+    const dir = resolve(distDir, prefix);
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.html')) continue;
+      const slug = file.slice(0, -5);
+      const url = `${baseUrl}/${prefix}/${slug}`;
+      const filePath = resolve(dir, file);
+      let html = readFileSync(filePath, 'utf-8');
+      if (!html.includes('rel="canonical"')) {
+        html = html.replace('</head>', `  <link rel="canonical" href="${url}" />\n  </head>`);
+        writeFileSync(filePath, html);
+      }
+    }
+  }
+}
+```
+
 ## Requirements
 
 - Zero config for basic cases (route title + description → OG tags)