@anglefeint/astro-theme 0.1.16 → 0.1.18

package/README.md

@@ -1,6 +1,7 @@
 ---
 doc_id: package_readme
 doc_role: package-guide
+doc_purpose: Package-level install, upgrade, and manual integration reference for advanced users.
 doc_scope: [package-install, package-upgrade, package-usage]
 update_triggers: [package-change, command-change, export-change]
 source_of_truth: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anglefeint/astro-theme",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "type": "module",
   "description": "Anglefeint core theme package for Astro",
   "keywords": [
@@ -26,6 +26,7 @@
     "src/scripts",
     "src/i18n",
     "src/styles",
+    "src/utils",
     "src/assets/theme",
     "src/cli-new-post.mjs",
     "src/cli-new-page.mjs"
@@ -42,6 +43,8 @@
     "./i18n/*": "./src/i18n/*",
     "./styles/*": "./src/styles/*",
     "./assets/*": "./src/assets/*",
+    "./utils/merge": "./src/utils/merge.ts",
+    "./utils/*": "./src/utils/*",
     "./content-schema": "./src/content-schema.ts",
     "./consts": "./src/consts.ts"
   },

package/src/cli-new-page.mjs

@@ -1,54 +1,15 @@
 import { access, mkdir, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import path from 'node:path';
+import {
+	buildNewPageTemplate,
+	isValidNewPageTheme,
+	parseNewPageArgs,
+	usageNewPage,
+	validatePageSlug,
+} from './scaffold/new-page.mjs';
 
-const THEMES = ['base', 'cyber', 'ai', 'hacker', 'matrix'];
 const PAGES_ROOT = path.resolve(process.cwd(), 'src/pages/[lang]');
-const LAYOUT_BY_THEME = {
-	base: 'BasePageLayout',
-	ai: 'AiPageLayout',
-	cyber: 'CyberPageLayout',
-	hacker: 'HackerPageLayout',
-	matrix: 'MatrixPageLayout',
-};
-
-function usage() {
-	console.error('Usage: npm run new-page -- <slug> [--theme <base|cyber|ai|hacker|matrix>]');
-}
-
-function parseArgs(argv) {
-	const args = argv.slice(2);
-	const positional = [];
-	let theme = 'base';
-
-	for (let i = 0; i < args.length; i += 1) {
-		const token = args[i];
-		if (token === '--theme') {
-			theme = args[i + 1] ?? '';
-			i += 1;
-			continue;
-		}
-		positional.push(token);
-	}
-
-	return { slug: positional[0], theme };
-}
-
-function validateSlug(slug) {
-	if (!slug) return false;
-	if (slug.startsWith('/') || slug.endsWith('/')) return false;
-	const parts = slug.split('/');
-	return parts.every((part) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(part));
-}
-
-function toTitleFromSlug(slug) {
-	const leaf = slug.split('/').pop() ?? slug;
-	return leaf
-		.split('-')
-		.filter(Boolean)
-		.map((segment) => segment[0].toUpperCase() + segment.slice(1))
-		.join(' ');
-}
 
 async function exists(filePath) {
 	try {
@@ -59,42 +20,20 @@ async function exists(filePath) {
 	}
 }
 
-function templateFor({ slug, theme }) {
-	const title = toTitleFromSlug(slug) || 'New Page';
-	const layoutName = LAYOUT_BY_THEME[theme];
-	return `---
-import type { GetStaticPaths } from 'astro';
-import ${layoutName} from '@anglefeint/astro-theme/layouts/${layoutName}.astro';
-import { SUPPORTED_LOCALES } from '@anglefeint/astro-theme/i18n/config';
-
-export const getStaticPaths = (() => SUPPORTED_LOCALES.map((lang) => ({ params: { lang } }))) satisfies GetStaticPaths;
-
-const locale = Astro.params.lang;
-const pageTitle = '${title}';
-const pageDescription = 'A custom page built from the ${theme} theme shell.';
----
-
-<${layoutName} locale={locale} title={pageTitle} description={pageDescription}>
-\t<h1>${title}</h1>
-\t<p>Replace this content with your own page content.</p>
-</${layoutName}>
-`;
-}
-
 async function main() {
-	const { slug, theme: rawTheme } = parseArgs(process.argv);
+	const { slug, theme: rawTheme } = parseNewPageArgs(process.argv);
 	const theme = String(rawTheme || '').toLowerCase();
 
 	if (!slug) {
-		usage();
+		console.error(usageNewPage());
 		process.exit(1);
 	}
-	if (!validateSlug(slug)) {
+	if (!validatePageSlug(slug)) {
 		console.error('Invalid page slug. Use lowercase letters, numbers, hyphens, and optional nested paths.');
 		process.exit(1);
 	}
-	if (!THEMES.includes(theme)) {
-		console.error(`Invalid theme "${rawTheme}". Use one of: ${THEMES.join(', ')}.`);
+	if (!isValidNewPageTheme(theme)) {
+		console.error('Invalid theme. Use one of: base, cyber, ai, hacker, matrix.');
 		process.exit(1);
 	}
 
@@ -109,7 +48,7 @@ async function main() {
 	await mkdir(targetDir, { recursive: true });
 	await writeFile(
 		targetPath,
-		templateFor({ slug, theme }),
+		buildNewPageTemplate({ slug, theme }),
 		'utf8',
 	);
 

package/src/cli-new-post.mjs

@@ -1,47 +1,20 @@
-import { mkdir, writeFile, access, readdir } from 'node:fs/promises';
+import { mkdir, writeFile, access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import path from 'node:path';
 import { SUPPORTED_LOCALES } from './i18n/locales.mjs';
+import {
+	buildNewPostTemplate,
+	loadDefaultCovers,
+	parseNewPostArgs,
+	pickDefaultCoverBySlug,
+	resolveLocales,
+	usageNewPost,
+	validatePostSlug,
+} from './scaffold/new-post.mjs';
 
 const CONTENT_ROOT = path.resolve(process.cwd(), 'src/content/blog');
 const DEFAULT_COVERS_ROOT = path.resolve(process.cwd(), 'src/assets/blog/default-covers');
 
-function toTitleFromSlug(slug) {
-	return slug
-		.split('-')
-		.filter(Boolean)
-		.map((segment) => segment[0].toUpperCase() + segment.slice(1))
-		.join(' ');
-}
-
-function validateSlug(slug) {
-	return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug);
-}
-
-function hashString(input) {
-	let hash = 5381;
-	for (let i = 0; i < input.length; i += 1) {
-		hash = ((hash << 5) + hash + input.charCodeAt(i)) >>> 0;
-	}
-	return hash >>> 0;
-}
-
-function normalizePathForFrontmatter(filePath) {
-	return filePath.split(path.sep).join('/');
-}
-
-async function loadDefaultCovers() {
-	try {
-		const entries = await readdir(DEFAULT_COVERS_ROOT, { withFileTypes: true });
-		return entries
-			.filter((entry) => entry.isFile() && /\.(webp|png|jpe?g)$/i.test(entry.name))
-			.map((entry) => path.join(DEFAULT_COVERS_ROOT, entry.name))
-			.sort((a, b) => a.localeCompare(b));
-	} catch {
-		return [];
-	}
-}
-
 async function exists(filePath) {
 	try {
 		await access(filePath, constants.F_OK);
@@ -51,58 +24,29 @@ async function exists(filePath) {
 	}
 }
 
-function templateFor(locale, slug, pubDate, heroImage) {
-	const titleByLocale = {
-		en: toTitleFromSlug(slug),
-		ja: '新しい記事タイトル',
-		ko: '새 글 제목',
-		es: 'Título del nuevo artículo',
-		zh: '新文章标题',
-	};
-	const descriptionByLocale = {
-		en: `A short EN post scaffold for "${slug}".`,
-		ja: `「${slug}」用の短い日本語記事テンプレートです。`,
-		ko: `"${slug}"용 한국어 글 템플릿입니다.`,
-		es: `Plantilla breve en español para "${slug}".`,
-		zh: `“${slug}”的中文文章模板。`,
-	};
-	const bodyByLocale = {
-		en: `Write your EN content for "${slug}" here.`,
-		ja: `ここに「${slug}」の日本語本文を書いてください。`,
-		ko: `여기에 "${slug}" 한국어 본문을 작성하세요.`,
-		es: `Escribe aquí el contenido en español para "${slug}".`,
-		zh: `请在这里填写“${slug}”的中文正文。`,
-	};
-	return `---
-title: '${titleByLocale[locale]}'
-subtitle: ''
-description: '${descriptionByLocale[locale]}'
-pubDate: '${pubDate}'
-${heroImage ? `heroImage: '${heroImage}'` : ''}
----
-
-${bodyByLocale[locale]}
-`;
-}
-
 async function main() {
-	const slug = process.argv[2];
+	const { slug, locales: cliLocales } = parseNewPostArgs(process.argv);
 	if (!slug) {
-		console.error('Usage: npm run new-post -- <slug>');
+		console.error(usageNewPost());
 		process.exit(1);
 	}
 
-	if (!validateSlug(slug)) {
+	if (!validatePostSlug(slug)) {
 		console.error('Invalid slug. Use lowercase letters, numbers, and hyphens only.');
 		process.exit(1);
 	}
 
 	const pubDate = new Date().toISOString().slice(0, 10);
-	const defaultCovers = await loadDefaultCovers();
+	const defaultCovers = await loadDefaultCovers(DEFAULT_COVERS_ROOT);
+	const locales = resolveLocales({
+		cliLocales,
+		envLocales: process.env.ANGLEFEINT_LOCALES ?? '',
+		defaultLocales: SUPPORTED_LOCALES,
+	});
 	const created = [];
 	const skipped = [];
 
-	for (const locale of SUPPORTED_LOCALES) {
+	for (const locale of locales) {
 		const localeDir = path.join(CONTENT_ROOT, locale);
 		const filePath = path.join(localeDir, `${slug}.md`);
 		await mkdir(localeDir, { recursive: true });
@@ -112,13 +56,9 @@ async function main() {
 			continue;
 		}
 
-		let heroImage = '';
-		if (defaultCovers.length > 0) {
-			const coverPath = defaultCovers[hashString(slug) % defaultCovers.length];
-			heroImage = normalizePathForFrontmatter(path.relative(localeDir, coverPath));
-		}
+		const heroImage = pickDefaultCoverBySlug(slug, localeDir, defaultCovers);
 
-		await writeFile(filePath, templateFor(locale, slug, pubDate, heroImage), 'utf8');
+		await writeFile(filePath, buildNewPostTemplate(locale, slug, pubDate, heroImage), 'utf8');
 		created.push(filePath);
 	}
 

package/src/config/theme.ts

@@ -8,4 +8,8 @@ export const THEME = {
 	HOME_LATEST_COUNT: 3,
 	/** Whether to enable the About page (disable to hide from nav/routes if needed) */
 	ENABLE_ABOUT_PAGE: true,
+	/** Optional visual effects switches */
+	EFFECTS: {
+		ENABLE_RED_QUEEN: true,
+	},
 } as const;

package/src/layouts/BlogPost.astro

@@ -7,6 +7,7 @@ import FormattedDate from '../components/FormattedDate.astro';
 import AiShell from './shells/AiShell.astro';
 import blogPostCssUrl from '../styles/blog-post.css?url';
 import { SITE_AUTHOR } from '@anglefeint/site-config/site';
+import { THEME } from '@anglefeint/site-config/theme';
 import { DEFAULT_LOCALE, type Locale, isLocale, localePath, blogIdToSlugAnyLocale } from '@anglefeint/site-i18n/config';
 import { getMessages } from '@anglefeint/site-i18n/messages';
 
@@ -49,6 +50,7 @@ const hasSystemMeta = Boolean(aiModel || aiMode || aiState);
 const hasResponseMeta = aiLatencyMs !== undefined || aiConfidence !== undefined;
 const hasStats = aiModel || wordCount !== undefined || tokenCount !== undefined;
 const confidenceText = aiConfidence !== undefined ? aiConfidence.toFixed(2) : undefined;
+const enableRedQueen = THEME.EFFECTS.ENABLE_RED_QUEEN;
 ---
 
 <AiShell
@@ -79,11 +81,13 @@ const confidenceText = aiConfidence !== undefined ? aiConfidence.toFixed(2) : un
 			</div>
 			<canvas class="ai-network-canvas" aria-hidden="true"></canvas>
 		</div>
-		<aside class="rq-tv rq-tv-collapsed">
-			<div class="rq-tv-stage" data-rq-src={themeRedqueen1.src} data-rq-src2={themeRedqueen2.src}></div>
-			<div class="rq-tv-badge">monitor feed<span class="rq-tv-dot"></span></div>
-			<button type="button" class="rq-tv-toggle" aria-label="Replay monitor feed" aria-expanded="false">▶</button>
-		</aside>
+		{enableRedQueen && (
+			<aside class="rq-tv rq-tv-collapsed">
+				<div class="rq-tv-stage" data-rq-src={themeRedqueen1.src} data-rq-src2={themeRedqueen2.src}></div>
+				<div class="rq-tv-badge">monitor feed<span class="rq-tv-dot"></span></div>
+				<button type="button" class="rq-tv-toggle" aria-label="Replay monitor feed" aria-expanded="false">▶</button>
+			</aside>
+		)}
 		<div class="ai-read-progress" aria-hidden="true"></div>
 		<button type="button" class="ai-back-to-top" aria-label="Back to top" title="Back to top">↑</button>
 		<div class="ai-stage-toast" aria-live="polite" aria-atomic="true"></div>

package/src/scripts/blogpost-effects.js

@@ -17,6 +17,8 @@ export function initBlogpostEffects() {
   initReadProgressAndBackToTop(prefersReducedMotion);
   initNetworkCanvas(prefersReducedMotion);
   initHeroCanvas(prefersReducedMotion);
-  initRedQueenTv(prefersReducedMotion);
+  if (document.querySelector('.rq-tv-stage')) {
+    initRedQueenTv(prefersReducedMotion);
+  }
   initPostInteractions(prefersReducedMotion);
 }

package/src/utils/merge.ts

@@ -0,0 +1,31 @@
+export type DeepPartial<T> = {
+	[K in keyof T]?: T[K] extends Array<infer U>
+		? Array<DeepPartial<U>>
+		: T[K] extends object
+			? DeepPartial<T[K]>
+			: T[K];
+};
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Object.prototype.toString.call(value) === '[object Object]';
+}
+
+export function deepMerge<T>(base: T, override: DeepPartial<T>): T {
+	if (!isPlainObject(base) || !isPlainObject(override)) return (override as T) ?? base;
+
+	const result: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+	for (const [key, value] of Object.entries(override)) {
+		if (value === undefined) continue;
+		const existing = result[key];
+		if (Array.isArray(value)) {
+			result[key] = value;
+			continue;
+		}
+		if (isPlainObject(existing) && isPlainObject(value)) {
+			result[key] = deepMerge(existing, value);
+			continue;
+		}
+		result[key] = value;
+	}
+	return result as T;
+}