@jtakeit/kit 0.9.0 → 0.11.0

package/README.md

@@ -131,10 +131,36 @@ import { writeMeta } from '@jtakeit/kit/meta';
 await writeMeta('dist', {
   collections, blocks, locales,      // the declaration: the specimens are derived from it
   immutable: ['/_next/static/'],     // where this generator keeps its hashed files; absent, the edge assumes Astro's
+  cache: [{ prefix: '/clips/', maxAge: 86400 }], // files that keep their names, kept a day; see below
   redirects: [{ from: '/old', to: '/new', status: 301 }],
 });
 ```
 
+### A file a script picks by name
+
+A film or a photograph a script addresses has no attribute pointing at it, so
+the generator does not hash it and it lives in `public/`, which the edge
+serves for a minute. `keepByName` gives it a name that carries its bytes,
+after the build and before `writeMeta`:
+
+```js
+import { keepByName } from '@jtakeit/kit/kept';
+
+const { kept, unreferenced } = keepByName('dist', { dirs: ['clips', 'scenes'] });
+// /clips/einsatz.mp4 → /_astro/kept/clips/einsatz.3f9a1c2b.mp4, kept for a year
+```
+
+Every address the build wrote whole — in a script, `src`, `data-src`,
+`url(…)` — is pointed at the copy; the originals stay, and `unreferenced`
+names the ones a script assembles and that therefore still go by name.
+
+Or keep the names and declare how long: `cache: [{ prefix: '/clips/', maxAge:
+86400 }]` beside `immutable`. The platform then holds every such name to its
+contents for that long once the site has an address — other bytes under it are
+refused, `JTK_E_CACHED_FILE_CHANGED`, and lowering `maxAge` frees nothing
+sooner. A day for names that may be reused; a year only for names that carry
+their version.
+
 The **specimen pages** are the one thing in that list a site has to build as
 well as declare: one page per block a post may hold, at
 `<collection prefix>/_fl-<type>[-<view>]/` and per extra language — the panel

package/lib/catalogue.mjs

@@ -1533,6 +1533,11 @@ for (const page of pages) {
           // for either way rather than reported as text nobody can touch.
           for (const key of ['src', 'alt', 'poster']) onThePage.delete(`${itemPath}.${key}`);
         });
+        // The wall itself may be annotated too — the belt the logos run on,
+        // the frame a gallery sits in — and a tap on it opens the same
+        // gallery with nothing selected. Allowed, not asked for: a wall whose
+        // every picture is tappable is complete without it (25 October 2026).
+        onThePage.delete(path);
         continue;
       }
 

package/lib/kept.mjs

@@ -0,0 +1,121 @@
+/**
+ * Files a script addresses by name, given a name that carries their contents.
+ *
+ * ── why ─────────────────────────────────────────────────────────────────────
+ *
+ * The generator hashes what the HTML refers to — a stylesheet, an `<img>` —
+ * and puts it under `/_astro/`, which the edge keeps in browsers for a year.
+ * A film or a photograph a script picks by name is not referred to by any
+ * attribute, so it has to live in `public/`, and `public/` keeps its names:
+ * the edge serves it for a minute, and every returning visitor downloads the
+ * hero film again (railtec, 19 October 2026: two megabytes).
+ *
+ * Declaring a lifetime for the directory (`cache` in `_meta.json`) is one
+ * answer, and it costs the names: the platform then holds each one to its
+ * contents for as long as was declared. This is the other answer, and the one
+ * that costs nothing later — after the build, each file under the named
+ * directories is copied under `/_astro/kept/` with a hash of its bytes in its
+ * name, and every place the build wrote its address as a literal is pointed
+ * at the copy. A new photograph is a new name by construction.
+ *
+ * ── what it does not do ─────────────────────────────────────────────────────
+ *
+ * It rewrites an address only where the build wrote it whole — `"/clips/
+ * einsatz.mp4"` in a script, `src`, `data-src`, `url(…)`. An address a script
+ * assembles (`'/scenes/scene-' + i + '.webp'`) cannot be found, so the
+ * original stays where it was and keeps working, at its minute; the result
+ * names every file nothing pointed at, so the site can write those addresses
+ * out in full. The originals are never removed.
+ */
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, sep } from 'node:path';
+
+/** Where the copies go: under Astro's hashed directory, which the edge keeps for a year. */
+export const KEPT_DIR = '_astro/kept';
+
+/** The files whose text may name an address. */
+const TEXT = new Set(['.html', '.js', '.mjs', '.css']);
+
+const posix = (path) => path.split(sep).join('/');
+
+function walk(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith('.')) continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+/** `scene-1.webp` and its bytes → `scene-1.3f9a1c2b.webp`. */
+export function keptName(name, bytes) {
+  const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+  const ext = extname(name);
+  return `${name.slice(0, name.length - ext.length)}.${hash}${ext}`;
+}
+
+/**
+ * Copies the files under `dirs` of a build directory to hashed names and
+ * points the build's literal references at them.
+ *
+ * @param {string} dist  the build directory
+ * @param {{ dirs: string[]; base?: string }} options
+ *   `dirs`, as they sit under `public/` — `['clips', 'scenes']`; `base`, the
+ *   site's base path when it is not `/` (Astro's `base`)
+ * @returns {{ kept: { from: string; to: string }[]; rewritten: number; unreferenced: string[] }}
+ *   every copy as addresses, how many references were pointed at one, and the
+ *   addresses no file named whole — still served by name, at the edge's minute
+ */
+export function keepByName(dist, { dirs, base = '/' } = {}) {
+  if (!Array.isArray(dirs) || dirs.length === 0) return { kept: [], rewritten: 0, unreferenced: [] };
+  const root = `/${base.replace(/^\/+|\/+$/g, '')}/`.replace(/^\/\/$/, '/');
+
+  const kept = [];
+  for (const one of dirs) {
+    const dir = one.replace(/^\/+|\/+$/g, '');
+    if (dir === '' || dir.startsWith('_astro') || dir.startsWith('.')) {
+      throw new TypeError(`keepByName: "${one}" is not a directory of public/ (not the root, not _astro, not hidden)`);
+    }
+    const from = join(dist, dir);
+    if (!existsSync(from)) continue;
+    for (const file of walk(from)) {
+      if (extname(file).toLowerCase() === '.html') continue;
+      const inside = posix(relative(from, file));
+      const hashed = posix(join(dirname(inside), keptName(inside.split('/').pop(), readFileSync(file))));
+      const to = join(dist, KEPT_DIR, dir, hashed);
+      mkdirSync(dirname(to), { recursive: true });
+      copyFileSync(file, to);
+      kept.push({ from: `${root}${dir}/${inside}`, to: `${root}${KEPT_DIR}/${dir}/${hashed.replace(/^\.\//, '')}` });
+    }
+  }
+  if (kept.length === 0) return { kept, rewritten: 0, unreferenced: [] };
+
+  // One pattern for every address, longest first, bounded the way an address
+  // is written: after a quote, a bracket, a space, `=` or `,` — or `&quot;`,
+  // which is how a JSON list in a `data-` attribute reaches the HTML — and
+  // before a quote, a bracket, a space, `,`, `?`, `#` or `&`. `/clips/a.mp4`
+  // must not match inside `/clips/a.mp4.old` or `/x/clips/a.mp4`.
+  const to = new Map(kept.map((one) => [one.from, one.to]));
+  const escaped = [...to.keys()].sort((a, b) => b.length - a.length).map((one) => one.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+  const pattern = new RegExp(`(?<=["'\`(\\s=,]|&quot;|&#34;|&#39;)(${escaped.join('|')})(?=["'\`)\\s,?#&])`, 'g');
+
+  const used = new Set();
+  let rewritten = 0;
+  const copies = join(dist, KEPT_DIR) + sep;
+  for (const file of walk(dist)) {
+    if (file.startsWith(copies) || !TEXT.has(extname(file).toLowerCase())) continue;
+    const text = readFileSync(file, 'utf8');
+    let changed = false;
+    const next = text.replace(pattern, (address) => {
+      used.add(address);
+      rewritten += 1;
+      changed = true;
+      return to.get(address);
+    });
+    if (changed) writeFileSync(file, next);
+  }
+
+  return { kept, rewritten, unreferenced: kept.map((one) => one.from).filter((one) => !used.has(one)) };
+}

package/lib/lead/render.mjs

@@ -145,7 +145,7 @@ export function renderLeadForm(props) {
   </div>
 
   ${asks.map((ask) => `<div class="field">
-    <label class="field__label" for="lead-${esc(ask.key)}" data-jtk-fixed>${esc(ask.label)}${ask.required ? ' <span aria-hidden="true">*</span>' : ''}</label>
+    <label class="field__label" for="lead-${esc(ask.key)}"${ask.path ? at(ask.path) : ' data-jtk-fixed'}>${esc(ask.label)}${ask.required ? ' <span aria-hidden="true">*</span>' : ''}</label>
     ${askControl(ask)}
   </div>`).join('\n  ')}
 

package/lib/meta.mjs

@@ -133,15 +133,56 @@ export async function hiddenEntries(root = join(process.cwd(), 'jtk', 'content')
  * @param {string[]} [what.locales]
  * @param {string[]} [what.immutable]          e.g. `['/_astro/']`
  * @param {{ from: string; to: string; status?: number }[]} [what.redirects]
- * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[] }>}
+ * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[]; cache?: { prefix: string; maxAge: number }[] }>}
  */
-export async function buildMeta({ root, collections = [], blocks = [], locales = [], immutable, redirects = [] } = {}) {
+export async function buildMeta({ root, collections = [], blocks = [], locales = [], immutable, cache, redirects = [] } = {}) {
   const drafts = [...(await hiddenEntries(root)), ...specimenAddresses(collections, blocks, locales)].sort();
   const meta = { redirects, drafts };
   if (Array.isArray(immutable) && immutable.length > 0) meta.immutable = immutable;
+  const lifetimes = cacheRules(cache);
+  if (lifetimes.length > 0) meta.cache = lifetimes;
   return meta;
 }
 
+/** A year: the most the edge keeps anything for. */
+const YEAR = 31_536_000;
+
+/**
+ * The lifetimes a build declares for directories of files that keep their own
+ * names — `public/clips/`, a film or a photograph a script addresses — read
+ * the way the edge reads them (jtakeit-core edge/src/meta.ts): each prefix as
+ * `/dir/`, never `/`, a whole number of seconds, at most a year.
+ *
+ * Thrown on rather than dropped, unlike the edge: the edge reads somebody
+ * else's file and must not fall over, the build is ours and should be told.
+ *
+ * Every name under such a directory is then held by the platform to its
+ * contents, once the site has an address, until the last visitor's copy may
+ * have run out: other bytes under it are refused (JTK_E_CACHED_FILE_CHANGED),
+ * and lowering `maxAge` frees nothing sooner. A day for names that may be
+ * reused; a year only for names that carry their version — or put the files
+ * under a hashed name with `keepByName` (`@jtakeit/kit/kept`) and declare
+ * nothing.
+ *
+ * @param {{ prefix: string; maxAge: number }[] | undefined} cache
+ * @returns {{ prefix: string; maxAge: number }[]}
+ */
+export function cacheRules(cache) {
+  if (cache === undefined || cache === null) return [];
+  if (!Array.isArray(cache)) throw new TypeError('cache is a list of { prefix, maxAge }');
+  return cache.map((one, i) => {
+    if (one === null || typeof one !== 'object' || typeof one.prefix !== 'string') {
+      throw new TypeError(`cache[${i}] needs a prefix, like "/clips/"`);
+    }
+    const trimmed = one.prefix.replace(/^\/+|\/+$/g, '');
+    if (trimmed === '') throw new TypeError(`cache[${i}]: a prefix of "/" would cover the whole site, pages included`);
+    if (typeof one.maxAge !== 'number' || !Number.isFinite(one.maxAge) || one.maxAge < 0) {
+      throw new TypeError(`cache[${i}]: maxAge is a number of seconds, like 86400 for a day`);
+    }
+    return { prefix: `/${trimmed}/`, maxAge: Math.min(Math.floor(one.maxAge), YEAR) };
+  });
+}
+
 /**
  * Writes `_meta.json` into a build directory — whatever happens, empty lists
  * and all, because a missing file and an empty one mean different things to
@@ -149,7 +190,7 @@ export async function buildMeta({ root, collections = [], blocks = [], locales =
  *
  * @param {string} dir   the build directory, `dist/`
  * @param {Parameters<typeof buildMeta>[0]} what
- * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[] }>}
+ * @returns {Promise<{ redirects: object[]; drafts: string[]; immutable?: string[]; cache?: { prefix: string; maxAge: number }[] }>}
  */
 export async function writeMeta(dir, what = {}) {
   const meta = await buildMeta(what);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jtakeit/kit",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "The framework-free half of a site on jtakeit: the booking form as an element and as markup, for Astro through @jtakeit/astro and for any other generator directly",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,10 @@
       "types": "./types/meta.d.ts",
       "default": "./lib/meta.mjs"
     },
+    "./kept": {
+      "types": "./types/kept.d.ts",
+      "default": "./lib/kept.mjs"
+    },
     "./kits": {
       "types": "./types/kits.d.ts",
       "default": "./lib/kits.mjs"

package/types/kept.d.ts

@@ -0,0 +1,21 @@
+/** Where the copies go: under Astro's hashed directory, which the edge keeps for a year. */
+export const KEPT_DIR: string;
+
+/** `scene-1.webp` and its bytes → `scene-1.3f9a1c2b.webp`. */
+export function keptName(name: string, bytes: Uint8Array): string;
+
+export interface Kept {
+  /** Every copy, as addresses: `/clips/a.mp4` → `/_astro/kept/clips/a.3f9a1c2b.mp4`. */
+  kept: { from: string; to: string }[];
+  /** How many references in the build were pointed at a copy. */
+  rewritten: number;
+  /** Addresses no file of the build named whole — still served by name, at the edge's minute. */
+  unreferenced: string[];
+}
+
+/**
+ * Copies the files under `dirs` of a build directory to names that carry a
+ * hash of their bytes, under `/_astro/kept/`, and points the build's literal
+ * references at them. The originals stay.
+ */
+export function keepByName(dist: string, options: { dirs: string[]; base?: string }): Kept;

package/types/lead.d.ts

@@ -1,6 +1,13 @@
 export interface Ask {
   key: string;
   label: string;
+  /**
+   * Where the words over the field come from, when the site keeps them in
+   * its content (a `<key>_label` field of the collecting block, say) and
+   * the owner may tap them. Without it the label is drawn fixed, as the
+   * catalogue declared it.
+   */
+  path?: string;
   kind: string;
   required?: boolean;
   max?: number;

package/types/meta.d.ts

@@ -2,6 +2,15 @@ export interface Meta {
   redirects: { from: string; to: string; status?: number }[];
   drafts: string[];
   immutable?: string[];
+  cache?: CacheRule[];
+}
+
+/** How long browsers keep the files under a directory whose names carry no hash. */
+export interface CacheRule {
+  /** The directory, e.g. `/clips/`. Never `/`. */
+  prefix: string;
+  /** Seconds, at most a year. Pages under the directory are never covered. */
+  maxAge: number;
 }
 
 export interface MetaInput {
@@ -12,6 +21,12 @@ export interface MetaInput {
   locales?: string[];
   /** The directories whose file names carry a content hash, e.g. `['/_astro/']`. */
   immutable?: string[];
+  /**
+   * Lifetimes for directories of files that keep their names. Each name is
+   * then held to its contents by the platform for that long: new contents
+   * take a new name (JTK_E_CACHED_FILE_CHANGED).
+   */
+  cache?: CacheRule[];
   redirects?: { from: string; to: string; status?: number }[];
 }
 
@@ -22,5 +37,6 @@ export function specimenAddresses(
   locales?: string[],
 ): string[];
 export function hiddenEntries(root?: string, now?: number): Promise<string[]>;
+export function cacheRules(cache?: CacheRule[]): CacheRule[];
 export function buildMeta(what?: MetaInput): Promise<Meta>;
 export function writeMeta(dir: string, what?: MetaInput): Promise<Meta>;