create-portfoliable 1.2.11 → 1.2.13

package/cli/portfoliable.mjs

@@ -26,6 +26,7 @@ import {
   isInteractiveTerminal,
   readProjectUiPreferences
 } from '../scripts/terminal-ui.mjs';
+import { resolveConsumerRuntimeAliases } from '../scripts/consumer-runtime-aliases.mjs';
 
 // MARK: TERMINAL STYLES
 // ANSI color code used for success-status text.
@@ -562,8 +563,13 @@ async function runDevServer(flags, options = {}) {
     process.env.PORTFOLIABLE_PHP_API_PROXY = phpRuntime.proxyTarget;
   }
 
+  const runtimeAliases = resolveConsumerRuntimeAliases(process.cwd());
+
   // Creates Vite development server instance.
   const server = await createServer({
+    resolve: runtimeAliases.length > 0
+      ? { alias: runtimeAliases }
+      : undefined,
     optimizeDeps: {
       exclude: ['create-portfoliable']
     },
@@ -642,7 +648,10 @@ async function runBuild() {
   printRailSegment();
   printRailSegment({ dot: true, label: `${cyan}${bold}Starting build...${reset}` });
   console.log(`${cyan}${bold}Building Portfoliable...${reset}`);
-  await viteBuild();
+  const runtimeAliases = resolveConsumerRuntimeAliases(process.cwd());
+  await viteBuild(runtimeAliases.length > 0
+    ? { resolve: { alias: runtimeAliases } }
+    : undefined);
   console.log(`${green}Build complete.${reset}`);
   printRailSegment({ dot: true, label: `${green}${bold}Build complete.${reset}` });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-portfoliable",
-  "version": "1.2.11",
+  "version": "1.2.13",
   "description": "Unified Portfoliable package with initializer and runtime CLI",
   "private": false,
   "type": "module",

package/scripts/consumer-runtime-aliases.mjs

@@ -0,0 +1,33 @@
+// File: scripts/consumer-runtime-aliases.mjs
+// Purpose: Resolve consumer-local runtime aliases that override template defaults when files exist.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const TEMPLATE_TO_CONSUMER_TARGETS = [
+  ['../templates/src/cases/index.js', 'src/cases/index.js'],
+  ['../templates/src/content/about/ABOUTME.md', 'src/content/about/ABOUTME.md'],
+  ['../templates/configs/portfoliable.design.config.js', 'configs/portfoliable.design.config.js'],
+  ['../templates/configs/portfoliable.a11y.config.js', 'configs/portfoliable.a11y.config.js'],
+  ['../templates/configs/i18n/i18n.config.js', 'configs/i18n/i18n.config.js'],
+  ['../templates/configs/i18n/i18n.labels.js', 'configs/i18n/i18n.labels.js']
+];
+
+// Builds Vite resolve.alias entries for consumer files that are present in the current project.
+export function resolveConsumerRuntimeAliases(projectRoot = process.cwd()) {
+  const aliases = [];
+
+  for (const [templateSpecifier, consumerRelativePath] of TEMPLATE_TO_CONSUMER_TARGETS) {
+    const consumerAbsolutePath = path.resolve(projectRoot, consumerRelativePath);
+    if (!fs.existsSync(consumerAbsolutePath)) {
+      continue;
+    }
+
+    aliases.push({
+      find: templateSpecifier,
+      replacement: consumerAbsolutePath
+    });
+  }
+
+  return aliases;
+}

package/src/App.js

@@ -26,6 +26,7 @@ import {
     resolveHeaderVisibilityAttributeValue,
     resolveReturnOnlyVisibilityOverrides
 } from './header-visibility.contract.js';
+import { pickReachableRuntimeMediaUrl } from './runtime-media.contract.js';
 import Lenis from 'lenis';
 import {
     AudioPlayer,
@@ -5435,9 +5436,7 @@ class AppShell extends HTMLElement {
             });
         }
 
-        const videoSrcCandidates = this._buildRuntimeMediaCandidates(rawVideoSrc, {
-            preferTemplatePrefix: true
-        });
+        const videoSrcCandidates = this._buildRuntimeMediaCandidates(rawVideoSrc);
 
         if (videoSrcCandidates.length > 1) {
             const resolveToken = `${activeCaseId}:${activeLocale}:${Date.now()}`;
@@ -5791,28 +5790,9 @@ class AppShell extends HTMLElement {
         return candidates[0] || '';
     }
 
-    async _pickReachableRuntimeMediaUrl(candidates = []) {
-        for (const candidate of candidates) {
-            if (!candidate) continue;
-            if (/^(?:https?:|data:|blob:)/i.test(candidate)) {
-                return candidate;
-            }
-
-            try {
-                const response = await fetch(candidate, {
-                    method: 'HEAD',
-                    cache: 'no-store'
-                });
-
-                if (response.ok) {
-                    return candidate;
-                }
-            } catch {
-                // Try next candidate when HEAD checks are unavailable.
-            }
-        }
-
-        return candidates[0] || '';
+    // Resolves to '' when no candidate is confirmed so callers keep the already bound source.
+    _pickReachableRuntimeMediaUrl(candidates = []) {
+        return pickReachableRuntimeMediaUrl(candidates);
     }
 
     _buildRuntimeImageCandidates(value) {

package/src/runtime-media.contract.js

@@ -0,0 +1,61 @@
+// File: src/runtime-media.contract.js
+// Purpose: Confirm that a runtime media candidate URL points at real media before it is bound.
+// Author: Lio Schimanko
+
+// MARK: RESPONSE CLASSIFICATION
+// Dev servers answer unknown paths with an HTML SPA fallback at status 200, so HTML must never count as media.
+export function isRuntimeMediaResponse(response) {
+    if (!response || !response.ok) return false;
+
+    const contentType = String(response.headers?.get?.('content-type') || '').toLowerCase();
+    if (!contentType) return true;
+
+    return !(contentType.startsWith('text/html') || contentType.startsWith('application/xhtml'));
+}
+
+// MARK: CANDIDATE PROBING
+// Returns '' when no candidate is confirmed so callers keep the already bound source.
+export async function pickReachableRuntimeMediaUrl(candidates = [], fetchImpl = globalThis.fetch) {
+    if (typeof fetchImpl !== 'function') return '';
+
+    for (const candidate of candidates) {
+        if (!candidate) continue;
+        if (/^(?:https?:|data:|blob:)/i.test(candidate)) {
+            return candidate;
+        }
+
+        let headResponse = null;
+        try {
+            headResponse = await fetchImpl(candidate, {
+                method: 'HEAD',
+                cache: 'no-store'
+            });
+        } catch {
+            headResponse = null;
+        }
+
+        if (isRuntimeMediaResponse(headResponse)) {
+            return candidate;
+        }
+
+        const headUnsupported = !headResponse || headResponse.status === 405 || headResponse.status === 501;
+        if (!headUnsupported) continue;
+
+        try {
+            // Single-byte range confirms the resource without downloading the media payload.
+            const rangedResponse = await fetchImpl(candidate, {
+                method: 'GET',
+                cache: 'no-store',
+                headers: { Range: 'bytes=0-0' }
+            });
+
+            if (isRuntimeMediaResponse(rangedResponse)) {
+                return candidate;
+            }
+        } catch {
+            // Try next candidate when ranged probing is unavailable.
+        }
+    }
+
+    return '';
+}

package/src/runtime-media.contract.test.js

@@ -0,0 +1,96 @@
+// File: src/runtime-media.contract.test.js
+// Purpose: Validate that media candidate probing rejects SPA fallbacks and never guesses a source.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  isRuntimeMediaResponse,
+  pickReachableRuntimeMediaUrl,
+} from './runtime-media.contract.js';
+
+// MARK: TEST HELPERS
+// Builds a minimal fetch Response stand-in with the headers the probe inspects.
+function makeResponse({ status = 200, contentType = '' } = {}) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: { get: (name) => (name.toLowerCase() === 'content-type' ? contentType : null) },
+  };
+}
+
+const CANONICAL = '/src/content/cases/template-case/template-video.mp4';
+const TEMPLATE = '/templates/src/content/cases/template-case/template-video.mp4';
+
+// MARK: RESPONSE CLASSIFICATION TESTS
+describe('isRuntimeMediaResponse', () => {
+  // Vite answers unknown dev paths with index.html at status 200.
+  it('rejects HTML responses served as a dev-server SPA fallback', () => {
+    expect(isRuntimeMediaResponse(makeResponse({ contentType: 'text/html; charset=utf-8' }))).toBe(false);
+    expect(isRuntimeMediaResponse(makeResponse({ contentType: 'application/xhtml+xml' }))).toBe(false);
+  });
+
+  // Real media and untyped static responses must stay acceptable.
+  it('accepts media and content-type-less responses', () => {
+    expect(isRuntimeMediaResponse(makeResponse({ contentType: 'video/mp4' }))).toBe(true);
+    expect(isRuntimeMediaResponse(makeResponse({ contentType: 'application/octet-stream' }))).toBe(true);
+    expect(isRuntimeMediaResponse(makeResponse({ contentType: '' }))).toBe(true);
+  });
+
+  // Non-success statuses and missing responses are never media.
+  it('rejects failed and absent responses', () => {
+    expect(isRuntimeMediaResponse(makeResponse({ status: 404, contentType: 'video/mp4' }))).toBe(false);
+    expect(isRuntimeMediaResponse(null)).toBe(false);
+  });
+});
+
+// MARK: CANDIDATE PROBING TESTS
+describe('pickReachableRuntimeMediaUrl', () => {
+  // Regression: the SPA fallback used to win and overwrite the working source.
+  it('skips a candidate answered by the SPA fallback and keeps probing', async () => {
+    const fetchImpl = vi.fn(async (url) =>
+      url === CANONICAL
+        ? makeResponse({ contentType: 'video/mp4' })
+        : makeResponse({ contentType: 'text/html' }));
+
+    await expect(pickReachableRuntimeMediaUrl([TEMPLATE, CANONICAL], fetchImpl)).resolves.toBe(CANONICAL);
+  });
+
+  // Absolute URLs are trusted without a network round-trip.
+  it('returns absolute URLs without probing', async () => {
+    const fetchImpl = vi.fn();
+
+    await expect(pickReachableRuntimeMediaUrl(['https://cdn.test/video.mp4'], fetchImpl))
+      .resolves.toBe('https://cdn.test/video.mp4');
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  // Some static hosts answer HEAD with 405, so a single-byte range confirms the file instead.
+  it('falls back to a ranged GET when HEAD is unsupported', async () => {
+    const fetchImpl = vi.fn(async (_url, options) =>
+      options.method === 'HEAD'
+        ? makeResponse({ status: 405 })
+        : makeResponse({ status: 206, contentType: 'video/mp4' }));
+
+    await expect(pickReachableRuntimeMediaUrl([CANONICAL], fetchImpl)).resolves.toBe(CANONICAL);
+    expect(fetchImpl).toHaveBeenCalledTimes(2);
+    expect(fetchImpl.mock.calls[1][1].headers).toEqual({ Range: 'bytes=0-0' });
+  });
+
+  // Returning '' is what stops the caller from replacing an already bound source.
+  it('returns an empty string when no candidate is confirmed', async () => {
+    const fetchImpl = vi.fn(async () => makeResponse({ contentType: 'text/html' }));
+
+    await expect(pickReachableRuntimeMediaUrl([TEMPLATE, CANONICAL], fetchImpl)).resolves.toBe('');
+  });
+
+  // Network failures must not promote an unverified candidate either.
+  it('returns an empty string when probing throws', async () => {
+    const fetchImpl = vi.fn(async () => {
+      throw new Error('network down');
+    });
+
+    await expect(pickReachableRuntimeMediaUrl([TEMPLATE, CANONICAL], fetchImpl)).resolves.toBe('');
+  });
+});

package/vite.config.js

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { defineConfig } from 'vite';
+import { resolveConsumerRuntimeAliases } from './scripts/consumer-runtime-aliases.mjs';
 
 // Detects when @portfoliablejs/valence is installed as a local symlink.
 function isLocalLinkedValence() {
@@ -63,6 +64,7 @@ function getManualChunk(id) {
 export default defineConfig(({ command }) => {
   const usingLocalValence = isLocalLinkedValence();
   const phpApiProxy = String(process.env.PORTFOLIABLE_PHP_API_PROXY || '').trim();
+  const runtimeAliases = resolveConsumerRuntimeAliases(process.cwd());
 
   const serverConfig = (command === 'serve' && usingLocalValence)
     ? {
@@ -88,6 +90,10 @@ export default defineConfig(({ command }) => {
   }
 
   return {
+    resolve: runtimeAliases.length > 0
+      ? { alias: runtimeAliases }
+      : undefined,
+
     // In local-link mode, avoid prebundling Valence so edits in the linked package
     // are reflected immediately during development.
     optimizeDeps: (command === 'serve' && usingLocalValence)