@acms-subir/core 0.0.1

package/src/components/editor/extensions/postList.tsx

@@ -0,0 +1,130 @@
+import { Node } from '@tiptap/core';
+import { NodeViewWrapper, ReactNodeViewRenderer } from '@tiptap/react';
+import type { NodeViewProps } from '@tiptap/react';
+import { CONTENT } from '../../../lib/content';
+
+// Post-list card: a *dynamic* block. It serializes into bodyHtml as a
+// placeholder div (data-dyn="post-list") that public routes expand at request
+// time via src/lib/dynamicBlocks.ts — the list stays fresh without re-saving
+// the page. The editor shows a config panel + schematic preview; the split
+// preview iframe shows the real, expanded result.
+
+export const PostListCard = Node.create({
+  name: 'postListCard',
+  group: 'block',
+  atom: true,
+  draggable: true,
+
+  addAttributes() {
+    return {
+      source: { default: 'latest' }, // latest | tag | featured
+      collection: { default: 'posts' }, // acms content.collections key
+      tag: { default: '' },
+      layout: { default: 'list' }, // list | grid | feature
+      limit: { default: 3 },
+      showImage: { default: true },
+      showExcerpt: { default: true },
+    };
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'div[data-dyn="post-list"]',
+        getAttrs: (el) => {
+          const e = el as HTMLElement;
+          return {
+            source: e.getAttribute('data-source') ?? 'latest',
+            collection: e.getAttribute('data-collection') || 'posts',
+            tag: e.getAttribute('data-tag') ?? '',
+            layout: e.getAttribute('data-layout') ?? 'list',
+            limit: Number(e.getAttribute('data-limit') ?? 3),
+            showImage: e.getAttribute('data-show-image') !== '0',
+            showExcerpt: e.getAttribute('data-show-excerpt') !== '0',
+          };
+        },
+      },
+    ];
+  },
+
+  renderHTML({ node }) {
+    const a = node.attrs;
+    return [
+      'div',
+      {
+        'data-dyn': 'post-list',
+        'data-source': a.source,
+        'data-collection': a.collection,
+        'data-tag': a.tag,
+        'data-layout': a.layout,
+        'data-limit': String(a.limit),
+        'data-show-image': a.showImage ? '1' : '0',
+        'data-show-excerpt': a.showExcerpt ? '1' : '0',
+      },
+    ];
+  },
+
+  addNodeView() {
+    return ReactNodeViewRenderer(PostListView);
+  },
+});
+
+function PostListView({ node, updateAttributes, deleteNode, selected }: NodeViewProps) {
+  const a = node.attrs;
+  const count = Math.min(12, Math.max(1, Number(a.limit) || 3));
+  const plural = (CONTENT.collections[a.collection] ?? CONTENT.posts).plural;
+  const multi = Object.keys(CONTENT.collections).length > 1;
+  const label =
+    a.source === 'featured' ? `Featured ${plural.toLowerCase()}` : a.source === 'tag' ? `${plural} tagged “${a.tag || '…'}”` : `Latest ${plural.toLowerCase()}`;
+  return (
+    <NodeViewWrapper className={`pe-card pe-postlist ${selected ? 'is-selected' : ''}`} data-drag-handle>
+      <div className="pe-card-tools" contentEditable={false}>
+        <button type="button" title="Remove" onClick={() => deleteNode()}>✕</button>
+      </div>
+      <div className="pe-postlist-config" contentEditable={false}>
+        <span className="pe-postlist-badge">{(CONTENT.collections[a.collection] ?? CONTENT.posts).singular} list · dynamic</span>
+        {multi && (
+          <select value={a.collection} onChange={(e) => updateAttributes({ collection: e.target.value })}>
+            {Object.entries(CONTENT.collections).map(([k, c]) => (
+              <option key={k} value={k}>{c.plural}</option>
+            ))}
+          </select>
+        )}
+        <select value={a.source} onChange={(e) => updateAttributes({ source: e.target.value })}>
+          <option value="latest">Latest</option>
+          <option value="tag">By tag</option>
+          <option value="featured">Featured</option>
+        </select>
+        {a.source === 'tag' && (
+          <input
+            type="text"
+            placeholder="Tag name"
+            value={a.tag}
+            onChange={(e) => updateAttributes({ tag: e.target.value })}
+          />
+        )}
+        <select value={a.layout} onChange={(e) => updateAttributes({ layout: e.target.value })}>
+          <option value="list">List</option>
+          <option value="grid">Grid</option>
+          <option value="feature">Feature</option>
+        </select>
+        <select value={count} onChange={(e) => updateAttributes({ limit: Number(e.target.value) })}>
+          {[1, 2, 3, 4, 6, 8, 10, 12].map((n) => <option key={n} value={n}>{n} post{n > 1 ? 's' : ''}</option>)}
+        </select>
+        <label><input type="checkbox" checked={a.showImage} onChange={(e) => updateAttributes({ showImage: e.target.checked })} /> Images</label>
+        <label><input type="checkbox" checked={a.showExcerpt} onChange={(e) => updateAttributes({ showExcerpt: e.target.checked })} /> Excerpts</label>
+      </div>
+      <div className={`pe-postlist-ghost layout-${a.layout}`} contentEditable={false}>
+        {Array.from({ length: Math.min(count, a.layout === 'feature' ? 2 : 4) }, (_, i) => (
+          <div className="pe-postlist-ghostcard" key={i}>
+            {a.showImage && <div className="g-img" />}
+            <div className="g-line w60" />
+            <div className="g-line w90" />
+            {a.showExcerpt && <div className="g-line w75" />}
+          </div>
+        ))}
+        <p className="pe-postlist-note">{label} — renders live on the site (see preview)</p>
+      </div>
+    </NodeViewWrapper>
+  );
+}

package/src/components/editor/extensions/slash.tsx

@@ -0,0 +1,250 @@
+import { Extension, ReactRenderer } from '@tiptap/react';
+import type { Editor, Range } from '@tiptap/react';
+import Suggestion from '@tiptap/suggestion';
+import { forwardRef, useEffect, useImperativeHandle, useState } from 'react';
+import { CONTENT } from '../../../lib/content';
+
+// "/" command menu, Ghost-style: type / on a line to insert cards and blocks.
+
+export interface SlashContext {
+  openImagePicker: (insertAt: Range) => void;
+}
+
+interface SlashItem {
+  title: string;
+  description: string;
+  keywords: string;
+  group: 'Basic' | 'Cards';
+  icon: string; // svg path (24 viewBox, stroked)
+  run: (editor: Editor, range: Range, ctx: SlashContext) => void;
+}
+
+const ITEMS: SlashItem[] = [
+  {
+    title: 'Image', description: 'Upload, library or Unsplash', keywords: 'image photo picture unsplash upload', group: 'Cards',
+    icon: 'M3 5h18v14H3zM3 15l5-5 4 4 3-3 6 6M15.5 9.5h0',
+    run: (editor, range, ctx) => {
+      editor.chain().focus().deleteRange(range).run();
+      ctx.openImagePicker({ from: editor.state.selection.from, to: editor.state.selection.from });
+    },
+  },
+  {
+    title: 'Gallery', description: 'Grid of 2–9 images', keywords: 'gallery grid images photos', group: 'Cards',
+    icon: 'M3 4h8v7H3zM13 4h8v7h-8zM3 13h8v7H3zM13 13h8v7h-8z',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'galleryCard' }).run(),
+  },
+  {
+    title: 'Embed', description: 'YouTube, Vimeo, Loom, iframe…', keywords: 'embed video youtube vimeo iframe audio',
+    group: 'Cards', icon: 'M4 5h16v14H4zM10 9.5l5 2.5-5 2.5z',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'embedCard' }).run(),
+  },
+  {
+    title: 'Bookmark', description: 'Rich link preview card', keywords: 'bookmark link preview url card', group: 'Cards',
+    icon: 'M6 3h12v18l-6-4-6 4z',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'bookmarkCard' }).run(),
+  },
+  {
+    title: 'File', description: 'Downloadable attachment', keywords: 'file download attachment pdf zip document', group: 'Cards',
+    icon: 'M13 3H6v18h12V8zM13 3v5h5M12 11v6M9.5 14.5L12 17l2.5-2.5',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'fileCard' }).run(),
+  },
+  {
+    title: 'Button', description: 'Call-to-action link', keywords: 'button cta link', group: 'Cards',
+    icon: 'M4 8h16v8H4zM8 12h8',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'buttonCard' }).run(),
+  },
+  {
+    title: 'Callout', description: 'Emphasized note with emoji', keywords: 'callout note info warning', group: 'Cards',
+    icon: 'M12 3l9 18H3zM12 10v4M12 17.5h0',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'callout' }).run(),
+  },
+  {
+    title: 'HTML', description: 'Raw HTML block', keywords: 'html code embed custom', group: 'Cards',
+    icon: 'M8 6l-5 6 5 6M16 6l5 6-5 6',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'htmlCard' }).run(),
+  },
+  {
+    title: 'Calendar', description: 'Google Calendar or ICS feed (dynamic)', keywords: 'calendar events google ics schedule month week upcoming dynamic', group: 'Cards',
+    icon: 'M3 5h18v16H3zM3 9h18M8 3v4M16 3v4M7 13h2M12 13h2M7 17h2M12 17h2',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'calendarCard' }).run(),
+  },
+  {
+    title: 'Info cards', description: 'Grid of cards: title, badge, details', keywords: 'info cards grid services hours schedule team features locations badge', group: 'Cards',
+    icon: 'M3 5h18v14H3zM7 9h6M15.5 9h2M7 13h7M7 16h5',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'infoCards' }).run(),
+  },
+  {
+    title: `${CONTENT.posts.singular} list`, description: `Latest, featured or by-tag ${CONTENT.posts.plural.toLowerCase()} (dynamic)`, keywords: `posts list latest featured tag dynamic blog ${CONTENT.posts.plural.toLowerCase()}`, group: 'Cards',
+    icon: 'M4 5h7v6H4zM4 14h7v6H4zM14 6h6M14 9h4M14 15h6M14 18h4',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).insertContent({ type: 'postListCard' }).run(),
+  },
+  {
+    title: 'Table', description: '3×3 table with header row', keywords: 'table grid rows columns cells', group: 'Basic',
+    icon: 'M3 5h18v14H3zM3 10h18M9 5v14M15 5v14',
+    run: (editor, range) =>
+      editor.chain().focus().deleteRange(range).insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run(),
+  },
+  {
+    title: 'Divider', description: 'Horizontal rule', keywords: 'divider hr rule separator', group: 'Basic',
+    icon: 'M3 12h18',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setHorizontalRule().run(),
+  },
+  {
+    title: 'Heading 2', description: 'Section heading', keywords: 'heading h2 title section', group: 'Basic',
+    icon: 'M4 5v14M14 5v14M4 12h10M18 15c0-1 2-1.6 2-3a1.8 1.8 0 0 0-3.4-.8',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setNode('heading', { level: 2 }).run(),
+  },
+  {
+    title: 'Heading 3', description: 'Subsection heading', keywords: 'heading h3 subtitle', group: 'Basic',
+    icon: 'M4 5v14M12 5v14M4 12h8M17 9.5a1.8 1.8 0 1 1 1.5 2.7 1.9 1.9 0 1 1-1.6 2.9',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setNode('heading', { level: 3 }).run(),
+  },
+  {
+    title: 'Quote', description: 'Blockquote', keywords: 'quote blockquote citation', group: 'Basic',
+    icon: 'M6 15c-1.5 0-2.5-1.2-2.5-2.8C3.5 9.5 5.5 7.5 8 7M6 15h2v3H5v-3zM15 15c-1.5 0-2.5-1.2-2.5-2.8 0-2.7 2-4.7 4.5-5.2M15 15h2v3h-3v-3z',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setBlockquote().run(),
+  },
+  {
+    title: 'Code block', description: 'Preformatted code', keywords: 'code pre snippet', group: 'Basic',
+    icon: 'M9 6l-5 6 5 6M15 6l5 6-5 6',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).setCodeBlock().run(),
+  },
+  {
+    title: 'Bullet list', description: 'Unordered list', keywords: 'list bullet ul', group: 'Basic',
+    icon: 'M9 6h12M9 12h12M9 18h12M4 6h.01M4 12h.01M4 18h.01',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleBulletList().run(),
+  },
+  {
+    title: 'Numbered list', description: 'Ordered list', keywords: 'list numbered ol ordered', group: 'Basic',
+    icon: 'M10 6h11M10 12h11M10 18h11M4 5l1.5-1v5M3.8 11.5a1.3 1.3 0 0 1 2.4.7c0 1-2.4 1.4-2.4 2.8h2.6',
+    run: (editor, range) => editor.chain().focus().deleteRange(range).toggleOrderedList().run(),
+  },
+];
+
+interface ListProps {
+  items: SlashItem[];
+  command: (item: SlashItem) => void;
+}
+
+export interface SlashListHandle {
+  onKeyDown: (e: KeyboardEvent) => boolean;
+}
+
+const SlashList = forwardRef<SlashListHandle, ListProps>(function SlashList({ items, command }, ref) {
+  const [selected, setSelected] = useState(0);
+  useEffect(() => setSelected(0), [items]);
+
+  useImperativeHandle(ref, () => ({
+    onKeyDown(e) {
+      if (e.key === 'ArrowDown') { setSelected((s) => (s + 1) % items.length); return true; }
+      if (e.key === 'ArrowUp') { setSelected((s) => (s - 1 + items.length) % items.length); return true; }
+      if (e.key === 'Enter') { if (items[selected]) command(items[selected]); return true; }
+      return false;
+    },
+  }));
+
+  if (!items.length) return <div className="pe-slash"><div className="pe-slash-empty">No matches</div></div>;
+
+  let lastGroup = '';
+  return (
+    <div className="pe-slash">
+      {items.map((item, i) => {
+        const header = item.group !== lastGroup ? item.group : null;
+        lastGroup = item.group;
+        return (
+          <div key={item.title}>
+            {header && <div className="pe-slash-group">{header}</div>}
+            <button
+              type="button"
+              className={`pe-slash-item ${i === selected ? 'is-selected' : ''}`}
+              onMouseEnter={() => setSelected(i)}
+              onMouseDown={(e) => { e.preventDefault(); command(item); }}
+            >
+              <span className="pe-slash-icon">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round">
+                  <path d={item.icon} />
+                </svg>
+              </span>
+              <span>
+                <span className="pe-slash-title">{item.title}</span>
+                <span className="pe-slash-desc">{item.description}</span>
+              </span>
+            </button>
+          </div>
+        );
+      })}
+    </div>
+  );
+});
+
+export const SlashMenu = Extension.create<{ context: SlashContext }>({
+  name: 'slashMenu',
+
+  addOptions() {
+    return { context: { openImagePicker: () => {} } };
+  },
+
+  addProseMirrorPlugins() {
+    const context = this.options.context;
+    return [
+      Suggestion({
+        editor: this.editor,
+        char: '/',
+        startOfLine: false,
+        command: ({ editor, range, props }: { editor: Editor; range: Range; props: SlashItem }) => {
+          props.run(editor, range, context);
+        },
+        items: ({ query }: { query: string }) => {
+          const q = query.toLowerCase();
+          return ITEMS.filter(
+            (i) => i.title.toLowerCase().includes(q) || i.keywords.includes(q)
+          );
+        },
+        render: () => {
+          let renderer: ReactRenderer<SlashListHandle, ListProps> | null = null;
+
+          const position = (clientRect?: (() => DOMRect | null) | null) => {
+            const rect = clientRect?.();
+            if (!rect || !renderer) return;
+            const el = renderer.element as HTMLElement;
+            el.style.position = 'fixed';
+            el.style.zIndex = '80';
+            el.style.left = `${Math.min(rect.left, window.innerWidth - 320)}px`;
+            const below = rect.bottom + 8;
+            if (below + 340 > window.innerHeight) {
+              el.style.top = 'auto';
+              el.style.bottom = `${window.innerHeight - rect.top + 8}px`;
+            } else {
+              el.style.top = `${below}px`;
+              el.style.bottom = 'auto';
+            }
+          };
+
+          return {
+            onStart: (props: any) => {
+              renderer = new ReactRenderer(SlashList, {
+                props: { items: props.items, command: props.command },
+                editor: props.editor,
+              });
+              document.body.appendChild(renderer.element);
+              position(props.clientRect);
+            },
+            onUpdate: (props: any) => {
+              renderer?.updateProps({ items: props.items, command: props.command });
+              position(props.clientRect);
+            },
+            onKeyDown: (props: any) => {
+              if (props.event.key === 'Escape') return true;
+              return renderer?.ref?.onKeyDown(props.event) ?? false;
+            },
+            onExit: () => {
+              renderer?.element.remove();
+              renderer?.destroy();
+              renderer = null;
+            },
+          };
+        },
+      }),
+    ];
+  },
+});

package/src/components/editor/extensions/tableTyping.ts

@@ -0,0 +1,63 @@
+import { Extension } from '@tiptap/react';
+
+// Typed markdown tables, Typora-style: write a header row, then a
+// | --- | --- | delimiter row, and press Enter — the two paragraphs convert
+// into a real table (header + one empty body row) with the cursor in the
+// first cell. Pasted markdown tables are handled separately in PostEditor.
+
+const ROW = /^\s*\|.+\|\s*$/;
+const DELIM = /^\s*\|(\s*:?-+:?\s*\|)+\s*$/;
+
+const splitRow = (line: string) =>
+  line.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+
+export const TableTyping = Extension.create({
+  name: 'tableTyping',
+  priority: 1000, // ahead of StarterKit's Enter (split block)
+
+  addKeyboardShortcuts() {
+    return {
+      Enter: () => {
+        const { state } = this.editor;
+        const { $from, empty } = state.selection;
+        if (!empty || $from.depth !== 1 || $from.parent.type.name !== 'paragraph') return false;
+        if ($from.parentOffset !== $from.parent.content.size) return false;
+        if (!DELIM.test($from.parent.textContent)) return false;
+
+        const index = $from.index(0);
+        if (index === 0) return false;
+        const header = state.doc.child(index - 1);
+        if (header.type.name !== 'paragraph' || !ROW.test(header.textContent)) return false;
+
+        const cells = splitRow(header.textContent);
+        if (cells.length < 2 || cells.length !== splitRow($from.parent.textContent).length) return false;
+
+        const to = $from.after(1);
+        const from = to - $from.parent.nodeSize - header.nodeSize;
+        // table(1) + header row(2 + Σ th(2 + p(2 + text))) + row(1) + cell(1) + p(1)
+        const firstBodyCellPos = from + cells.reduce((s, c) => s + 4 + c.length, 2) + 4;
+        this.editor
+          .chain()
+          .insertContentAt({ from, to }, {
+            type: 'table',
+            content: [
+              {
+                type: 'tableRow',
+                content: cells.map((text) => ({
+                  type: 'tableHeader',
+                  content: [{ type: 'paragraph', content: text ? [{ type: 'text', text }] : undefined }],
+                })),
+              },
+              {
+                type: 'tableRow',
+                content: cells.map(() => ({ type: 'tableCell', content: [{ type: 'paragraph' }] })),
+              },
+            ],
+          })
+          .setTextSelection(firstBodyCellPos)
+          .run();
+        return true;
+      },
+    };
+  },
+});

package/src/components/editor/imaging.ts

@@ -0,0 +1,146 @@
+// Client-side image pipeline: decode (EXIF-corrected), downscale to the
+// web cap, re-encode as WebP, generate smaller variants, upload everything
+// to /api/media/upload. Keeps image optimization free and backend-portable.
+
+import type { Media } from '../../lib/schema';
+
+// Everything stored is web-sized: longest edge capped at MAX_DIMENSION.
+export const MAX_DIMENSION = 1080;
+export const VARIANT_WIDTHS = [480, 720];
+export const DEFAULT_SIZES = '(max-width: 760px) 100vw, 720px';
+
+const WEBP_QUALITY = 0.82;
+const RETRY_QUALITY = 0.7;
+const TARGET_BYTES = 400 * 1024;
+
+export interface ProcessedImage {
+  file: File;
+  width: number;
+  height: number;
+  variants: { w: number; blob: Blob }[];
+}
+
+export async function processImage(file: File): Promise<ProcessedImage> {
+  // SVG/GIF pass through untouched (resizing would rasterize/break them)
+  if (file.type === 'image/svg+xml' || file.type === 'image/gif') {
+    const dims = await imageDims(file);
+    return { file, ...dims, variants: [] };
+  }
+  const bmp = await createImageBitmap(file, { imageOrientation: 'from-image' });
+
+  // Downscale so the longest edge is at most MAX_DIMENSION.
+  const scale = Math.min(1, MAX_DIMENSION / Math.max(bmp.width, bmp.height));
+  const width = Math.round(bmp.width * scale);
+  const height = Math.round(bmp.height * scale);
+
+  // Re-encode at the capped size; step quality down once if still heavy.
+  let blob = await encodeWebp(bmp, width, height, WEBP_QUALITY);
+  if (blob && blob.size > TARGET_BYTES) {
+    const retry = await encodeWebp(bmp, width, height, RETRY_QUALITY);
+    if (retry && retry.size < blob.size) blob = retry;
+  }
+
+  // Use the re-encode unless the untouched original is already smaller
+  // (e.g. a tiny, well-compressed image that needed no resizing).
+  let out = file;
+  if (blob && (scale < 1 || blob.size < file.size)) {
+    const base = file.name.replace(/\.[^.]*$/, '') || 'image';
+    out = new File([blob], `${base}.webp`, { type: 'image/webp' });
+  }
+
+  const variants: { w: number; blob: Blob }[] = [];
+  for (const w of VARIANT_WIDTHS) {
+    if (w >= width) continue;
+    const h = Math.round((height / width) * w);
+    const vblob = await encodeWebp(bmp, w, h, WEBP_QUALITY);
+    if (vblob) variants.push({ w, blob: vblob });
+  }
+  bmp.close();
+  return { file: out, width, height, variants };
+}
+
+function encodeWebp(bmp: ImageBitmap, w: number, h: number, quality: number): Promise<Blob | null> {
+  const canvas = document.createElement('canvas');
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext('2d')!;
+  ctx.imageSmoothingQuality = 'high';
+  ctx.drawImage(bmp, 0, 0, w, h);
+  return new Promise<Blob | null>((res) => canvas.toBlob(res, 'image/webp', quality));
+}
+
+function imageDims(file: File): Promise<{ width: number; height: number }> {
+  return new Promise((resolve, reject) => {
+    const url = URL.createObjectURL(file);
+    const img = new Image();
+    img.onload = () => {
+      resolve({ width: img.naturalWidth, height: img.naturalHeight });
+      URL.revokeObjectURL(url);
+    };
+    img.onerror = reject;
+    img.src = url;
+  });
+}
+
+export async function uploadImage(file: File, alt = ''): Promise<Media> {
+  const processed = await processImage(file);
+  const form = new FormData();
+  form.set('file', processed.file);
+  form.set('width', String(processed.width));
+  form.set('height', String(processed.height));
+  form.set('alt', alt);
+  for (const v of processed.variants) {
+    form.set(`variant_${v.w}`, new File([v.blob], `w${v.w}.webp`, { type: 'image/webp' }));
+  }
+  const res = await fetch('/api/media/upload', { method: 'POST', body: form });
+  if (!res.ok) {
+    const data = (await res.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(data?.error ?? `Upload failed (${res.status})`);
+  }
+  return ((await res.json()) as { media: Media }).media;
+}
+
+// Non-image upload (documents for the file card): no client-side processing,
+// the file goes up as-is and the server validates the type.
+export async function uploadFile(file: File): Promise<Media> {
+  const form = new FormData();
+  form.set('file', file);
+  form.set('width', '0');
+  form.set('height', '0');
+  const res = await fetch('/api/media/upload', { method: 'POST', body: form });
+  if (!res.ok) {
+    const data = (await res.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(data?.error ?? `Upload failed (${res.status})`);
+  }
+  return ((await res.json()) as { media: Media }).media;
+}
+
+export function mediaUrl(key: string): string {
+  return `/media/${key}`;
+}
+
+export function mediaSrc(media: Media): string {
+  const largest = media.variants[media.variants.length - 1];
+  return mediaUrl(largest ? largest.key : media.key);
+}
+
+export function mediaSrcset(media: Media): string {
+  if (!media.variants.length) return '';
+  const parts = media.variants.map((v) => `${mediaUrl(v.key)} ${v.w}w`);
+  if (media.width > media.variants[media.variants.length - 1].w) {
+    parts.push(`${mediaUrl(media.key)} ${media.width}w`);
+  }
+  return parts.join(', ');
+}
+
+export function mediaThumb(media: Media): string {
+  return mediaUrl(media.variants[0]?.key ?? media.key);
+}
+
+// Unsplash photos are hotlinked (per API guidelines) with dynamic resizing.
+export function unsplashSrcset(regular: string): string {
+  const base = regular.replace(/([&?])w=\d+/, `$1w=${MAX_DIMENSION}`);
+  return [...VARIANT_WIDTHS, MAX_DIMENSION]
+    .map((w) => `${base.replace(/([&?])w=\d+/, `$1w=${w}`)} ${w}w`)
+    .join(', ');
+}