Skip to the content.

Site media manifest and import

The site’s own images, videos and PDFs stay in core/web/public/{i,v,d}, tracked in git, and are served at their own paths (/i/…, /v/…, /d/…, the Nuxt public dir). core/web/content/media.json is the reviewed metadata for them: one entry per file, with a fixed id, a human name and the owner’s title and alt text. The media catalog (SQLite + filesystem locally, DynamoDB + S3 in production) is for new and admin media, not for these files.

This page covers part 1 (PR 5): the metadata policy, the sanitizer, the manifest and the import CLI, and part 2a: rendering reads the manifest for metadata only. Part 2b added admin title / alt editing and rename, turned enforceMetaPolicy on by default and sends admin uploads through the sanitizer (media.md, admin.md). None of that touches site media: admin edits and renames work on catalog assets, and the site’s files are not in the catalog, so their paths, titles and alt text change only in public/{i,v,d} and media.json.

Owner decision 2026-10-17. Site media is not moved into the catalog: no /m/ URLs for it, no 301s from the public paths, and no site import before a deploy. CD keeps uploading public/{i,v,d} through the typed sync for good (cicd.md). The labs stay at /d/htm/…, and scripts/enrich-image-meta.mjs stays in use for content LQIPs and aspect ratios.

Intentional case-study paths (do not flag)

The tesseract images in two case studies use /i/portfolio/tesseract/… paths on purpose (owner decision, #279), although the files live at core/web/public/i/tesseract/:

The owner confirmed these paths on 2026-10-14 without a visual check. The Docker test stack (http://localhost:4300) serves no static files at all (/_nuxt/*, /i/* and /_ipx/* return 404 or 502; tracked in Phase 9b of docs/superpowers/plans/2026-10-01-prod-readiness-docker-media.md), and the deployed test environment predated #279 at the time. (Since 2026-10-19 the docker:test cdn stand-in serves public/, including /_ipx/*: docker/README.md.)

Other content still points at /i/tesseract/… (for example the spatial-experiences.json video poster, gallery.json, content/media.json legacyPath and shared/tesseract.ts). That mix is intentional as well. Don’t “align” the two prefixes in either direction.

Do not move the files, rewrite the paths, restore the file-exists checks that #279 removed from core/web/tests/portfolio-content.spec.ts and core/web/tests/work-card-media.spec.ts, or report the paths (or the mixed prefixes) as broken or inconsistent. core/web/tests/tesseract-media-paths.spec.ts keeps the paths and this note in place.

Case-study diagrams show whole

Case-study media is framed at the theme’s --media-ratio with object-fit: cover (core/web/app/pages/work/case-study.scss). On portrait screens that ratio is 9:16, which is right for photos and video but cut a 16:9 flow diagram to its middle third on a 375px phone. AppCaseStudyMedia marks SVG diagrams ("type": "diagram", which must be an SVG, or any SVG src) with data-media-kind="diagram"; the hero and the Artifacts grid show those at the file’s own ratio (aspect-ratio: auto 16 / 9, the 16:9 reserved until the file loads) with object-fit: contain. Photos and video keep the frame and the crop. Fixed 2026-10-19; core/web/tests/case-study-diagrams.spec.ts keeps it (and checks that every SVG in content/case-studies is typed diagram and every diagram is an SVG). Old styles: theme/core/scss/_archive/2026-10-19-case-study-diagrams/.

Manifest

{
  "version": 1,
  "entries": [
    {
      "id": "…uuid…",
      "tenant": "portfolio",
      "kind": "image",
      "name": "profile-pic-1",
      "ext": "jpg",
      "path": "m/pf/i/profile-pic-1.jpg",
      "title": "Tamara Mack portrait",
      "alt": "Portrait of Tamara Mack smiling, …",
      "description": null,
      "credit": "Tamara Mack",
      "sha256": "…of the sanitized bytes…",
      "width": 1024,
      "height": 1024,
      "durationSec": null,
      "lqip": "data:image/webp;base64,…",
      "dominantColor": "#cece9f",
      "variants": [],
      "legacyPath": "/i/profile_pic_1.jpg",
      "reviewNotes": ["check: …"]
    }
  ]
}
Field Rule
id UUIDv5 of legacyPath (siteMediaId). Stable across reruns and identical in every backend. Never edit it once imported.
name, ext, path normalizeMediaFilename of the original filename (generator and camera prefixes dropped), -2, -3 on collisions; path is m/pf/{kind code}/{name}.{ext}.
title, alt, description, credit Owner-reviewed text, checked by validateMediaMeta (title 3–80 characters, alt ≤150 and required for images and SVGs, description ≤300, no filenames or vendor ids).
sha256, width, height, durationSec Computed from the sanitized bytes. Don’t edit by hand.
lqip, dominantColor Computed for images and SVGs (ingestImage). null for video and documents.
variants Ready catalog variants (t, 640, 1280, 1920) for srcset. Empty until they are materialized; --from exports fill it.
legacyPath The file’s public path, as content references it. Must start with /; . / .. segments and backslashes are rejected (the import reads <source><legacyPath>).
reviewNotes Draft checklist. The import refuses entries that still have notes; notes are never imported.

Types and the validator live in @tgmc/media (SiteMediaEntry, validateSiteManifest, serializeSiteManifest). The validator is strict: unknown keys, a path that does not match kind / name / ext, an ext whose type does not belong to kind (image + .pdf), duplicate ids, names or legacy paths are structural errors; metadata policy issues are reported separately so a draft can still be written.

Review workflow

npm run build:libs
npm run media:site-manifest -- --draft --review-out tmp/site-media-review.md

--draft reads every file under the source (--source <dir>, default data/media-source/ when it exists, else core/web/public; folders starting with . or _ are skipped, non-media files such as the HTML labs are listed under skipped, and files the overrides exclude under excluded). For each file it:

  1. Detects the real format from the bytes (a .png that is really an animated GIF becomes .gif).
  2. Pre-fills the title (gallery item title, then the SVG <title>, then the filename), alt (the longest content alt that fits) and description (the longest caption that fits, else the SVG <desc>), from every content JSON file under core/web/content/ (except media.json itself, and --out) and quoted paths in core/web/{app,shared,server}.
  3. Sanitizes the bytes (sanitizer), then records the sha256, dimensions, duration and LQIP.
  4. Adds notes: check: (an owner decision: generated title, several content alts, a borrowed gallery title, a changed extension, a renamed collision, a generated-media credit), unused: (nothing references the file), duplicate: (same sanitized bytes as another file) and invalid: (fails the metadata policy).

--review-out writes a Markdown table with each entry’s legacy and new path, title, alt, description, credit and review notes, so every field the owner signs off on is visible in one place.

The owner edits media.json directly: fix titles, alt text, descriptions and credits, delete each note once resolved, then rerun --draft. A rerun keeps each existing entry’s id, name, editorial fields, variants and the owner’s remaining check: notes, and recomputes the bytes, dimensions, LQIP and the automatic unused: / duplicate: / invalid: notes. kind and ext always follow the sniffed bytes: when a source changes format (say the animated GIF named .png is replaced by a real PNG), the entry moves to the new extension (and kind code), its variants are reset, a name already taken in the new kind gets -2, and a check: format changed: … note asks for review. Its summary lists changed (sha256 differs from the committed manifest) and dropped (no longer in the source).

PDFs embed the title, credit (Author) and description (Subject) in the sanitized file, so editing a PDF’s title changes its sha256: rerun --draft before importing.

Overrides

Decisions a rerun must not undo live in core/web/site-media.overrides.json (committed; outside content/ so it is never scanned as content; --overrides <file> points elsewhere):

{
  "exclude": { "/i/portfolio/social-card.png": "why it is not imported" },
  "entries": {
    "/d/Resume2026.pdf": { "name": "Tamara Mack-resume-2026" },
    "/v/portfolio/generated/vimg-tesseract-framework.mp4": { "credit": "Tamara Mack (AI-assisted)" }
  }
}

Unknown keys are errors; overrides for paths that are not in the source are listed under staleOverrides. Titles, alt text and descriptions are edited in media.json itself (a rerun keeps them).

npm run media:site-manifest -- --from <endpoint> exports the manifest back from a catalog (assets tagged site), including ready variants. Endpoints are media:transfer’s sqlite:<dir> or aws:<table>@<bucket> with --region, --dynamodb-endpoint, --s3-endpoint, --path-style. postgres: is refused (the site CLIs have no --blobs); to seed a Postgres catalog, import into sqlite: and media:transfer from there.

Rendering: metadata only (part 2a)

Content and code keep referencing site media by its public path, exactly as before ("src": "/i/portfolio/manhattan-2150-keyframe.png"); UiImage and Nuxt Image (IPX, sizes → srcset) are unchanged. The manifest’s path (m/pf/…) is only the catalog key the optional import writes; the site never requests it. The manifest adds metadata:

Content guard

core/web/tests/site-media-guard.spec.ts scans core/web/content (JSON, Markdown, YAML), core/web/app (Vue, TS, SCSS), core/web/assets (SCSS), core/web/shared and core/web/server (TS), the Nuxt layers web extends (packages/nuxt-layer-base app / scss / src and packages/nuxt-layer-ui app / src, plus both nuxt.config.ts) and core/web/nuxt.config.ts (not media.json or the client map). Every /i/…, /v/… or /d/… path it finds, after a quote, bracket, =, ,, :, } (as in `${base}/i/x.png`) or whitespace, must be a manifest legacyPath, so every site file on the page has reviewed metadata. A self-test pins what the pattern catches and that an unknown path is flagged.

Allowlist (permanent):

Path Why
/i/tesseract/…, /i/portfolio/tesseract/… Intentional case-study paths (owner, #279)
/d/htm/adv_wire_tess.html, /d/htm/wire_tess.html HTML labs (pages, not media), served from public/d/htm/

A new site image: add the file under public/, rerun npm run media:site-manifest -- --draft, review its title and alt in media.json, then reference its public path.

Import

The import is optional tooling: it copies the site’s media into a catalog (for example to try admin features against real files). The site never reads site media from the catalog, so no environment needs it, and it is not a deploy prerequisite.

# rehearsal against a scratch catalog (imports entries that still have notes)
npm run media:site-import -- --to sqlite:./data/site-media-rehearsal --allow-unreviewed
# production, after the review
npm run media:site-import -- --to aws:<table>@<bucket> --dry-run
npm run media:site-import -- --to aws:<table>@<bucket>

For each entry the import checks that <source><legacyPath> exists and is media, then (importSiteMedia in @tgmc/media):

It prints a JSON report (copied, skipped, conflicts, conflictReasons, failed, refused) and exits 1 when anything was refused, conflicted or failed, 2 on bad arguments. A dry run opens a sqlite: target read-only and writes nothing.

The import is create-only, not a sync. Once an entry is imported, editing its title, alt text, description or credit in media.json and re-importing does not update the catalog: the entry is skipped (same id, path and sha256), or for a PDF, whose sanitized bytes embed the title and credit, reported as a conflict. Admin’s Details and Rename… can edit the imported copies, but they change only the catalog; the site keeps serving public/{i,v,d} with the metadata in media.json. --from exports the catalog back into media.json when the two should be brought in step.

Production import runbook

Only if a production catalog should hold the site’s media; nothing on the site depends on it.

  1. Run it on the machine and OS that produced the committed draft (Windows today), with the same ffmpeg (ffmpeg -version, or pin FFMPEG_PATH) and the same node_modules — sanitized bytes, and so every sha256, depend on them.
  2. npm run build:libs, then npm run media:site-import -- --to aws:<table>@<bucket> --dry-run. Expect failed: [], conflicts: [] and refused: [] (any refused entry still has review notes).
  3. Only then run the same command without --dry-run, and keep the JSON report.

Tooling notes

Resized images on the CDN

On AWS the Lambda serves no public/ files (serveStatic: false) and so cannot resize them either. A site-root path in the HTML went API Gateway → Lambda, and server/middleware/cdn.ts answered with a 302 to CloudFront: about 0.16 s per image before the download, and 1.8–2.6 s for the case-study SVG diagrams. Resized images (/_ipx/…) were worse: nothing generated them, so CloudFront returned 403. With a CDN on an aws_lambda build (NUXT_APP_CDN_URL at build time, which CD sets), site media now goes to the CDN directly:

Media URL in the HTML Comes from
Rasters (UiImage → NuxtImg) <cdn>/_ipx/w_<ladder width>/<path> public/_ipx/, written at build time
Rasters asked for as WebP (format="webp") <cdn>/_ipx/w_<ladder width>&f_webp/<path>.webp public/_ipx/, written at build time
SVG diagrams (UiSvgImg), videos and posters <cdn>/<path> (usePublicAssetUrl) public/ as is

Responsive sizes and format

UiImage has two modes.

$img comes from @nuxt/image’s image: { inject: true }, set on both image configs in core/web/nuxt.config.ts; the layer does not depend on @nuxt/image. Without it (an app without inject, such as core/admin today) widths is ignored and NuxtImg renders the image with its own srcset; the native sizes is then not passed on, since NuxtImg’s syntax cannot read it. Loading (lazy by default), decoding and the fade-in behave the same in both modes: the plain <img> fades in on load, and, like NuxtImg, an image that finished before hydration is marked loaded on mount unless the server-side onerror marker says it failed.

The /about portrait (app/pages/about.vue, values in shared/about-portrait.ts) is the first widths user. Its box is the sidebar’s content width (pages/about.scss and the theme’s split layout): the sidebar column (14 / 16 / 18rem from 48em / 90em / 120em) minus its padding (2 × 1.1rem) and border (2 × 1 px), and below 48em the viewport minus the page pad and the same padding. From 120em the root font is 125%, so those rems count × 1.25. In sizes, em and rem are the reader’s default font size, as in media queries, so the slot follows their text size like the layout does:

(min-width: 120em) calc(19.75rem - 2px), (min-width: 90em) calc(13.8rem - 2px),
(min-width: 48em) calc(11.8rem - 2px), (min-width: 30em) calc(100vw - 4.7rem - 2px),
calc(100vw - 4.2rem - 2px)

tests/about-page.spec.ts evaluates the string against boxes measured on a production build at a 16 px and a 20 px default. widths is [320, 480, 640, 960, 1024] (1024 is the source) and the format is WebP. The portrait stays lazy with no fetchpriority or preload: the owner’s decision is that it is not the page’s priority. Measured on .output/local (3 cold runs each; the 20 px default set through Chromium’s Page.setFontSizes):

Viewport Before (JPEG, px sizes) After (WebP, native sizes)
375 × 812, DPR 3 960 px JPEG, 93.8 KB; LCP (portrait) 2.0–2.5 s 960 px WebP, 55.0 KB; LCP (portrait) 1.2–1.5 s
375 × 812, DPR 2 960 px JPEG 640 px WebP, 30.0 KB; LCP (portrait) 1.3 s
1280 × 800, DPR 1 480 px JPEG, 30.5 KB (LCP is the h1) 320 px WebP, 10.7 KB (LCP is the h1)
800 × 900, 20 px default 704 px box; a px sizes would ask for 187 px 960 px WebP, 55.0 KB (not upscaled)
1280 × 800, 20 px default 234 px box 320 px WebP, 10.7 KB
375 × 812, DPR 3, 20 px def. 289 px box 960 px WebP, 55.0 KB

Case studies (/work/[slug], app/components/AppCaseStudyMedia.vue, values in shared/case-study-media.ts) are the second widths user. The page passes a native sizes to AppCaseStudyMedia: CASE_STUDY_HERO_SIZES for the hero and caseStudyArtifactSizes(count) for the Artifacts cells. For a raster in content/media.json, caseStudyRasterLadder(src) turns that into widths (each IPX_VARIANT_WIDTHS rung below the source, then the source width, at most the largest rung), the source’s own width / height (so no candidate is cropped to another ratio; the frame already has the file’s aspectCss) and format="webp" unless the source is WebP. SVG diagrams, video, a call without sizes and a raster outside the manifest render as before: the manifest is the list the CDN build writes variants for, so an unlisted raster (today the intentional /i/portfolio/tesseract/… paths) keeps the default NuxtImg srcset rather than linking variants that do not exist. Loading is unchanged: the hero stays eager with no fetchpriority or preload, the Artifacts stay lazy.

The boxes come from pages/work/case-study.scss, layouts/site.scss and the theme’s prose / split layout. The body column is --prose-max (42rem) once there is room; before that it is the viewport minus the site padding (0.5rem below 48em, 0.75rem to 67.5em), the page pad (0.5rem below 30em, 0.75rem to 48em, then clamp(0.75rem, 0.5rem + 2vw, 1.5rem)) and, from 48em, the 14rem page nav and its 2rem gap. From 120em the root font is 125%, so 42rem counts as 52.5rem. An Artifacts cell is the section’s content box (body − 2 × 1.5rem padding − 2 × 1 px border), halved with the 1 px gap once both columns can be 16rem; a lone artifact spans the grid (auto-fit drops the empty column), hence the separate single-cell string:

hero:     (min-width: 120em) 52.5rem, (min-width: 62.5em) 42rem, (min-width: 50em) calc(100vw - 20.5rem),
          (min-width: 48em) calc(96vw - 18.5rem), (min-width: 44.5em) 42rem,
          (min-width: 30em) calc(100vw - 2.5rem), calc(100vw - 2rem)
artifact: (min-width: 120em) calc(24.375rem - 1.5px), (min-width: 62.5em) calc(19.5rem - 1.5px),
          (min-width: 55.75em) calc(50vw - 11.75rem - 1.5px), (min-width: 50em) calc(100vw - 23.5rem - 2px),
          (min-width: 48em) calc(96vw - 21.5rem - 2px), (min-width: 44.5em) calc(19.5rem - 1.5px),
          (min-width: 37.75em) calc(50vw - 2.75rem - 1.5px), (min-width: 30em) calc(100vw - 5.5rem - 2px),
          calc(100vw - 5rem - 2px)
single:   the artifact string without the halving (39rem / 48.75rem - 2px at the wide end)

tests/case-study-media-sizes.spec.ts evaluates the three strings against boxes measured on a production build at 320–2560 px and a 16 px and a 20 px default, and checks that every candidate of every case-study raster is a variant the CDN build writes (cdnIpx snaps the source width up to the next rung, whose file is the source size, never enlarged). tests/case-study-media-component.spec.ts covers the rendering (raster, WebP source, unlisted raster, SVG, loading). Measured on .output/local (the innovation-prototyping hero, manhattan-2150-keyframe.png, 1672 × 941; 3 cold runs each):

Viewport Hero before (1× / 2× PNG) Hero after (WebP, native sizes) Artifacts on the page, before → after
375 × 812, DPR 3 2880 px asked, 1672 px PNG, 3,467 KB 1280 px WebP, 127 KB (343 px box) 4,329 KB → 375 KB
375 × 812, DPR 2 2880 px asked, 1672 px PNG, 3,467 KB 960 px WebP, 76 KB 4,329 KB → 194 KB
1280 × 800, DPR 1 1440 px PNG, 2,610 KB (672 px box) 960 px WebP, 76 KB 1,557 KB → 58 KB
800 × 900, 20 px default 1440 px PNG, 2,610 KB (750 px box) 960 px WebP, 76 KB 1,557 KB → 118 KB

The LCP element of that page is text (the lead paragraph or the h1, 0.38–0.50 s before and after): the hero fades in from opacity: 0, which Chromium does not count. On data-visualization (one WebP artifact) at a 1280 × 800 viewport the LCP is the artifact; its file went from 109 KB (960 px) to 57 KB (640 px) and the LCP stayed within run-to-run noise (1.3–1.6 s, dominated by the local ipx resizing each cold request). Screenshots at DPR 3 show the hero sharp. Before, the local ipx also cropped every Artifacts candidate to 16:9 (width="960" height="540"), including the 1:1 vimg-crystal-volume.webp; the ladder now keeps the source ratio, as the CDN variants always did.

WebP needs no JPEG fallback in the browsers the site supports (Safari 14+). AVIF would be about 44% smaller again (960 px: 30.9 KB) but needs a <picture> with a fallback, so it is a TODO. The local ipx handler answers max-age=60 (its default), which only applies to local / development builds. On AWS the variants are S3 objects with the one-hour revalidated cache (the repo policy for unversioned files). Neither is changed.

Media slots and placeholders

Pages that had no imagery get media slots: named places for a picture or video, listed in core/web/content/media-slots.json and read through #shared/media-slots. Until the real asset exists, a slot renders a labelled placeholder, so the layout is final before the art is.

{
  "version": 1,
  "slots": {
    "case-study.walkthrough": {
      "kind": "video",
      "src": null,
      "poster": null,
      "alt": "Placeholder: screen-recorded walkthrough of this case study",
      "ratio": "16 / 9",
      "caption": "Walkthrough video coming soon."
    }
  }
}

Fallbacks when media is missing

When a file is missing or fails to load in a media slot or on a case study, the page shows a labelled stand-in instead, built by AppMediaFallback (core/web/app/components/AppMediaFallback.vue; props kind, alt, ratio default 16 / 9, poster). Its root is always its own [data-media-fallback="<kind>"] element. Its poster / placeholder box (.media-fallback__box) keeps ratio, unless a caller frames the root with its own aspect-ratio; the box then fills that frame.

Tests:

Library media on public pages

A page can reference a library asset by id (never by URL or key). The server resolves the id at render time.

Resolution and cache

core/web/server/utils/media-refs.ts resolves ids for a render: resolveMediaRefs(ids) answers a map with every id, null when the id does not resolve. createMediaRefResolver is the same resolver with its library, storage and clock injected (tests).

Tests: core/web/tests/server/utils/media-refs.spec.ts (a real library on in-memory SQLite) and packages/media-nuxt/tests/media-asset-events.spec.ts (the event and the four emitting routes).

Usage list writes

A post or slot write keeps the library’s usage list (which published pages use each asset) up to date, so a delete can’t silently take media off a page. The code is core/web/server/utils/media-usage-sync.ts. The posts service (createBlogPostFromBody, updateBlogPostFromBody, deleteBlogPostById) runs it when it is given a sync, and without one it writes no usage.

Tests: core/web/tests/server/utils/media-usage-sync.spec.ts, core/web/tests/server/api/posts/posts-service.spec.ts (usage sync), core/web/tests/server/api/blog-posts-routes.spec.ts (the web routes and their auth table), core/web/tests/server/api/media-slots-admin-routes.spec.ts and core/web/tests/server/utils/media-slot-write.spec.ts (slot writes and the rebuild), core/admin/tests/admin-blog-usage.spec.ts, core/admin/tests/admin-blog-forward.spec.ts and core/admin/tests/admin-slots-routes.spec.ts (forward mode sends the writes to these routes), core/web/tests/server/plugins/media-usage-wait.spec.ts (the Lambda wait), and the store contract (create keeps a given id).

Blog covers and embeds

A post’s cover and the media in its body come from the library. GET /api/posts/:slug resolves them on the server (core/web/server/utils/blog-post-media.ts) and answers { ...post, html, cover, segments } with Cache-Control: public, max-age=0, must-revalidate. The cover id and the body’s block ids resolve in one resolveMediaRefs call, next to getMediaSlotViews(). Neither throws: with the catalog down the cover falls back and every media segment has ref: null, and the post still answers 200. html (the whole body as sanitized html) stays for the github.io export and older clients; in it a block reference renders as the unavailable text, like an inline one.

Tests: core/web/tests/server/utils/blog-post-media.spec.ts (precedence, segments, the route), core/web/tests/server/utils/render-blog-markdown.spec.ts (inline images), core/web/tests/server/utils/media-refs.spec.ts (the srcset without variants), core/web/tests/blog-post-page-component.spec.ts (the page with a cover, segments and a fallback; a library image without variants renders a plain img with its direct URL, never /_ipx/; an svg cover renders a direct img; body and cover sizes are native).

Related: @tgmc/media, @tgmc/image sanitizer, promote media to production.