kempo-media 0.2.3

package/public/sdk.js

@@ -0,0 +1,62 @@
+const BASE = '/kempo-media/api';
+
+const req = async (method, path, data) => {
+  const opts = { method, headers: {} };
+  if(data && method !== 'GET'){
+    opts.headers['Content-Type'] = 'application/json';
+    opts.body = JSON.stringify(data);
+  }
+  try {
+    const res = await fetch(path, opts);
+    const json = await res.json().catch(() => ({}));
+    if(!res.ok) return [{ code: res.status, msg: json.error || 'An error occurred' }, null];
+    return [null, json];
+  } catch {
+    return [{ code: 503, msg: 'Network error' }, null];
+  }
+};
+
+const buildQuery = params => {
+  const pairs = Object.entries(params)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
+  return pairs.length ? `?${pairs.join('&')}` : '';
+};
+
+export const getMediaAssets = (params = {}) => req('GET', `${BASE}/media${buildQuery(params)}`);
+export const getMediaAsset = id => req('GET', `${BASE}/media${buildQuery({ id })}`);
+export const updateMediaAsset = data => req('PATCH', `${BASE}/media`, data);
+export const deleteMediaAsset = id => req('DELETE', `${BASE}/media`, { id });
+
+/*
+  Uploads go through XMLHttpRequest rather than fetch purely for `upload.onprogress` — fetch still
+  has no way to report how far a request body has been sent, and a progress bar is the difference
+  between a usable upload of a large video and one that looks frozen.
+*/
+export const uploadMedia = (file, { alt = '' } = {}, onProgress) => new Promise(resolve => {
+  const form = new FormData();
+  form.append('file', file);
+  if(alt) form.append('alt', alt);
+
+  const xhr = new XMLHttpRequest();
+  xhr.open('POST', `${BASE}/media`);
+
+  xhr.upload.addEventListener('progress', e => {
+    if(e.lengthComputable) onProgress?.(e.loaded / e.total);
+  });
+
+  xhr.addEventListener('load', () => {
+    let json = {};
+    try { json = JSON.parse(xhr.responseText); } catch { /* a non-JSON error page */ }
+    if(xhr.status >= 200 && xhr.status < 300){
+      onProgress?.(1);
+      return resolve([null, json]);
+    }
+    resolve([{ code: xhr.status, msg: json.error || `Upload failed (${xhr.status})` }, null]);
+  });
+
+  xhr.addEventListener('error', () => resolve([{ code: 503, msg: 'Network error' }, null]));
+  xhr.addEventListener('abort', () => resolve([{ code: 499, msg: 'Upload cancelled' }, null]));
+
+  xhr.send(form);
+});

package/sdk.js

@@ -0,0 +1,15 @@
+/*
+  Server-side entry point, for hooks and other extensions that want to reach media assets in
+  process rather than over HTTP. The browser-facing client is public/sdk.js, served at
+  /kempo-media/sdk.js — same names, different transport.
+*/
+
+export { default as createMediaAsset } from './server/utils/media/createMediaAsset.js';
+export { default as getMediaAsset } from './server/utils/media/getMediaAsset.js';
+export { default as getMediaAssets } from './server/utils/media/getMediaAssets.js';
+export { default as updateMediaAsset } from './server/utils/media/updateMediaAsset.js';
+export { default as deleteMediaAsset } from './server/utils/media/deleteMediaAsset.js';
+
+export { default as storeUpload } from './server/utils/uploads/storeUpload.js';
+export { default as parseMultipart, extractBoundary } from './server/utils/uploads/parseMultipart.js';
+export { ALLOWED_TYPES, KINDS, typeForFilename } from './server/utils/uploads/fileTypes.js';

package/server/db/schema.js

@@ -0,0 +1,18 @@
+import { pgTable, text, integer, timestamp } from 'drizzle-orm/pg-core';
+
+export const kempoMediaAsset = pgTable('kempoMediaAsset', {
+  id: text('id').primaryKey(), // crypto.randomBytes(8).toString('hex')
+  filename: text('filename').notNull(), // server-generated name on disk — never derived from user input
+  originalName: text('originalName').notNull(),
+  mimeType: text('mimeType').notNull(),
+  kind: text('kind').notNull(), // 'image' | 'video' | 'audio' | 'model3d' | 'archive'
+  sizeBytes: integer('sizeBytes').notNull(),
+  path: text('path').notNull(), // relative to the site's public/, e.g. 'media/uploads/<id>.png'
+  thumbnailPath: text('thumbnailPath'), // images only; null for every other kind
+  altText: text('altText').notNull().default(''),
+  width: integer('width'),
+  height: integer('height'),
+  uploadedBy: text('uploadedBy').notNull(),
+  createdAt: timestamp('createdAt').notNull(),
+  updatedAt: timestamp('updatedAt').notNull(),
+});

package/server/utils/media/createMediaAsset.js

@@ -0,0 +1,19 @@
+import db from 'kempo/server/db/index.js';
+import { kempoMediaAsset } from '../../db/schema.js';
+
+/*
+  Records an asset that storeUpload has already written to disk. Kept separate from the write so a
+  failure to record does not leave the caller unsure whether the bytes landed.
+*/
+export default async (asset) => {
+  try {
+    const now = new Date();
+    const [row] = await db
+      .insert(kempoMediaAsset)
+      .values({ ...asset, createdAt: now, updatedAt: now })
+      .returning();
+    return [null, row];
+  } catch(e) {
+    return [{ code: 500, msg: e.message }, null];
+  }
+};

package/server/utils/media/deleteMediaAsset.js

@@ -0,0 +1,37 @@
+import { join } from 'path';
+import { unlink } from 'fs/promises';
+import db from 'kempo/server/db/index.js';
+import { kempoMediaAsset } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
+import getMediaAsset from './getMediaAsset.js';
+
+/*
+  Removes the row and the files behind it.
+
+  A file already missing from disk is not treated as a failure: the row is the thing that makes the
+  asset visible, so refusing to delete it because its file was removed by hand would leave a
+  permanently undeletable entry pointing at nothing.
+*/
+export default async (id, { rootDir }) => {
+  const [findError, asset] = await getMediaAsset(id);
+  if(findError) return [findError, null];
+
+  for(const relativePath of [asset.path, asset.thumbnailPath].filter(Boolean)){
+    try {
+      await unlink(join(rootDir, relativePath));
+    } catch(e) {
+      if(e.code !== 'ENOENT'){
+        return [{ code: 500, msg: `Could not delete ${relativePath}: ${e.message}` }, null];
+      }
+      console.warn(`[kempo-media] ${relativePath} was already gone from disk`);
+    }
+  }
+
+  try {
+    await db.delete(kempoMediaAsset).where(eq(kempoMediaAsset.id, id));
+  } catch(e) {
+    return [{ code: 500, msg: e.message }, null];
+  }
+
+  return [null, { id }];
+};

package/server/utils/media/getMediaAsset.js

@@ -0,0 +1,14 @@
+import db from 'kempo/server/db/index.js';
+import { kempoMediaAsset } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
+
+export default async (id) => {
+  if(!id) return [{ code: 400, msg: 'An asset id is required' }, null];
+  try {
+    const [row] = await db.select().from(kempoMediaAsset).where(eq(kempoMediaAsset.id, id));
+    if(!row) return [{ code: 404, msg: 'Asset not found' }, null];
+    return [null, row];
+  } catch(e) {
+    return [{ code: 500, msg: e.message }, null];
+  }
+};

package/server/utils/media/getMediaAssets.js

@@ -0,0 +1,39 @@
+import db from 'kempo/server/db/index.js';
+import { kempoMediaAsset } from '../../db/schema.js';
+import { eq, and, desc, count, ilike, inArray } from 'drizzle-orm';
+import { KINDS } from '../uploads/fileTypes.js';
+
+/*
+  Newest first, which is what a library browser wants — the asset you just uploaded is the one you
+  are about to use.
+*/
+export default async ({ limit = 24, offset = 0, kind, search } = {}) => {
+  try {
+    const conditions = [];
+
+    if(kind){
+      // Accepts a single kind or a comma-separated list; unknown values are ignored rather than
+      // silently matching nothing, so a typo in a query string does not look like an empty library
+      const kinds = String(kind).split(',').map(k => k.trim()).filter(k => KINDS.includes(k));
+      if(kinds.length) conditions.push(kinds.length === 1 ? eq(kempoMediaAsset.kind, kinds[0]) : inArray(kempoMediaAsset.kind, kinds));
+    }
+
+    if(search) conditions.push(ilike(kempoMediaAsset.originalName, `%${search}%`));
+
+    const where = conditions.length ? and(...conditions) : undefined;
+
+    const [{ total }] = await db.select({ total: count() }).from(kempoMediaAsset).where(where);
+
+    const assets = await db
+      .select()
+      .from(kempoMediaAsset)
+      .where(where)
+      .orderBy(desc(kempoMediaAsset.createdAt))
+      .limit(limit)
+      .offset(offset);
+
+    return [null, { assets, total, limit, offset }];
+  } catch(e) {
+    return [{ code: 500, msg: e.message }, null];
+  }
+};

package/server/utils/media/updateMediaAsset.js

@@ -0,0 +1,32 @@
+import db from 'kempo/server/db/index.js';
+import { kempoMediaAsset } from '../../db/schema.js';
+import { eq } from 'drizzle-orm';
+
+/*
+  Only the display fields are editable. Everything else — the stored filename, path, kind, size —
+  describes bytes already on disk, so letting it be edited would just make the row lie about them.
+*/
+export default async (id, { altText, originalName } = {}) => {
+  if(!id) return [{ code: 400, msg: 'An asset id is required' }, null];
+
+  const updates = {};
+  if(altText !== undefined) updates.altText = String(altText);
+  if(originalName !== undefined){
+    const trimmed = String(originalName).trim();
+    if(!trimmed) return [{ code: 400, msg: 'A name cannot be empty' }, null];
+    updates.originalName = trimmed;
+  }
+  if(!Object.keys(updates).length) return [{ code: 400, msg: 'Nothing to update' }, null];
+
+  try {
+    const [row] = await db
+      .update(kempoMediaAsset)
+      .set({ ...updates, updatedAt: new Date() })
+      .where(eq(kempoMediaAsset.id, id))
+      .returning();
+    if(!row) return [{ code: 404, msg: 'Asset not found' }, null];
+    return [null, row];
+  } catch(e) {
+    return [{ code: 500, msg: e.message }, null];
+  }
+};

package/server/utils/uploads/fileTypes.js

@@ -0,0 +1,50 @@
+/*
+  What this extension accepts, and how each kind is presented in the library.
+
+  Deliberately excluded: SVG. kempo-server serves it as inline, unsanitised markup on the site's own
+  origin, so an uploaded SVG carrying a <script> is stored XSS against the very admin who uploaded
+  it. Raster images cover what the editor actually needs; adding SVG means adding a sanitiser first.
+
+  These extensions are all registered in kempo-server's default allowedMimes as of 3.2.0, so an
+  uploaded file is served with a correct Content-Type — and, being binary, with range support, so
+  video and audio seek properly.
+*/
+export const ALLOWED_TYPES = {
+  png: { kind: 'image', mime: 'image/png' },
+  jpg: { kind: 'image', mime: 'image/jpeg' },
+  jpeg: { kind: 'image', mime: 'image/jpeg' },
+  gif: { kind: 'image', mime: 'image/gif' },
+  webp: { kind: 'image', mime: 'image/webp' },
+  avif: { kind: 'image', mime: 'image/avif' },
+
+  mp4: { kind: 'video', mime: 'video/mp4' },
+  m4v: { kind: 'video', mime: 'video/mp4' },
+  webm: { kind: 'video', mime: 'video/webm' },
+  ogv: { kind: 'video', mime: 'video/ogg' },
+
+  mp3: { kind: 'audio', mime: 'audio/mpeg' },
+  ogg: { kind: 'audio', mime: 'audio/ogg' },
+  wav: { kind: 'audio', mime: 'audio/wav' },
+
+  glb: { kind: 'model3d', mime: 'model/gltf-binary' },
+  gltf: { kind: 'model3d', mime: 'model/gltf+json' },
+  obj: { kind: 'model3d', mime: 'model/obj' },
+  fbx: { kind: 'model3d', mime: 'application/octet-stream' },
+
+  zip: { kind: 'archive', mime: 'application/zip' },
+};
+
+export const KINDS = ['image', 'video', 'audio', 'model3d', 'archive'];
+
+/*
+  Takes only the final extension of the original name, lowercased. The name itself is never used to
+  build a path — see storeUpload — so this is a type decision, not a filesystem one.
+*/
+export const typeForFilename = filename => {
+  if(typeof filename !== 'string') return null;
+  const dot = filename.lastIndexOf('.');
+  if(dot === -1 || dot === filename.length - 1) return null;
+  const ext = filename.slice(dot + 1).toLowerCase();
+  const type = ALLOWED_TYPES[ext];
+  return type ? { ext, ...type } : null;
+};

package/server/utils/uploads/generateThumbnail.js

@@ -0,0 +1,63 @@
+import { join } from 'path';
+import { writeFile, mkdir } from 'fs/promises';
+import { THUMBNAIL_DIR } from './storeUpload.js';
+
+/*
+  sharp is a native module, so it is the one dependency here that can fail to install on an unusual
+  host (musl without the right build flags, an unsupported architecture). Importing it lazily means
+  that failure surfaces as "this image has no thumbnail" rather than as a route that will not load
+  at all — the upload itself never depends on it.
+*/
+let sharpModule;
+let sharpUnavailable = false;
+
+const loadSharp = async () => {
+  if(sharpUnavailable) return null;
+  if(sharpModule) return sharpModule;
+  try {
+    sharpModule = (await import('sharp')).default;
+    return sharpModule;
+  } catch(e) {
+    sharpUnavailable = true;
+    console.warn(`[kempo-media] sharp is unavailable, so no thumbnails will be generated: ${e.message}`);
+    return null;
+  }
+};
+
+/*
+  Produces a WebP thumbnail for a raster image and reports the source's dimensions.
+
+  `fit: 'inside'` scales the longest edge down to maxDimension and leaves the aspect ratio alone;
+  `withoutEnlargement` keeps an image that is already smaller than the box at its original size
+  rather than upscaling it into a blurrier, larger file.
+
+  Returns the usual [error, data] tuple. Callers treat an error as "no preview", not as a failed
+  upload — see storeUpload.
+*/
+export default async ({ rootDir, data, id, maxDimension = 480 }) => {
+  const sharp = await loadSharp();
+  if(!sharp) return [{ code: 501, msg: 'sharp is not available' }, null];
+
+  try {
+    const image = sharp(data, { failOn: 'none' });
+    const metadata = await image.metadata();
+
+    const thumbnail = await image
+      .resize({ width: maxDimension, height: maxDimension, fit: 'inside', withoutEnlargement: true })
+      .webp()
+      .toBuffer();
+
+    const relativePath = join(THUMBNAIL_DIR, `${id}.webp`).replace(/\\/g, '/');
+    await mkdir(join(rootDir, THUMBNAIL_DIR), { recursive: true });
+    await writeFile(join(rootDir, relativePath), thumbnail);
+
+    return [null, {
+      thumbnailPath: relativePath,
+      width: metadata.width ?? null,
+      height: metadata.height ?? null,
+    }];
+  } catch(e) {
+    // Anything that is not really a decodable image lands here, including a mislabelled extension
+    return [{ code: 422, msg: e.message }, null];
+  }
+};

package/server/utils/uploads/parseMultipart.js

@@ -0,0 +1,99 @@
+/*
+  A minimal multipart/form-data parser, working entirely on Buffers.
+
+  Nothing in kempo or kempo-server parses multipart, and the usual dependency for it (busboy and
+  friends) is built around streaming a body that is still arriving. kempo-server buffers the whole
+  body before a route ever runs, so there is no stream left to consume by then and none of that
+  machinery earns its keep. This handles the shape an upload form actually sends — file parts plus
+  a few text fields — and nothing else.
+
+  Every offset is found with Buffer.indexOf and every slice stays a Buffer, so file content is
+  never decoded. Decoding it as UTF-8 is precisely the corruption kempo-server 3.2.0 fixed, and
+  doing it here would reintroduce it one layer up.
+*/
+
+const CRLF = Buffer.from('\r\n');
+const CRLF_CRLF = Buffer.from('\r\n\r\n');
+const DASH_DASH = Buffer.from('--');
+
+/*
+  `multipart/form-data; boundary=----WebKitFormBoundaryAbC123`, optionally quoted. Returns null when
+  the header is absent or is not multipart, which the caller turns into a 400.
+*/
+export const extractBoundary = contentType => {
+  if(!contentType || !contentType.toLowerCase().includes('multipart/form-data')) return null;
+  const match = contentType.match(/boundary=(?:"([^"]+)"|([^;\s]+))/i);
+  return match ? (match[1] || match[2]) : null;
+};
+
+const parseHeaders = raw => {
+  const headers = {};
+  for(const line of raw.split('\r\n')){
+    const colon = line.indexOf(':');
+    if(colon === -1) continue;
+    headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+  }
+  return headers;
+};
+
+// name="field"; filename="photo.png" — filename is absent on plain text fields
+const quoted = (source, key) => {
+  const match = source.match(new RegExp(`${key}="([^"]*)"`, 'i'));
+  return match ? match[1] : null;
+};
+
+/*
+  Returns [{ name, filename, contentType, data }], where `data` is always a Buffer. Parts without a
+  Content-Disposition name are skipped rather than treated as an error, since a stray part should
+  not fail an otherwise valid upload.
+*/
+export default (buffer, boundary) => {
+  if(!Buffer.isBuffer(buffer) || !boundary) return [];
+
+  const delimiter = Buffer.from(`\r\n--${boundary}`);
+  /*
+    The opening boundary is at the very start of the body with no CRLF before it, unlike every
+    later one. Prefixing a CRLF makes all of them identical so a single search handles the lot.
+  */
+  const body = Buffer.concat([CRLF, buffer]);
+
+  const parts = [];
+  let index = body.indexOf(delimiter);
+
+  while(index !== -1){
+    const afterBoundary = index + delimiter.length;
+
+    // A boundary followed by "--" is the closing delimiter; anything after it is epilogue
+    if(body.subarray(afterBoundary, afterBoundary + 2).equals(DASH_DASH)) break;
+
+    const next = body.indexOf(delimiter, afterBoundary);
+    if(next === -1) break; // truncated body — drop the trailing fragment rather than guess at it
+
+    // The boundary line may carry trailing whitespace before its CRLF
+    const lineEnd = body.indexOf(CRLF, afterBoundary);
+    if(lineEnd === -1 || lineEnd > next) break;
+
+    const headerEnd = body.indexOf(CRLF_CRLF, lineEnd);
+    if(headerEnd === -1 || headerEnd > next){
+      index = next;
+      continue; // no header block — not a part worth keeping
+    }
+
+    const headers = parseHeaders(body.subarray(lineEnd + CRLF.length, headerEnd).toString('utf8'));
+    const disposition = headers['content-disposition'] || '';
+    const name = quoted(disposition, 'name');
+
+    if(name !== null){
+      parts.push({
+        name,
+        filename: quoted(disposition, 'filename'),
+        contentType: headers['content-type'] || null,
+        data: body.subarray(headerEnd + CRLF_CRLF.length, next)
+      });
+    }
+
+    index = next;
+  }
+
+  return parts;
+};

package/server/utils/uploads/storeUpload.js

@@ -0,0 +1,89 @@
+import { join } from 'path';
+import { writeFile, mkdir } from 'fs/promises';
+import crypto from 'crypto';
+import { typeForFilename } from './fileTypes.js';
+import generateThumbnail from './generateThumbnail.js';
+
+export const UPLOAD_DIR = join('media', 'uploads');
+export const THUMBNAIL_DIR = join('media', 'thumbnails');
+
+/*
+  Writes an uploaded file into the site's own public/ directory and returns the row to record.
+
+  Files go to the *site's* public/, never anywhere inside this package: node_modules is replaced
+  wholesale on every install, so anything written there is one `npm install` away from deletion.
+  It also means kempo-server's own static scanner serves them, which is where range support for
+  video and audio seeking comes from — this extension serves no files itself.
+
+  Returns the usual [error, data] tuple.
+*/
+export default async ({ rootDir, filename, data, mimeType, altText = '', uploadedBy, maxBytes, thumbnailMaxDimension }) => {
+  if(!Buffer.isBuffer(data) || data.length === 0){
+    return [{ code: 400, msg: 'No file content was uploaded' }, null];
+  }
+
+  const type = typeForFilename(filename);
+  if(!type){
+    return [{ code: 415, msg: `Unsupported file type: ${filename}` }, null];
+  }
+
+  if(maxBytes && data.length > maxBytes){
+    const limitMb = Math.round(maxBytes / (1024 * 1024));
+    return [{ code: 413, msg: `File is larger than the ${limitMb}MB limit` }, null];
+  }
+
+  /*
+    The name on disk is generated, never derived from what the client sent. A filename is fully
+    attacker-controlled and is the classic path-traversal vector ("../../.env"), quite apart from
+    collisions between two people uploading "photo.jpg". The original is kept for display only.
+  */
+  const id = crypto.randomBytes(8).toString('hex');
+  const storedName = `${id}.${type.ext}`;
+  const relativePath = join(UPLOAD_DIR, storedName).replace(/\\/g, '/');
+
+  try {
+    await mkdir(join(rootDir, UPLOAD_DIR), { recursive: true });
+    await writeFile(join(rootDir, relativePath), data);
+  } catch(e) {
+    return [{ code: 500, msg: `Could not write the uploaded file: ${e.message}` }, null];
+  }
+
+  /*
+    Thumbnails are images only; every other kind shows a type icon in the library instead. A
+    failure here is deliberately not fatal — the asset is already on disk and perfectly usable, so
+    it is recorded without a preview rather than rejected.
+  */
+  let thumbnailPath = null;
+  let width = null;
+  let height = null;
+  if(type.kind === 'image'){
+    const [thumbError, thumb] = await generateThumbnail({
+      rootDir,
+      data,
+      id,
+      maxDimension: thumbnailMaxDimension
+    });
+    if(thumbError){
+      console.warn(`[kempo-media] No thumbnail for ${filename}: ${thumbError.msg}`);
+    } else {
+      thumbnailPath = thumb.thumbnailPath;
+      width = thumb.width;
+      height = thumb.height;
+    }
+  }
+
+  return [null, {
+    id,
+    filename: storedName,
+    originalName: filename,
+    mimeType: mimeType || type.mime,
+    kind: type.kind,
+    sizeBytes: data.length,
+    path: relativePath,
+    thumbnailPath,
+    altText,
+    width,
+    height,
+    uploadedBy,
+  }];
+};

package/tests/browser-fixtures.node-test.js

@@ -0,0 +1,61 @@
+import { stat, rm, symlink } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/*
+  MediaLibrary.js imports absolute /kempo-ui/... and /kempo-media/sdk.js URLs — the same paths a
+  real kempo-server site resolves via customRoutes and this extension's own public-scope routing.
+  The lightweight static server kempo-testing-framework's browser tests run under has neither: it
+  only serves "." + the request path relative to this repo's own root (see its own
+  browserTestServer.js — there is no config for a different resolution root). So
+  MediaLibrary.browser-test.js needs literal <root>/kempo-ui and <root>/kempo-media directories to
+  exist for those imports to resolve at all.
+
+  Both are junctions created here rather than committed: kempo-ui because it's someone else's large
+  built package (already present under node_modules), and kempo-media because the real target must
+  be a *fake* sdk.js (tests/fixtures/kempo-media-sdk-mock/sdk.js) — the real public/sdk.js talks to
+  a real server this suite never boots.
+
+  This lives in a *.node-test.js file specifically so it always finishes before any browser test
+  starts: kempo-test runs every node test to completion before touching a single browser test (see
+  runTestFiles.js), which is the only ordering guarantee available without a dedicated setup hook.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const ensureJunction = async (linkPath, targetPath) => {
+  try {
+    const stats = await stat(linkPath);
+    if(stats.isDirectory()) return; // already present and resolving
+  } catch { /* fall through and create it */ }
+  await rm(linkPath, { recursive: true, force: true }).catch(() => {});
+  await symlink(targetPath, linkPath, 'junction');
+};
+
+const tests = {
+  'links /kempo-ui to the installed kempo-ui package for browser tests': async ({ pass, fail }) => {
+    const link = path.join(root, 'kempo-ui');
+    const target = path.join(root, 'node_modules', 'kempo-ui', 'dist');
+    await ensureJunction(link, target);
+    try {
+      await stat(path.join(link, 'lit-all.min.js'));
+    } catch {
+      return fail('kempo-ui junction created but lit-all.min.js is not reachable through it');
+    }
+    pass();
+  },
+
+  'links /kempo-media to a fake sdk.js for browser tests': async ({ pass, fail }) => {
+    const link = path.join(root, 'kempo-media');
+    const target = path.join(root, 'tests', 'fixtures', 'kempo-media-sdk-mock');
+    await ensureJunction(link, target);
+    try {
+      await stat(path.join(link, 'sdk.js'));
+    } catch {
+      return fail('kempo-media junction created but sdk.js is not reachable through it');
+    }
+    pass();
+  },
+};
+
+export default tests;

package/tests/browser-modules-parse.node-test.js

@@ -0,0 +1,62 @@
+import { readdir } from 'fs/promises';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const run = promisify(execFile);
+
+/*
+  The browser-side modules under admin/ and public/ are never imported by the node test suite —
+  they pull in absolute /kempo-ui/... URLs that only resolve in a browser — so nothing else here
+  would notice if one stopped parsing.
+
+  That is not hypothetical. A backtick inside a comment within an html`` or css`` template literal
+  terminates the literal, and the rest of the file is then parsed as JavaScript. The module fails
+  to load, the custom element silently never upgrades, and the page renders bare markup with no
+  error beyond one line in the browser console. It happened twice while building this.
+
+  `node --check` parses without executing, so it catches exactly this without needing a browser.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const walk = async dir => {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for(const entry of entries){
+    const full = path.join(dir, entry.name);
+    if(entry.isDirectory()) files.push(...await walk(full));
+    else if(entry.name.endsWith('.js')) files.push(full);
+  }
+  return files;
+};
+
+const files = (await Promise.all(['admin', 'public'].map(d => walk(path.join(root, d))))).flat();
+
+const tests = {
+  'browser modules are discoverable': async ({ pass, fail }) => {
+    if(!files.length) return fail('found no browser modules — this suite would pass without checking anything');
+    pass(`${files.length} module(s)`);
+  }
+};
+
+for(const file of files){
+  const rel = path.relative(root, file).replace(/\\/g, '/');
+  tests[`parses ${rel}`] = async ({ pass, fail }) => {
+    try {
+      await run(process.execPath, ['--check', file]);
+    } catch(e) {
+      const detail = (e.stderr || e.message).split('\n').find(l => l.includes('Error')) || e.message;
+      return fail(detail.trim());
+    }
+    pass();
+  };
+}
+
+export default tests;