@homepages/dev-media 0.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+HomePages Dev Media License
+
+Copyright (c) 2026 HomePages
+
+This package ("@homepages/dev-media") ships two kinds of bytes under `assets/`:
+
+1. Real property photography and floor plans, owned by HomePages. Each
+   included asset's source is cleared for public redistribution per
+   `selection.json`'s `cleared` block, reviewed and recorded by the
+   repository owner. HomePages grants anyone who obtains this package a
+   worldwide, royalty-free, non-exclusive license to use, copy, modify, and
+   redistribute these assets, including as part of a derived build, solely
+   for developing, testing, and demonstrating HomePages templates. This
+   license does not grant any trademark right, and does not extend to any
+   asset not shipped in this package (including any excluded, unlicensed
+   source held in the HomePages dev environment).
+
+2. Procedurally generated placeholder images and video, produced by this
+   package's own generator (`scripts/generate-placeholders.mjs`) from no
+   external input. These contain no third-party or model-generated content
+   and are provided under the same terms as (1), without restriction.
+
+THE ASSETS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL HOMEPAGES BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM THEIR USE.

package/README.md

@@ -0,0 +1,91 @@
+# @homepages/dev-media
+
+The dev-only media pack template authoring resolves against: `manifest.json` indexing
+every asset the fixture corpus can select, plus the bytes in `assets/`.
+
+Allowlisted to publish, though it has not yet had its first `npm publish`. It
+is a package rather than a `@homepages/template-kit` subpath because the kit
+is a dependency of every workspace and CI install, and media bytes would tax
+all of them.
+
+## What is in here
+
+| path | role |
+|---|---|
+| `manifest.json` | generated pack index — assets + named media sets |
+| `selection.json` | reviewed slot → source mapping, with per-asset provenance and rights |
+| `assets/` | the bytes, `assets/<kind>/<slug>.<ext>` |
+| `vendor/` | byte-vendored copies of the derived contract; never hand-edit |
+| `scripts/` | the importer, generators, and the pack validator |
+
+Ids are namespaced per id space (`dev_upl_`, `dev_efp_`, `dev_lib_`, `dev_vid_`) so a
+dev id is impossible to mistake for a real one if it ever reaches a real `content_doc`.
+
+`tags` are a contract, not decoration: fixtures select by tag and throw when a value
+has no match, which is why `check` asserts the full tag vocabulary is covered.
+
+## Two kinds of bytes
+
+Most slots hold **real property media** imported from the dev environment; the rest hold
+**generated placeholders** — a labelled frame at the asset's true dimensions.
+
+`selection.json` decides which is which. It maps a brief slot to a source object in the
+dev uploads bucket and records that source's provenance and rights clearance. It is
+committed and reviewed by a human: querying the dev database at build time would let the
+pack's contents shift whenever that database changed, silently, with no version
+recording it. Reviewed once, the pack regenerates byte-identically from S3 forever.
+
+A slot with no entry falls back to its placeholder. That is a permanent state for some
+slots and a temporary one for others:
+
+- `sparseSingleFamily` keeps placeholders **by design** — it exercises the corpus's
+  missing-content branches, where a labelled frame is the honest representation.
+- The library logos and headshots depict fictional brands and fictional people, so no
+  source could supply them.
+- A handful of photo slots (gym, patio, balcony) have no matching content in the dev
+  environment yet and fill automatically once it exists.
+
+Imported bytes are the platform's existing 2048px `image_web_variant` derivatives,
+copied verbatim. No re-encoding: the derivatives already match the brief's width, and an
+encoder here would drift against the platform's own ladder.
+
+**Rights are enforced, not just recorded.** The importer refuses to fetch any selection
+whose provenance is not listed in the file's `cleared` block, so adding a source without
+clearing it fails the import rather than shipping quietly.
+
+`npm run check` reports the real-vs-placeholder split explicitly. Coverage alone cannot:
+it is asserted against the inventory rather than against a source, so an import that
+silently resolved nothing would still come out green.
+
+## Commands
+
+```
+npm run check           # validate: schema, inventory coverage, files resolve, true dimensions
+npm run import          # fetch the selected sources from S3 (needs dev AWS credentials)
+npm run generate        # regenerate placeholders + manifest, prune superseded files
+npm run generate:videos # also re-encode the two MP4s — needs Docker (no ffmpeg on the dev host)
+```
+
+Re-authoring the selection (needs the dev Postgres container) is a deliberate,
+hand-run step — never part of the build:
+
+```
+node scripts/derive-selection.mjs > selection.proposed.json   # review, clear rights, commit
+```
+
+## Dimensions and the responsive ladder
+
+Production emits rungs `[320,640,960,1200,1600,2048]` across avif/webp/jpeg. The dev
+server instead serves the source file at every rung URL while the manifest declares
+each rung's true size, so the emitted `srcset` is structurally identical to production
+and every URL resolves. The only divergence is transferred bytes — a performance
+property, not a layout or authoring one. This is why a manifest that lies about
+intrinsic dimensions is a real defect and `check` fails on it.
+
+The brief's `min_width` is a separate thing from the declared dimensions: it states the
+ladder ceiling the corpus binds a slot at, while the manifest states what the bytes
+actually are. Every imported floor plan is narrower than the 1024px the brief asks for —
+the dev environment's extracted plans run 341–876px — so their top rung upscales. This
+is an accepted gap, not a defect: floor plans are line art and read acceptably upscaled,
+and the alternative was leaving every plan slot synthetic. `check` prints one
+`under-floor` warning per affected asset so the gap stays visible.

package/assets/library/bluebird_logo_dark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 120" role="img" aria-label="Bluebird Realty Group">
+  <rect width="480" height="120" fill="#22262c"/>
+  <circle cx="60" cy="60" r="28" fill="none" stroke="#f4f6f8" stroke-width="6"/>
+  <text x="108" y="70" font-family="Helvetica, Arial, sans-serif" font-size="26" fill="#f4f6f8">Bluebird Realty Group</text>
+</svg>

package/assets/library/bluebird_logo_light.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 120" role="img" aria-label="Bluebird Realty Group">
+  <rect width="480" height="120" fill="#f4f6f8"/>
+  <circle cx="60" cy="60" r="28" fill="none" stroke="#22262c" stroke-width="6"/>
+  <text x="108" y="70" font-family="Helvetica, Arial, sans-serif" font-size="26" fill="#22262c">Bluebird Realty Group</text>
+</svg>

package/assets/library/okane_logo_dark.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 120" role="img" aria-label="Okane Marketing">
+  <rect width="480" height="120" fill="#22262c"/>
+  <circle cx="60" cy="60" r="28" fill="none" stroke="#f4f6f8" stroke-width="6"/>
+  <text x="108" y="70" font-family="Helvetica, Arial, sans-serif" font-size="26" fill="#f4f6f8">Okane Marketing</text>
+</svg>

package/assets/library/okane_logo_light.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 120" role="img" aria-label="Okane Marketing">
+  <rect width="480" height="120" fill="#f4f6f8"/>
+  <circle cx="60" cy="60" r="28" fill="none" stroke="#22262c" stroke-width="6"/>
+  <text x="108" y="70" font-family="Helvetica, Arial, sans-serif" font-size="26" fill="#22262c">Okane Marketing</text>
+</svg>

package/index.d.ts

@@ -0,0 +1,34 @@
+/** The four library kinds the editor's media picker lists. */
+export type MediaKind = "photo" | "plan" | "library" | "video";
+
+export interface MediaAsset {
+  /** Namespaced dev id (`dev_upl_`/`dev_efp_`/`dev_lib_`/`dev_vid_`). */
+  id: string;
+  kind: MediaKind;
+  /** Picker tile label — a display name, not a filename. */
+  name: string;
+  caption: string;
+  /** The selection contract: fixtures select by tag and throw when a value is absent. */
+  tags: Record<string, string>;
+  /** Pack-relative path to the source bytes. */
+  file: string;
+  /** True intrinsic dimensions of `file`. Absent for vector assets. */
+  width?: number;
+  height?: number;
+  /** `video` only. */
+  poster?: string;
+  duration_ms?: number;
+}
+
+export interface MediaManifest {
+  version: 1;
+  license?: { spdx: string; source: string; notes?: string };
+  assets: MediaAsset[];
+  /** Named media sets keyed to the kit's fixture scenarios. */
+  sets: Record<string, Partial<Record<MediaKind, string[]>>>;
+}
+
+export declare const manifest: MediaManifest;
+export declare function getAsset(id: string): MediaAsset | null;
+export declare function listByKind(kind: MediaKind): MediaAsset[];
+export declare function resolveAssetPath(packRelative: string): string;

package/index.js

@@ -0,0 +1,29 @@
+// Buildless on purpose: the package is data, and a compile step over a JSON index
+// would only add a way for the shipped manifest to differ from the checked-in one.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const PACK_ROOT = new URL("./", import.meta.url);
+
+/** The pack index. Generated from the derived inventory — see scripts/generate-manifest.mjs. */
+export const manifest = JSON.parse(readFileSync(new URL("manifest.json", PACK_ROOT), "utf8"));
+
+const BY_ID = new Map(manifest.assets.map((asset) => [asset.id, asset]));
+
+export function getAsset(id) {
+  return BY_ID.get(id) ?? null;
+}
+
+export function listByKind(kind) {
+  return manifest.assets.filter((asset) => asset.kind === kind);
+}
+
+/**
+ * Absolute path for a pack-relative reference (an asset's `file` or `poster`).
+ * Callers hand these to a static file server or read them directly; the pack never
+ * assumes a URL scheme, because the dev server owns that mapping.
+ */
+export function resolveAssetPath(packRelative) {
+  return fileURLToPath(new URL(packRelative, PACK_ROOT));
+}