@jant/core 0.6.16 → 0.7.0

package/src/client/image-processor.ts

@@ -5,10 +5,19 @@
  * - Resizes oversized images (caps the short side; the long side rides free)
  * - Strips all metadata (privacy)
  * - Converts to WebP format (JPEG fallback when WebP encoding is unavailable)
+ * - Samples a blurhash placeholder from the decoded pixels
  *
- * EXIF orientation is handled automatically by the browser — modern
- * engines (Chrome 81+, Safari 13.1+, Firefox 93+) apply orientation
- * both in `<img>` rendering and in canvas `drawImage`.
+ * The work runs in a Web Worker (`image-worker.ts`) wherever the browser can
+ * decode and encode there — every engine with OffscreenCanvas. Decoding a
+ * photo and encoding the result are the heaviest things the composer does on
+ * the client; on the main thread they froze the page for their whole
+ * duration, and several photos at once froze it for seconds. Browsers without
+ * OffscreenCanvas, and any file the worker cannot decode, take the in-page
+ * canvas path below.
+ *
+ * EXIF orientation is handled by the browser on both paths — `<img>`, canvas
+ * `drawImage`, and `createImageBitmap` with `imageOrientation: "from-image"`
+ * all report and draw the oriented image.
  *
  * Long and wide screenshots (chat logs, articles, wide tables) lose their
  * text legibility if the short side is scaled down, so the resize step caps
@@ -17,25 +26,104 @@
  * untouched, so images of any length are supported.
  */
 
-/** Cap for the shorter image side — the side that determines text sharpness. */
-const MAX_SHORT_SIDE = 1920;
+import { encode } from "blurhash";
+import {
+  DEFAULT_IMAGE_PROCESS_OPTIONS,
+  blurhashDimensions,
+  planImageProcessing,
+  resolveEncodedMimeType,
+  type ImageProcessOptions,
+  type ImageWorkerRequest,
+  type ImageWorkerResponse,
+} from "./image-plan.js";
+import {
+  createImageWorker,
+  supportsImageWorker,
+} from "./image-worker-client.js";
 
-/**
- * Largest long side we can still redraw on a canvas. A canvas bounded by
- * MAX_SHORT_SIDE × MAX_LONG_SIDE (1920 × 8192 ≈ 15.7M px) stays under the
- * ~16.7M-pixel area limit older mobile Safari enforces. Anything longer
- * can't be re-encoded, so it uploads as-is.
- */
-const MAX_LONG_SIDE = 8192;
+type ProcessOptions = Partial<ImageProcessOptions>;
+
+export interface ProcessResult {
+  blob: Blob;
+  width: number;
+  height: number;
+  /** False when `blob` is the untouched original (too large to re-encode). */
+  processed: boolean;
+  /** Absent only when the pixels could not be sampled. */
+  blurhash?: string;
+}
+
+export interface ProcessToFileResult {
+  file: File;
+  width: number;
+  height: number;
+  blurhash?: string;
+}
+
+// ── Worker path ──────────────────────────────────────────────────────────
+
+interface PendingRequest {
+  resolve(result: ProcessResult): void;
+  reject(error: Error): void;
+}
+
+let worker: Worker | null = null;
+let nextRequestId = 1;
+const pending = new Map<number, PendingRequest>();
+
+/** One worker for the page, started on the first image and kept warm. */
+function getWorker(): Worker {
+  if (worker) return worker;
+  const created = createImageWorker();
+  created.addEventListener(
+    "message",
+    (event: MessageEvent<ImageWorkerResponse>) => {
+      const response = event.data;
+      const request = pending.get(response.id);
+      if (!request) return;
+      pending.delete(response.id);
+      if (response.ok) {
+        request.resolve({
+          blob: response.blob,
+          width: response.width,
+          height: response.height,
+          processed: response.processed,
+          blurhash: response.blurhash,
+        });
+      } else {
+        request.reject(new Error(response.error));
+      }
+    },
+  );
+  // A worker that dies takes every in-flight image with it. Fail them over to
+  // the in-page path and start clean for the next one.
+  created.addEventListener("error", (event) => {
+    if (worker !== created) return;
+    worker = null;
+    created.terminate();
+    const requests = [...pending.values()];
+    pending.clear();
+    const error = new Error(event.message || "Image worker failed");
+    for (const request of requests) request.reject(error);
+  });
+  worker = created;
+  return created;
+}
 
-const DEFAULT_OPTIONS = {
-  maxShortSide: MAX_SHORT_SIDE,
-  maxLongSide: MAX_LONG_SIDE,
-  quality: 0.85,
-  mimeType: "image/webp" as const,
-};
+function processInWorker(
+  file: File,
+  options: ImageProcessOptions,
+): Promise<ProcessResult> {
+  const target = getWorker();
+  return new Promise((resolve, reject) => {
+    const id = nextRequestId++;
+    pending.set(id, { resolve, reject });
+    const request: ImageWorkerRequest = { id, file, options };
+    target.postMessage(request);
+  });
+}
 
-type ProcessOptions = Partial<typeof DEFAULT_OPTIONS>;
+// ── In-page path ─────────────────────────────────────────────────────────
 
 /**
  * Load image from file
@@ -52,115 +140,73 @@ function loadImage(file: File): Promise<HTMLImageElement> {
   });
 }
 
-export interface ImageProcessPlan {
-  /** When true, upload the original file untouched (too large to re-encode). */
-  passthrough: boolean;
-  /** Target dimensions — equal to the source dimensions when `passthrough`. */
-  width: number;
-  height: number;
-}
-
-/**
- * Decide how to handle an image given its source dimensions.
- *
- * - Long side over `maxLongSide` → `passthrough` (canvas can't redraw it).
- * - Short side within `maxShortSide` → keep dimensions, just re-encode.
- * - Otherwise → scale down so the short side hits `maxShortSide`.
- *
- * @param sourceWidth - Natural image width in pixels
- * @param sourceHeight - Natural image height in pixels
- * @param options - `maxShortSide` and `maxLongSide` caps
- * @returns The processing plan
- *
- * @example
- * ```ts
- * planImageProcessing(1080, 6000, { maxShortSide: 1920, maxLongSide: 8192 });
- * // { passthrough: false, width: 1080, height: 6000 }
- * ```
- */
-export function planImageProcessing(
-  sourceWidth: number,
-  sourceHeight: number,
-  options: { maxShortSide: number; maxLongSide: number },
-): ImageProcessPlan {
-  const longSide = Math.max(sourceWidth, sourceHeight);
-  if (longSide > options.maxLongSide) {
-    return { passthrough: true, width: sourceWidth, height: sourceHeight };
-  }
-
-  const shortSide = Math.min(sourceWidth, sourceHeight);
-  if (shortSide <= options.maxShortSide) {
-    return { passthrough: false, width: sourceWidth, height: sourceHeight };
-  }
-
-  const scale = options.maxShortSide / shortSide;
-  return {
-    passthrough: false,
-    width: Math.round(sourceWidth * scale),
-    height: Math.round(sourceHeight * scale),
-  };
+function createCanvas(width: number, height: number) {
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Failed to get canvas context");
+  return { canvas, ctx };
 }
 
-/**
- * Convert canvas to Blob, falling back to JPEG when the requested format
- * (typically WebP) is not supported by the browser (e.g. Safari).
- */
-async function canvasToBlob(
+function canvasToBlob(
   canvas: HTMLCanvasElement,
-  mimeType: string,
+  type: string,
   quality: number,
 ): Promise<Blob> {
-  const blob = await new Promise<Blob>((resolve, reject) => {
+  return new Promise<Blob>((resolve, reject) => {
     canvas.toBlob(
       (b) => (b ? resolve(b) : reject(new Error("Failed to create blob"))),
-      mimeType,
+      type,
       quality,
     );
   });
-
-  // Browser silently falls back to PNG when it can't encode the requested
-  // format. PNG ignores the quality parameter, producing oversized files.
-  // Re-encode as JPEG instead so lossy compression still applies.
-  if (mimeType !== "image/png" && blob.type === "image/png") {
-    return new Promise<Blob>((resolve, reject) => {
-      canvas.toBlob(
-        (b) => (b ? resolve(b) : reject(new Error("Failed to create blob"))),
-        "image/jpeg",
-        quality,
-      );
-    });
-  }
-
-  return blob;
 }
 
-export interface ProcessResult {
-  blob: Blob;
-  width: number;
-  height: number;
-  /** False when `blob` is the untouched original (too large to re-encode). */
-  processed: boolean;
+const pageEncodeTypeByRequest = new Map<string, Promise<string>>();
+
+/** The format `toBlob` really produces for `requested`, probed once. */
+function resolveEncodeTypeOnPage(
+  requested: string,
+  quality: number,
+): Promise<string> {
+  let pending = pageEncodeTypeByRequest.get(requested);
+  if (!pending) {
+    pending = canvasToBlob(createCanvas(1, 1).canvas, requested, quality).then(
+      (probe) => resolveEncodedMimeType(requested, probe.type),
+    );
+    pageEncodeTypeByRequest.set(requested, pending);
+  }
+  return pending;
 }
 
-export interface ProcessToFileResult {
-  file: File;
-  width: number;
-  height: number;
+/** Best-effort: no blurhash beats no upload. */
+function blurhashOf(img: HTMLImageElement): string | undefined {
+  try {
+    const { width, height } = blurhashDimensions(img.width, img.height);
+    const { ctx } = createCanvas(width, height);
+    ctx.drawImage(img, 0, 0, width, height);
+    return encode(
+      ctx.getImageData(0, 0, width, height).data,
+      width,
+      height,
+      4,
+      3,
+    );
+  } catch {
+    return undefined;
+  }
 }
 
-/**
- * Process image file
- */
-async function process(
+async function processOnPage(
   file: File,
-  options: ProcessOptions = {},
+  options: ImageProcessOptions,
 ): Promise<ProcessResult> {
-  const opts = { ...DEFAULT_OPTIONS, ...options };
-
   const img = await loadImage(file);
 
   // img.width / img.height already reflect EXIF orientation in modern browsers
-  const plan = planImageProcessing(img.width, img.height, opts);
+  const plan = planImageProcessing(img.width, img.height, options);
+  const blurhash = blurhashOf(img);
 
   // Too large to redraw on a canvas without crushing detail — keep the
   // original bytes so images of any length upload at full quality.
@@ -170,22 +216,48 @@ async function process(
       width: plan.width,
       height: plan.height,
       processed: false,
+      blurhash,
     };
   }
 
-  const canvas = document.createElement("canvas");
-  canvas.width = plan.width;
-  canvas.height = plan.height;
-
-  const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("Failed to get canvas context");
-
+  const { canvas, ctx } = createCanvas(plan.width, plan.height);
   // drawImage respects EXIF orientation — no manual rotation needed
   ctx.drawImage(img, 0, 0, plan.width, plan.height);
 
-  const blob = await canvasToBlob(canvas, opts.mimeType, opts.quality);
+  const type = await resolveEncodeTypeOnPage(options.mimeType, options.quality);
+  const blob = await canvasToBlob(canvas, type, options.quality);
+
+  return {
+    blob,
+    width: plan.width,
+    height: plan.height,
+    processed: true,
+    blurhash,
+  };
+}
+
+// ── Facade ───────────────────────────────────────────────────────────────
 
-  return { blob, width: plan.width, height: plan.height, processed: true };
+/**
+ * Process image file
+ */
+async function process(
+  file: File,
+  options: ProcessOptions = {},
+): Promise<ProcessResult> {
+  const opts = { ...DEFAULT_IMAGE_PROCESS_OPTIONS, ...options };
+
+  if (supportsImageWorker()) {
+    try {
+      return await processInWorker(file, opts);
+    } catch {
+      // The worker could not decode this file, or never started. `<img>`
+      // accepts a few things `createImageBitmap` does not, and if it fails
+      // too, that is the error worth reporting.
+    }
+  }
+
+  return processOnPage(file, opts);
 }
 
 /**
@@ -199,7 +271,12 @@ async function processToFile(
 
   // Original kept untouched — upload the file as-is.
   if (!result.processed) {
-    return { file, width: result.width, height: result.height };
+    return {
+      file,
+      width: result.width,
+      height: result.height,
+      blurhash: result.blurhash,
+    };
   }
 
   // Use actual blob type — Safari falls back to JPEG when WebP encoding isn't supported
@@ -216,6 +293,7 @@ async function processToFile(
     file: new File([result.blob], newName, { type: result.blob.type }),
     width: result.width,
     height: result.height,
+    blurhash: result.blurhash,
   };
 }
 

package/src/client/image-worker-client.ts

@@ -0,0 +1,45 @@
+/**
+ * Where the image worker comes from.
+ *
+ * Kept apart from `ImageProcessor` so tests can stand in a fake worker, and so
+ * the `?worker&inline` import has exactly one home. Inline — Vite bundles the
+ * worker into the client script and starts it from a `blob:` URL — rather than
+ * a separate file, because client assets may be served from another origin
+ * (`ASSET_BASE_URL`) and a worker script must be same-origin with the page.
+ * CSP already admits `blob:` scripts for the media workers.
+ */
+
+import ImageWorker from "./image-worker.js?worker&inline";
+
+/**
+ * Whether this browser can decode and encode images inside a worker.
+ *
+ * @returns True when `Worker`, `OffscreenCanvas`, and `createImageBitmap` exist
+ *
+ * @example
+ * ```ts
+ * if (supportsImageWorker()) worker = createImageWorker();
+ * ```
+ */
+export function supportsImageWorker(): boolean {
+  return (
+    typeof Worker === "function" &&
+    typeof OffscreenCanvas === "function" &&
+    typeof createImageBitmap === "function"
+  );
+}
+
+/**
+ * Start a fresh image worker.
+ *
+ * @returns The worker, speaking the protocol in `image-plan.ts`
+ *
+ * @example
+ * ```ts
+ * const worker = createImageWorker();
+ * worker.postMessage({ id: 1, file, options });
+ * ```
+ */
+export function createImageWorker(): Worker {
+  return new ImageWorker({ name: "jant-image" });
+}

package/src/client/image-worker.ts

@@ -0,0 +1,135 @@
+/**
+ * Image processing worker.
+ *
+ * Decodes, resizes, re-encodes, and blurhashes an image entirely off the main
+ * thread: `createImageBitmap` decodes without touching the DOM, and
+ * `OffscreenCanvas.convertToBlob` encodes without a synchronous readback on
+ * the UI thread. Selecting a 12-megapixel photo used to hold the composer for
+ * a couple of hundred milliseconds per image; here it costs the page a
+ * `postMessage`.
+ *
+ * Protocol in `image-plan.ts`. A failure is reported back, not retried: the
+ * caller falls back to the in-page canvas path, which is also what browsers
+ * without OffscreenCanvas use.
+ */
+
+import { encode } from "blurhash";
+import {
+  blurhashDimensions,
+  planImageProcessing,
+  resolveEncodedMimeType,
+  type ImageProcessOptions,
+  type ImageWorkerRequest,
+  type ImageWorkerResponse,
+  type ImageWorkerSuccess,
+} from "./image-plan.js";
+
+// The DOM lib types `self` as a Window; the worker needs only the two members
+// both scopes share, typed against this module's own protocol.
+const scope = self as unknown as {
+  addEventListener(
+    type: "message",
+    listener: (event: MessageEvent<ImageWorkerRequest>) => void,
+  ): void;
+  postMessage(message: ImageWorkerResponse): void;
+};
+
+const encodeTypeByRequest = new Map<string, Promise<string>>();
+
+/** The format `convertToBlob` really produces for `requested`, probed once. */
+function resolveEncodeType(
+  requested: string,
+  quality: number,
+): Promise<string> {
+  let pending = encodeTypeByRequest.get(requested);
+  if (!pending) {
+    const { canvas } = draw(null, 1, 1);
+    pending = canvas
+      .convertToBlob({ type: requested, quality })
+      .then((probe) => resolveEncodedMimeType(requested, probe.type));
+    encodeTypeByRequest.set(requested, pending);
+  }
+  return pending;
+}
+
+function draw(
+  source: ImageBitmap | null,
+  width: number,
+  height: number,
+): { canvas: OffscreenCanvas; ctx: OffscreenCanvasRenderingContext2D } {
+  const canvas = new OffscreenCanvas(width, height);
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Failed to get canvas context");
+  if (source) ctx.drawImage(source, 0, 0, width, height);
+  return { canvas, ctx };
+}
+
+/** Best-effort, like the metadata pass it replaces: no blurhash beats no upload. */
+function blurhashOf(bitmap: ImageBitmap): string | undefined {
+  try {
+    const { width, height } = blurhashDimensions(bitmap.width, bitmap.height);
+    const { ctx } = draw(bitmap, width, height);
+    return encode(
+      ctx.getImageData(0, 0, width, height).data,
+      width,
+      height,
+      4,
+      3,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+async function processImage(
+  file: File,
+  options: ImageProcessOptions,
+): Promise<Omit<ImageWorkerSuccess, "id" | "ok">> {
+  // `from-image` applies EXIF orientation, so the bitmap's dimensions are the
+  // ones the photo is meant to be seen at — the same as `<img>` reports.
+  const bitmap = await createImageBitmap(file, {
+    imageOrientation: "from-image",
+  });
+  try {
+    const plan = planImageProcessing(bitmap.width, bitmap.height, options);
+    const blurhash = blurhashOf(bitmap);
+
+    // Too large to redraw on a canvas without crushing detail — keep the
+    // original bytes so images of any length upload at full quality.
+    if (plan.passthrough) {
+      return {
+        blob: file,
+        width: plan.width,
+        height: plan.height,
+        processed: false,
+        blurhash,
+      };
+    }
+
+    const { canvas } = draw(bitmap, plan.width, plan.height);
+    const type = await resolveEncodeType(options.mimeType, options.quality);
+    const blob = await canvas.convertToBlob({ type, quality: options.quality });
+    return {
+      blob,
+      width: plan.width,
+      height: plan.height,
+      processed: true,
+      blurhash,
+    };
+  } finally {
+    bitmap.close();
+  }
+}
+
+scope.addEventListener("message", async (event) => {
+  const { id, file, options } = event.data;
+  try {
+    scope.postMessage({ id, ok: true, ...(await processImage(file, options)) });
+  } catch (error) {
+    scope.postMessage({
+      id,
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+});

package/src/client/lazy-entries.ts

@@ -0,0 +1,95 @@
+/**
+ * The authenticated bundle, split by what a page needs.
+ *
+ * `client-auth.ts` is the shell every signed-in page loads: the post menu,
+ * command palette, shortcuts, and the triggers that open the composer. The
+ * heavier parts ship as their own entries and load through here:
+ *
+ * - `client-compose.ts` — the editor. Loaded the first time the composer
+ *   opens (`compose-launch.ts`), at once on the compose page, and preloaded
+ *   by the layout on every signed-in page so that first open costs no
+ *   round trip.
+ * - `client-settings.ts` — the settings pages' components.
+ * - `client-manage.ts` — navigation manager, collection directory, and the
+ *   collection page menus.
+ *
+ * The page decides: {@link loadEntriesForPage} looks for the elements and
+ * hooks the server renders only where an entry is needed, and keeps looking
+ * as fragments arrive, so a component never has to be registered up front.
+ * `docs/internal/lit-guide.md` says which entry a new component belongs in.
+ */
+
+function once(load: () => Promise<unknown>): () => Promise<void> {
+  let loading: Promise<void> | undefined;
+  return () => (loading ??= load().then(() => undefined));
+}
+
+/** Load the composer entry; resolves once its elements are defined. */
+export const ensureCompose = once(() => import("../client-compose.js"));
+
+/** Load the settings entry; resolves once its elements are defined. */
+export const ensureSettings = once(() => import("../client-settings.js"));
+
+/** Load the management entry; resolves once its elements are defined. */
+export const ensureManage = once(() => import("../client-manage.js"));
+
+/**
+ * Markup the server renders only on pages that need an entry. A selector
+ * matching means the page cannot work without that entry, so it loads at
+ * once; the composer on an ordinary page is not listed because it loads on
+ * first open instead.
+ */
+const PAGE_ENTRIES: ReadonlyArray<{
+  selector: string;
+  load: () => Promise<void>;
+}> = [
+  { selector: '[data-page="compose"]', load: ensureCompose },
+  {
+    selector: [
+      "jant-settings-general",
+      "jant-settings-language",
+      "jant-settings-avatar",
+      "jant-config-editor",
+      "jant-repo-picker",
+    ].join(", "),
+    load: ensureSettings,
+  },
+  {
+    selector: [
+      "jant-nav-manager",
+      "jant-collections-manager",
+      "[data-collection-page-actions]",
+      "[data-smart-collection-page-actions]",
+      "[data-custom-url-actions]",
+    ].join(", "),
+    load: ensureManage,
+  },
+];
+
+/**
+ * Load every entry whose markup is on the page, now and as the DOM changes.
+ *
+ * @example
+ * ```ts
+ * // client-auth.ts, once the shell is set up
+ * loadEntriesForPage();
+ * ```
+ */
+export function loadEntriesForPage(): void {
+  const pending = new Set(PAGE_ENTRIES);
+  const observer = new globalThis.MutationObserver(check);
+
+  function check(): void {
+    for (const entry of pending) {
+      if (!document.querySelector(entry.selector)) continue;
+      pending.delete(entry);
+      void entry.load();
+    }
+    if (pending.size === 0) observer.disconnect();
+  }
+
+  check();
+  if (pending.size > 0) {
+    observer.observe(document.body, { childList: true, subtree: true });
+  }
+}

package/src/client/lazy-slugify.ts

@@ -1,7 +1,7 @@
 /**
  * Lazy-loaded slug generation
  *
- * Wraps the `slugify` function from `url.ts` behind a dynamic import so
+ * Wraps the `slugify` function from `lib/slugify.ts` behind a dynamic import so
  * `limax` (used for i18n-aware transliteration) doesn't bloat the main
  * client bundle. Vite code-splits it into a separate chunk.
  *
@@ -22,7 +22,7 @@ let loadingPromise: Promise<SlugifyFn> | undefined;
 function load(): Promise<SlugifyFn> {
   if (slugifyFn) return Promise.resolve(slugifyFn);
   if (!loadingPromise) {
-    loadingPromise = import("../lib/url.js").then((mod) => {
+    loadingPromise = import("../lib/slugify.js").then((mod) => {
       slugifyFn = mod.slugify;
       return mod.slugify;
     });