Restore Cache-Control, ship both filenames, publish identifiable builds

Three related gaps in how dist/ is published, all handled by a postbuild
step so the layout is produced in one place.

Cache-Control: the gsutil deploys used to set it explicitly (no-store on
dev, max-age on prod). The move to rsync in 950b9e0 dropped that, and
nothing noticed because .htaccess only ever existed on the server. It is
now in the repo per environment and shipped with the bundle, into the
ar-button/ directory. Apache merges it with the docroot .htaccess that
sets CORS; the two touch different headers so they do not collide.
Without it responses carry no Cache-Control at all and browsers fall back
to heuristic caching, holding a stale bundle for weeks.

Filenames: build:prod used to `mv` the bundle to ar-button.min.js, so each
environment served one name and only one. That name has shipped in customer
embeds since the Vue CLI days and can never disappear, so it is now a copy
rather than a rename. Both environments publish both names, which lets both
move to ar-button.js without breaking anything already embedded.

Identifiability: the stable names cannot be hashed, since customers control
those references. Instead each build also publishes an immutable
content-addressed copy (cacheable for a year, and available to pin against)
plus a version.json naming the version, hash and commit that is live.
Answering "which build is deployed?" previously meant comparing CDN
Last-Modified headers by hand.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pixlhero

deploy/htaccess.dev

@@ -0,0 +1,20 @@
+# Deployed into the ar-button/ directory by `yarn deploy:dev`.
+#
+# Apache merges this with the docroot .htaccess, which sets the CORS headers.
+# Only Cache-Control is set here, so the two never collide.
+#
+# The gsutil deploys used to set "no-store, no-cache" on dev. That was lost in
+# the move to rsync (Dec 2025), leaving responses with no Cache-Control at all,
+# so browsers fell back to heuristic caching and held the bundle for weeks.
+
+<IfModule mod_headers.c>
+    # Dev must never be cached: a redeploy has to be visible on reload.
+    <FilesMatch "^(ar-button(\.min)?\.js|version\.json)$">
+        Header set Cache-Control "no-store, no-cache, must-revalidate"
+    </FilesMatch>
+
+    # Content-addressed builds never change, so they can be cached forever.
+    <FilesMatch "^ar-button-.+\.js$">
+        Header set Cache-Control "public, max-age=31536000, immutable"
+    </FilesMatch>
+</IfModule>

deploy/htaccess.prod

@@ -0,0 +1,19 @@
+# Deployed into the ar-button/ directory by `yarn deploy:prod`.
+#
+# Apache merges this with the docroot .htaccess, which sets the CORS headers.
+# Only Cache-Control is set here, so the two never collide.
+
+<IfModule mod_headers.c>
+    # Customers embed these filenames directly, so they can never be renamed or
+    # hashed. They must stay revalidating instead, or a redeploy takes weeks to
+    # reach browsers. Revalidation is cheap: ETag turns it into a 304.
+    <FilesMatch "^(ar-button(\.min)?\.js|version\.json)$">
+        Header set Cache-Control "public, max-age=300, must-revalidate"
+    </FilesMatch>
+
+    # Content-addressed builds never change, so they can be cached forever.
+    # Pin one of these if you need a build that cannot shift under you.
+    <FilesMatch "^ar-button-.+\.js$">
+        Header set Cache-Control "public, max-age=31536000, immutable"
+    </FilesMatch>
+</IfModule>

package.json

@@ -15,9 +15,9 @@
   "scripts": {
     "serve": "parcel ./demo.html --port 8080 --target default",
     "watch": "parcel watch --target default",
-    "build:dev": "rm -rf dist/* && NODE_ENV=development parcel build --target default",
+    "build:dev": "rm -rf dist && NODE_ENV=development parcel build --target default && node scripts/postbuild.mjs dev",
     "test:smoke": "node test/smoke.mjs",
-    "build:prod": "rm -rf dist/* && NODE_ENV=production parcel build --target default && mv dist/ar-button.js dist/ar-button.min.js",
+    "build:prod": "rm -rf dist && NODE_ENV=production parcel build --target default && node scripts/postbuild.mjs prod",
     "deploy:dev": "yarn build:dev && rsync -avz dist/ loxanimo@bitforge.ch:www/dist.dev.yago.cloud/ar-button/",
     "deploy:prod": "yarn build:prod && rsync -avz --exclude='*.map' dist/ loxanimo@bitforge.ch:www/dist.yago.cloud/ar-button/"
   },

scripts/postbuild.mjs

@@ -0,0 +1,76 @@
+/**
+ * Post-build step: lay out dist/ so a deploy is both stable and identifiable.
+ *
+ * Produces, from the single bundle Parcel emits:
+ *
+ *   ar-button.js                     stable entry, what new embeds should use
+ *   ar-button.min.js                 identical copy under the legacy filename
+ *   ar-button-<version>-<hash>.js    immutable, content-addressed build
+ *   version.json                     what is actually deployed here
+ *   .htaccess                        per-environment Cache-Control
+ *
+ * Why a copy and not the old `mv`: production URLs have shipped as
+ * ar-button.min.js since the Vue CLI days and are embedded on customer sites,
+ * so that name can never disappear. Emitting both lets both environments move
+ * to ar-button.js without breaking anything already out there.
+ *
+ * The hashed copy exists because the stable names cannot be hashed - customers
+ * control those references. It gives something immutable to pin, and makes
+ * "which build is live?" answerable with one request instead of an
+ * investigation into CDN headers.
+ */
+import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+
+const env = process.argv[2];
+if (env !== 'dev' && env !== 'prod') {
+    console.error('usage: node scripts/postbuild.mjs <dev|prod>');
+    process.exit(1);
+}
+
+const DIST = 'dist';
+const ENTRY = join(DIST, 'ar-button.js');
+
+if (!existsSync(ENTRY)) {
+    console.error(`✗ ${ENTRY} not found - did the parcel build run?`);
+    process.exit(1);
+}
+
+const bundle = readFileSync(ENTRY);
+const hash = createHash('sha256').update(bundle).digest('hex').slice(0, 8);
+const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+const immutable = `ar-button-${pkg.version}-${hash}.js`;
+
+// Legacy filename, kept forever for embeds already in the wild.
+copyFileSync(ENTRY, join(DIST, 'ar-button.min.js'));
+copyFileSync(ENTRY, join(DIST, immutable));
+
+const htaccess = join('deploy', `htaccess.${env}`);
+if (!existsSync(htaccess)) {
+    console.error(`✗ ${htaccess} not found`);
+    process.exit(1);
+}
+copyFileSync(htaccess, join(DIST, '.htaccess'));
+
+let commit = 'unknown';
+try {
+    commit = execSync('git rev-parse --short HEAD', { stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString()
+        .trim();
+} catch {
+    // building outside a git checkout is fine, just less traceable
+}
+
+const info = {
+    version: pkg.version,
+    hash,
+    commit,
+    env,
+    built: new Date().toISOString(),
+    files: { latest: 'ar-button.js', legacy: 'ar-button.min.js', immutable },
+};
+writeFileSync(join(DIST, 'version.json'), JSON.stringify(info, null, 2) + '\n');
+
+console.log(`postbuild (${env}): ${immutable}  commit ${commit}`);