@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/media/memory-adapter.js

@@ -0,0 +1,162 @@
+import { foldText } from "../lib/text.js";
+const kindOf = (mime) => mime.startsWith("image/") ? "image" : mime.startsWith("video/") ? "video" : mime.startsWith("audio/") ? "audio" : /pdf|word|sheet|presentation|text/.test(mime) ? "document" : /zip|tar|rar|7z/.test(mime) ? "archive" : "other";
+const wait = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(new DOMException("Aborted", "AbortError"));
+    const id = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(id);
+        reject(new DOMException("Aborted", "AbortError"));
+    });
+});
+function acceptMatches(accept, a) {
+    if (!accept)
+        return true;
+    return accept.split(",").some((raw) => {
+        const rule = raw.trim().toLowerCase();
+        if (!rule)
+            return false;
+        if (rule.startsWith("."))
+            return a.filename.toLowerCase().endsWith(rule);
+        if (rule.endsWith("/*"))
+            return a.mime.startsWith(rule.slice(0, -1));
+        return a.mime === rule;
+    });
+}
+/**
+ * An in-memory adapter for docs, demos, prototypes and tests: object URLs for uploads,
+ * simulated progress, locale-aware search. Nothing persists.
+ *
+ * ```ts
+ * const adapter = createMemoryAdapter({ seed: assets, locale: "tr-TR" });
+ * ```
+ */
+export function createMemoryAdapter(options = {}) {
+    const { latency = 120, uploadDuration = 900, locale = "en-US" } = options;
+    let assets = [...(options.seed ?? [])];
+    let folders = [...(options.folders ?? [])];
+    const listeners = new Set();
+    const emit = (e) => listeners.forEach((l) => l(e));
+    let seq = 0;
+    const nextId = (p) => `${p}_${Date.now().toString(36)}${(seq++).toString(36)}`;
+    const find = (id) => {
+        const a = assets.find((x) => x.id === id);
+        if (!a)
+            throw new Error(`Media ${id} not found`);
+        return a;
+    };
+    async function fromFile(file, opts, id) {
+        const steps = 10;
+        for (let i = 1; i <= steps; i++) {
+            await wait(uploadDuration / steps, opts.signal);
+            opts.onProgress({ loaded: Math.round((file.size * i) / steps), total: file.size });
+        }
+        const url = typeof URL !== "undefined" && URL.createObjectURL ? URL.createObjectURL(file) : "";
+        const dims = file.type.startsWith("image/") ? await imageSize(url) : {};
+        const now = new Date().toISOString();
+        return {
+            id: id ?? nextId("m"),
+            kind: kindOf(file.type),
+            mime: file.type || "application/octet-stream",
+            filename: file.name,
+            size: file.size,
+            url,
+            ...dims,
+            alt: opts.alt ?? "",
+            folderId: opts.folderId ?? null,
+            createdAt: now,
+            updatedAt: now,
+            status: "ready",
+        };
+    }
+    return {
+        capabilities: { folders: true, replace: true, edit: true, trash: false, bulk: true, ...options.capabilities },
+        async list(q, o) {
+            await wait(latency, o?.signal);
+            const kinds = q.kind ? (Array.isArray(q.kind) ? q.kind : [q.kind]) : null;
+            const needle = q.search ? foldText(q.search, locale) : "";
+            let items = assets.filter((a) => (!kinds || kinds.includes(a.kind)) &&
+                acceptMatches(q.accept, a) &&
+                (q.folderId === undefined || (a.folderId ?? null) === q.folderId) &&
+                (!q.month || a.createdAt.startsWith(q.month)) &&
+                (!q.uploadedBy || a.uploadedBy?.id === q.uploadedBy) &&
+                (!q.unattached || !a.usage?.count) &&
+                (!needle || foldText(`${a.filename} ${a.alt} ${a.title ?? ""} ${a.caption ?? ""} ${(a.tags ?? []).join(" ")}`, locale).includes(needle)));
+            const sort = q.sort ?? "newest";
+            items = [...items].sort((a, b) => sort === "name" ? a.filename.localeCompare(b.filename, locale) : sort === "size" ? b.size - a.size : sort === "oldest" ? a.createdAt.localeCompare(b.createdAt) : b.createdAt.localeCompare(a.createdAt));
+            const start = q.cursor ? Number(q.cursor) : 0;
+            const limit = q.limit ?? 60;
+            const page = items.slice(start, start + limit);
+            return { items: page, total: items.length, nextCursor: start + limit < items.length ? String(start + limit) : undefined };
+        },
+        async get(id) {
+            await wait(latency);
+            return find(id);
+        },
+        async getMany(ids) {
+            await wait(latency);
+            return ids.map(find);
+        },
+        async upload(file, opts) {
+            const asset = await fromFile(file, opts);
+            assets = [asset, ...assets];
+            emit({ type: "ready", asset });
+            return asset;
+        },
+        async replace(id, file, opts) {
+            const prev = find(id);
+            const next = { ...(await fromFile(file, opts, id)), alt: prev.alt, title: prev.title, caption: prev.caption, folderId: prev.folderId, createdAt: prev.createdAt };
+            assets = assets.map((a) => (a.id === id ? next : a));
+            emit({ type: "updated", asset: next });
+            return next;
+        },
+        async update(id, patch) {
+            await wait(latency);
+            const next = { ...find(id), ...patch, updatedAt: new Date().toISOString() };
+            assets = assets.map((a) => (a.id === id ? next : a));
+            emit({ type: "updated", asset: next });
+            return next;
+        },
+        async remove(ids) {
+            await wait(latency);
+            assets = assets.filter((a) => !ids.includes(a.id));
+            ids.forEach((id) => emit({ type: "removed", id }));
+        },
+        folders: {
+            async list() {
+                await wait(latency);
+                return folders.map((f) => ({ ...f, count: assets.filter((a) => a.folderId === f.id).length }));
+            },
+            async create(name, parentId = null) {
+                await wait(latency);
+                const f = { id: nextId("f"), name, parentId };
+                folders = [...folders, f];
+                return f;
+            },
+            async rename(id, name) {
+                await wait(latency);
+                folders = folders.map((f) => (f.id === id ? { ...f, name } : f));
+                return folders.find((f) => f.id === id);
+            },
+            async remove(id) {
+                await wait(latency);
+                folders = folders.filter((f) => f.id !== id);
+                assets = assets.map((a) => (a.folderId === id ? { ...a, folderId: null } : a));
+            },
+        },
+        subscribe(cb) {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+    };
+}
+function imageSize(url) {
+    if (typeof window === "undefined" || !url)
+        return Promise.resolve({});
+    return new Promise((resolve) => {
+        const img = new window.Image();
+        img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+        img.onerror = () => resolve({});
+        img.src = url;
+    });
+}

package/dist/media/rest-adapter.d.ts

@@ -0,0 +1,90 @@
+import type { MediaAdapter, MediaAsset, MediaCapabilities, MediaQuery, UploadOptions, ImageLoader } from "./types.js";
+type HeadersSource = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+export interface XhrUploadOptions {
+    method?: "POST" | "PUT";
+    headers?: Record<string, string>;
+    /** Sent as-is (a `File`/`Blob` for a presigned PUT, `FormData` for multipart). */
+    body: XMLHttpRequestBodyInit;
+    signal?: AbortSignal;
+    onProgress?: (p: {
+        loaded: number;
+        total: number;
+    }) => void;
+    withCredentials?: boolean;
+}
+/** XHR request with upload progress and abort. Resolves with the parsed JSON body (or `null`). */
+export declare function xhrUpload<T = unknown>(url: string, { method, headers, body, signal, onProgress, withCredentials }: XhrUploadOptions): Promise<T>;
+/** What `sign` returns for one presigned upload. */
+export interface PresignedTarget {
+    /** Upload id the server uses to complete the upload. */
+    id: string;
+    /** Where to `PUT` (or `POST` with `fields`) the file. */
+    url: string;
+    method?: "PUT" | "POST";
+    headers?: Record<string, string>;
+    /** S3 POST policy fields; when set the file is sent as multipart with these fields first. */
+    fields?: Record<string, string>;
+}
+export interface PresignedUploadOptions {
+    sign: (file: File, o: {
+        folderId?: string | null;
+        alt?: string;
+    }) => Promise<PresignedTarget>;
+    complete: (target: PresignedTarget, file: File) => Promise<MediaAsset>;
+}
+/**
+ * S3 / R2 upload: sign → XHR `PUT` with real progress → complete. Use it as `createRestAdapter({ upload })`
+ * or inside your own adapter's `upload`.
+ *
+ * ```ts
+ * const upload = createPresignedUpload({
+ *   sign: (file) => api.post("/uploads", { name: file.name, type: file.type, size: file.size }),
+ *   complete: (t) => api.post(`/uploads/${t.id}/complete`),
+ * });
+ * ```
+ */
+export declare function createPresignedUpload({ sign, complete }: PresignedUploadOptions): (file: File, opts: UploadOptions) => Promise<MediaAsset>;
+export interface RestAdapterOptions {
+    /** API root, e.g. `"https://cms.example.com/api"`. Endpoints live under `{baseUrl}/media`. */
+    baseUrl: string;
+    /** Static headers or a function (fresh auth token per request). */
+    headers?: HeadersSource;
+    /** Send cookies (`credentials: "include"`). */
+    credentials?: RequestCredentials;
+    /** Custom fetch (tests, SSR). */
+    fetch?: typeof fetch;
+    /**
+     * `"presigned"` (default): `POST /media/uploads` → PUT to the returned URL → `POST /media/uploads/:id/complete`.
+     * `"multipart"`: one `POST /media` with `FormData`. A function replaces both (e.g. `createPresignedUpload`).
+     */
+    upload?: "presigned" | "multipart" | ((file: File, opts: UploadOptions) => Promise<MediaAsset>);
+    capabilities?: Partial<MediaCapabilities>;
+    loader?: ImageLoader;
+    /** Server offers `POST /media/:id/suggest-alt`. */
+    suggestAlt?: boolean;
+    /** Live updates: `"sse"` opens `GET /media/events` (EventSource). Default off. */
+    events?: "sse" | false;
+}
+/**
+ * Adapter for the default vamos-ui media API:
+ *
+ * | Method | Endpoint |
+ * |---|---|
+ * | list | `GET /media?search&kind&accept&folderId&month&uploadedBy&unattached&sort&cursor&limit` → `MediaPage` |
+ * | get / getMany | `GET /media/:id` · `GET /media?ids=a,b` |
+ * | upload | `POST /media/uploads` → `PUT` → `POST /media/uploads/:id/complete` (or multipart `POST /media`) |
+ * | update | `PATCH /media/:id` |
+ * | remove | `DELETE /media?ids=a,b&permanent=1` |
+ * | replace | `POST /media/:id/replace` (multipart) |
+ * | sideload | `POST /media/sideload` `{ url, folderId, alt }` |
+ * | folders | `GET · POST /media/folders`, `PATCH · DELETE /media/folders/:id` |
+ * | events | `GET /media/events` (SSE, `data: MediaEvent`) |
+ *
+ * ```ts
+ * const media = createRestAdapter({ baseUrl: "/api", headers: () => ({ Authorization: `Bearer ${token()}` }) });
+ * ```
+ */
+export declare function createRestAdapter(options: RestAdapterOptions): MediaAdapter;
+/** `MediaQuery` → URL search params (arrays joined with commas, `undefined` dropped). */
+export declare function toSearchParams(q: MediaQuery): string;
+export {};

package/dist/media/rest-adapter.js

@@ -0,0 +1,208 @@
+/** XHR request with upload progress and abort. Resolves with the parsed JSON body (or `null`). */
+export function xhrUpload(url, { method = "POST", headers = {}, body, signal, onProgress, withCredentials }) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new DOMException("Aborted", "AbortError"));
+        const xhr = new XMLHttpRequest();
+        xhr.open(method, url);
+        if (withCredentials)
+            xhr.withCredentials = true;
+        for (const [k, v] of Object.entries(headers))
+            xhr.setRequestHeader(k, v);
+        xhr.upload.onprogress = (e) => {
+            if (e.lengthComputable)
+                onProgress?.({ loaded: e.loaded, total: e.total });
+        };
+        xhr.onload = () => {
+            if (xhr.status >= 200 && xhr.status < 300) {
+                try {
+                    resolve((xhr.responseText ? JSON.parse(xhr.responseText) : null));
+                }
+                catch {
+                    resolve(null);
+                }
+            }
+            else
+                reject(new Error(errorMessage(xhr.responseText, xhr.status)));
+        };
+        xhr.onerror = () => reject(new Error("Network error"));
+        xhr.onabort = () => reject(new DOMException("Aborted", "AbortError"));
+        signal?.addEventListener("abort", () => xhr.abort());
+        xhr.send(body);
+    });
+}
+function errorMessage(text, status) {
+    try {
+        const j = JSON.parse(text);
+        if (j.message || j.error)
+            return String(j.message ?? j.error);
+    }
+    catch {
+        /* not JSON */
+    }
+    return `Request failed (${status})`;
+}
+/**
+ * S3 / R2 upload: sign → XHR `PUT` with real progress → complete. Use it as `createRestAdapter({ upload })`
+ * or inside your own adapter's `upload`.
+ *
+ * ```ts
+ * const upload = createPresignedUpload({
+ *   sign: (file) => api.post("/uploads", { name: file.name, type: file.type, size: file.size }),
+ *   complete: (t) => api.post(`/uploads/${t.id}/complete`),
+ * });
+ * ```
+ */
+export function createPresignedUpload({ sign, complete }) {
+    return async (file, opts) => {
+        const target = await sign(file, { folderId: opts.folderId, alt: opts.alt });
+        if (opts.signal.aborted)
+            throw new DOMException("Aborted", "AbortError");
+        let body = file;
+        if (target.fields) {
+            const form = new FormData();
+            for (const [k, v] of Object.entries(target.fields))
+                form.append(k, v);
+            form.append("file", file);
+            body = form;
+        }
+        await xhrUpload(target.url, {
+            method: target.method ?? (target.fields ? "POST" : "PUT"),
+            headers: target.fields ? target.headers : { "Content-Type": file.type || "application/octet-stream", ...target.headers },
+            body,
+            signal: opts.signal,
+            onProgress: opts.onProgress,
+        });
+        return complete(target, file);
+    };
+}
+/**
+ * Adapter for the default vamos-ui media API:
+ *
+ * | Method | Endpoint |
+ * |---|---|
+ * | list | `GET /media?search&kind&accept&folderId&month&uploadedBy&unattached&sort&cursor&limit` → `MediaPage` |
+ * | get / getMany | `GET /media/:id` · `GET /media?ids=a,b` |
+ * | upload | `POST /media/uploads` → `PUT` → `POST /media/uploads/:id/complete` (or multipart `POST /media`) |
+ * | update | `PATCH /media/:id` |
+ * | remove | `DELETE /media?ids=a,b&permanent=1` |
+ * | replace | `POST /media/:id/replace` (multipart) |
+ * | sideload | `POST /media/sideload` `{ url, folderId, alt }` |
+ * | folders | `GET · POST /media/folders`, `PATCH · DELETE /media/folders/:id` |
+ * | events | `GET /media/events` (SSE, `data: MediaEvent`) |
+ *
+ * ```ts
+ * const media = createRestAdapter({ baseUrl: "/api", headers: () => ({ Authorization: `Bearer ${token()}` }) });
+ * ```
+ */
+export function createRestAdapter(options) {
+    const base = options.baseUrl.replace(/\/+$/, "") + "/media";
+    const doFetch = options.fetch ?? ((...a) => fetch(...a));
+    const resolveHeaders = async () => {
+        const h = typeof options.headers === "function" ? await options.headers() : options.headers;
+        return Object.fromEntries(new Headers(h ?? {}).entries());
+    };
+    async function request(path, init = {}) {
+        const headers = await resolveHeaders();
+        if (init.body && typeof init.body === "string")
+            headers["content-type"] ??= "application/json";
+        const res = await doFetch(base + path, { credentials: options.credentials, ...init, headers: { accept: "application/json", ...headers, ...init.headers } });
+        const text = await res.text();
+        if (!res.ok)
+            throw new Error(errorMessage(text, res.status));
+        return (text ? JSON.parse(text) : undefined);
+    }
+    const json = (body) => JSON.stringify(body);
+    async function multipart(path, file, opts) {
+        const form = new FormData();
+        form.append("file", file);
+        if (opts.folderId !== undefined)
+            form.append("folderId", opts.folderId ?? "");
+        if (opts.alt !== undefined)
+            form.append("alt", opts.alt);
+        return xhrUpload(base + path, {
+            method: "POST",
+            headers: await resolveHeaders(),
+            body: form,
+            signal: opts.signal,
+            onProgress: opts.onProgress,
+            withCredentials: options.credentials === "include",
+        });
+    }
+    const presigned = createPresignedUpload({
+        sign: (file, o) => request("/uploads", { method: "POST", body: json({ filename: file.name, mime: file.type, size: file.size, folderId: o.folderId ?? null, alt: o.alt }) }),
+        complete: (t) => request(`/uploads/${encodeURIComponent(t.id)}/complete`, { method: "POST" }),
+    });
+    const upload = typeof options.upload === "function" ? options.upload : options.upload === "multipart" ? (f, o) => multipart("", f, o) : presigned;
+    const adapter = {
+        capabilities: { folders: true, replace: true, edit: true, trash: false, bulk: true, ...options.capabilities },
+        loader: options.loader,
+        list(q, o) {
+            return request(`?${toSearchParams(q)}`, { signal: o?.signal });
+        },
+        get(id) {
+            return request(`/${encodeURIComponent(id)}`);
+        },
+        async getMany(ids) {
+            if (!ids.length)
+                return [];
+            const page = await request(`?ids=${ids.map(encodeURIComponent).join(",")}`);
+            const list = Array.isArray(page) ? page : page.items;
+            return ids.map((id) => list.find((a) => a.id === id)).filter((a) => Boolean(a));
+        },
+        upload,
+        update(id, patch) {
+            return request(`/${encodeURIComponent(id)}`, { method: "PATCH", body: json(patch) });
+        },
+        async remove(ids, o) {
+            await request(`?ids=${ids.map(encodeURIComponent).join(",")}${o?.permanent ? "&permanent=1" : ""}`, { method: "DELETE" });
+        },
+        replace(id, file, o) {
+            return multipart(`/${encodeURIComponent(id)}/replace`, file, o);
+        },
+        async sideload(url, o) {
+            o.onProgress({ loaded: 0, total: 1 });
+            const asset = await request("/sideload", { method: "POST", body: json({ url, folderId: o.folderId ?? null, alt: o.alt }), signal: o.signal });
+            o.onProgress({ loaded: 1, total: 1 });
+            return asset;
+        },
+        folders: {
+            list: () => request("/folders"),
+            create: (name, parentId = null) => request("/folders", { method: "POST", body: json({ name, parentId }) }),
+            rename: (id, name) => request(`/folders/${encodeURIComponent(id)}`, { method: "PATCH", body: json({ name }) }),
+            remove: (id) => request(`/folders/${encodeURIComponent(id)}`, { method: "DELETE" }),
+        },
+    };
+    if (options.suggestAlt)
+        adapter.suggestAlt = async (id) => (await request(`/${encodeURIComponent(id)}/suggest-alt`, { method: "POST" })).alt;
+    if (options.events === "sse") {
+        adapter.subscribe = (cb) => {
+            if (typeof EventSource === "undefined")
+                return () => { };
+            const es = new EventSource(`${base}/events`, { withCredentials: options.credentials === "include" });
+            es.onmessage = (m) => {
+                try {
+                    cb(JSON.parse(m.data));
+                }
+                catch {
+                    /* ignore malformed events */
+                }
+            };
+            return () => es.close();
+        };
+    }
+    return adapter;
+}
+/** `MediaQuery` → URL search params (arrays joined with commas, `undefined` dropped). */
+export function toSearchParams(q) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(q)) {
+        if (v === undefined || v === "" || v === false)
+            continue;
+        if (v === null)
+            p.set(k, "null");
+        else
+            p.set(k, Array.isArray(v) ? v.join(",") : String(v));
+    }
+    return p.toString();
+}

package/dist/media/serp.d.ts

@@ -0,0 +1,62 @@
+export declare const SERP_LIMITS: {
+    readonly version: "2026-11";
+    readonly desktop: {
+        readonly title: {
+            readonly font: "400 20px Arial, sans-serif";
+            readonly fontSize: 20;
+            readonly maxPx: 600;
+            readonly idealChars: readonly [30, 60];
+        };
+        readonly description: {
+            readonly font: "400 14px Arial, sans-serif";
+            readonly fontSize: 14;
+            readonly maxPx: 920;
+            readonly idealChars: readonly [70, 160];
+        };
+    };
+    readonly mobile: {
+        readonly title: {
+            readonly font: "400 16px Arial, sans-serif";
+            readonly fontSize: 16;
+            readonly maxPx: 640;
+            readonly idealChars: readonly [30, 60];
+        };
+        readonly description: {
+            readonly font: "400 14px Arial, sans-serif";
+            readonly fontSize: 14;
+            readonly maxPx: 680;
+            readonly idealChars: readonly [70, 120];
+        };
+    };
+};
+export type SerpField = "title" | "description";
+export type SerpDevice = "desktop" | "mobile";
+/** Splits into user-perceived characters (emoji, combining marks). */
+export declare function graphemes(text: string, locale?: string): string[];
+/** Character count as people see it (`"👩‍💻"` is 1). */
+export declare function countGraphemes(text: string, locale?: string): number;
+/** Pixel width of `text` in a CSS `font`. Canvas in the browser, an Arial estimate elsewhere. */
+export declare function measureText(text: string, font: string, fontSize: number, estimate?: boolean): number;
+export interface SerpMeasure {
+    /** Rendered width in px. */
+    px: number;
+    /** Limit in px for this field/device. */
+    maxPx: number;
+    truncated: boolean;
+    /** Grapheme index where the visible text ends (before the ellipsis). `length` when not truncated. */
+    cutAt: number;
+    /** The text as shown, with "…" when cut. */
+    display: string;
+}
+/**
+ * How a title or description renders in a search result: width in px and where it gets cut.
+ *
+ * ```ts
+ * Pass `{ estimate: true }` for a canvas-free, deterministic result (server rendering, first paint).
+ *
+ * measureSerp("Spa packages in Kadıköy — Defne Spa", "title"); // { px: 334, truncated: false, … }
+ * ```
+ */
+export declare function measureSerp(text: string, field: SerpField, device?: SerpDevice, locale?: string, options?: {
+    estimate?: boolean;
+}): SerpMeasure;

package/dist/media/serp.js

@@ -0,0 +1,108 @@
+// Search-result truncation constants and measurement. Static and versioned: update the numbers
+// here when search engines change their layout. Google truncates by pixel width, not characters.
+export const SERP_LIMITS = {
+    version: "2026-11",
+    desktop: {
+        title: { font: "400 20px Arial, sans-serif", fontSize: 20, maxPx: 600, idealChars: [30, 60] },
+        description: { font: "400 14px Arial, sans-serif", fontSize: 14, maxPx: 920, idealChars: [70, 160] },
+    },
+    mobile: {
+        title: { font: "400 16px Arial, sans-serif", fontSize: 16, maxPx: 640, idealChars: [30, 60] },
+        description: { font: "400 14px Arial, sans-serif", fontSize: 14, maxPx: 680, idealChars: [70, 120] },
+    },
+};
+/** Splits into user-perceived characters (emoji, combining marks). */
+export function graphemes(text, locale) {
+    if (typeof Intl !== "undefined" && "Segmenter" in Intl) {
+        const seg = new Intl.Segmenter(locale, { granularity: "grapheme" });
+        return Array.from(seg.segment(text), (s) => s.segment);
+    }
+    return Array.from(text);
+}
+/** Character count as people see it (`"👩‍💻"` is 1). */
+export function countGraphemes(text, locale) {
+    return graphemes(text, locale).length;
+}
+// Arial advance widths in em, used when canvas is unavailable (server, tests).
+const NARROW = new Set("iljtf.,;:'!|()[]{} ".split(""));
+const SEMI = new Set("rI-\"`*".split(""));
+const WIDE = new Set("mwMW@%".split(""));
+function estimateWidth(text, fontSize) {
+    let em = 0;
+    for (const ch of text) {
+        if (NARROW.has(ch))
+            em += 0.278;
+        else if (SEMI.has(ch))
+            em += 0.333;
+        else if (WIDE.has(ch))
+            em += 0.86;
+        else if (/[A-ZÇĞİÖŞÜ0-9]/.test(ch))
+            em += 0.667;
+        else if (/\p{Extended_Pictographic}/u.test(ch))
+            em += 1.1;
+        else
+            em += 0.556;
+    }
+    return em * fontSize;
+}
+let ctx;
+function canvasContext() {
+    if (ctx !== undefined)
+        return ctx;
+    try {
+        const jsdom = typeof navigator !== "undefined" && /jsdom/i.test(navigator.userAgent);
+        ctx = typeof document !== "undefined" && !jsdom ? document.createElement("canvas").getContext("2d") : null;
+    }
+    catch {
+        ctx = null;
+    }
+    return ctx;
+}
+/** Pixel width of `text` in a CSS `font`. Canvas in the browser, an Arial estimate elsewhere. */
+export function measureText(text, font, fontSize, estimate = false) {
+    const c = estimate ? null : canvasContext();
+    if (c) {
+        c.font = font;
+        const w = c.measureText(text).width;
+        if (w > 0 || text === "")
+            return w;
+    }
+    return estimateWidth(text, fontSize);
+}
+/**
+ * How a title or description renders in a search result: width in px and where it gets cut.
+ *
+ * ```ts
+ * Pass `{ estimate: true }` for a canvas-free, deterministic result (server rendering, first paint).
+ *
+ * measureSerp("Spa packages in Kadıköy — Defne Spa", "title"); // { px: 334, truncated: false, … }
+ * ```
+ */
+export function measureSerp(text, field, device = "desktop", locale, options = {}) {
+    const spec = SERP_LIMITS[device][field];
+    const clean = text.replace(/\s+/g, " ").trim();
+    const est = options.estimate ?? false;
+    const measure = (t) => measureText(t, spec.font, spec.fontSize, est);
+    const px = measure(clean);
+    const chars = graphemes(clean, locale);
+    if (px <= spec.maxPx)
+        return { px, maxPx: spec.maxPx, truncated: false, cutAt: chars.length, display: clean };
+    const ellipsis = measure(" …");
+    // Binary search the longest prefix that fits with the ellipsis.
+    let lo = 0;
+    let hi = chars.length;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (measure(chars.slice(0, mid).join("")) + ellipsis <= spec.maxPx)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    // Prefer a word boundary when it is close.
+    let cut = lo;
+    const lastSpace = chars.slice(0, lo).lastIndexOf(" ");
+    if (lastSpace > 0 && lo - lastSpace < 16)
+        cut = lastSpace;
+    const shown = chars.slice(0, cut).join("").replace(/[\s,;:—–-]+$/, "");
+    return { px, maxPx: spec.maxPx, truncated: true, cutAt: cut, display: `${shown} …` };
+}

package/dist/media/test-fixtures.d.ts

@@ -0,0 +1,3 @@
+import type { MediaAsset, MediaFolder } from "./types.js";
+export declare const mediaFolders: MediaFolder[];
+export declare const mediaSeed: MediaAsset[];

package/dist/media/test-fixtures.js

@@ -0,0 +1,37 @@
+const img = (id, filename, alt, extra = {}) => ({
+    id,
+    kind: "image",
+    mime: "image/jpeg",
+    filename,
+    size: 482_000,
+    url: `https://cdn.example.com/${filename}`,
+    width: 2400,
+    height: 1600,
+    alt,
+    createdAt: "2026-11-04T09:12:00Z",
+    folderId: null,
+    uploadedBy: { id: "u1", name: "Elif Demir" },
+    ...extra,
+});
+export const mediaFolders = [
+    { id: "f_blog", name: "Blog" },
+    { id: "f_team", name: "Team" },
+];
+export const mediaSeed = [
+    img("m1", "harbour-sunrise.jpg", "Fishing boats in Kadıköy harbour at sunrise", { folderId: "f_blog" }),
+    img("m2", "team-offsite.jpg", "", { folderId: "f_team", createdAt: "2026-10-21T14:00:00Z" }),
+    img("m3", "office-lobby.jpg", "Reception desk with oak panels and a green wall", { createdAt: "2026-10-02T08:30:00Z" }),
+    img("m4", "small-logo.png", "Vamos logo", { mime: "image/png", width: 400, height: 210, size: 18_400 }),
+    {
+        id: "m5",
+        kind: "document",
+        mime: "application/pdf",
+        filename: "q3-board-report.pdf",
+        size: 2_400_000,
+        url: "https://cdn.example.com/q3-board-report.pdf",
+        alt: "",
+        createdAt: "2026-09-18T16:45:00Z",
+        folderId: null,
+        uploadedBy: { id: "u2", name: "Mert Aksoy" },
+    },
+];