gulp-mu-css 2.0.0

package/src/build/MediaSteps.mjs

@@ -0,0 +1,171 @@
+// Bridge from manifest "media" steps to microPS (CONCEPT.md, D3): renders
+// PSD-based image series, app icons and sequence strips into the skin output
+// directory and copies static assets. Generator steps are skipped when their
+// configuration, sources and outputs are unchanged (D7); copy steps use a
+// classic make-style mtime comparison.
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { ButtonAndIconCreator, AppIconMaker, SequenceStrip } from "gulp-mu-ps";
+import { FileFingerprint, FingerprintFiles, FingerprintsMatch } from "./BuildCache.mjs";
+
+// "imgs/smoke.png" + "webp" -> "imgs/smoke.webp"
+function _SwapExtension(_file, _format) {
+	const dot = _file.lastIndexOf(".");
+	return dot < 0 ? `${_file}.${_format}` : `${_file.slice(0, dot)}.${_format}`;
+}
+
+function _ListFilesRecursive(_dir) {
+	const result = [];
+	for (const entry of readdirSync(_dir, { withFileTypes: true }).sort((_a, _b) => _a.name.localeCompare(_b.name))) {
+		const path = join(_dir, entry.name);
+		if (entry.isDirectory()) result.push(..._ListFilesRecursive(path));
+		else result.push(path);
+	}
+	return result;
+}
+
+// Copies _source to _target when the target is missing or older (make-style).
+function _CopyIfNewer(_source, _target) {
+	const sourceStat = statSync(_source);
+	if (existsSync(_target) && statSync(_target).mtimeMs >= sourceStat.mtimeMs) return false;
+	mkdirSync(dirname(_target), { recursive: true });
+	copyFileSync(_source, _target);
+	return true;
+}
+
+// Resolves the base directory for step outputs. Default is the skin output
+// directory; outputBase: "project" targets the project root instead, so a
+// step can generate intermediate assets (raw -> final, e.g. sequence strips)
+// that later copy/copyFolder steps pick up.
+function _OutputBase(_step, _ctx) {
+	const base = _step.outputBase ?? "skin";
+	if (base === "skin") return _ctx.outputDir;
+	if (base === "project") return _ctx.rootDir;
+	throw new Error(`invalid outputBase "${_step.outputBase}" (use "skin" or "project")`);
+}
+
+// Runs one media step. _ctx: { rootDir, outputDir, imageFormat, cache, index }
+// Returns { type, skipped, outputs }.
+export async function RunMediaStep(_step, _ctx) {
+	if (_step.copy) return _RunCopy(_step, _ctx);
+	if (_step.copyFolder) return _RunCopyFolder(_step, _ctx);
+	if (_step.buttonsAndIcons) return _RunGenerator(_step, _ctx, "buttonsAndIcons", _ButtonsAndIcons);
+	if (_step.appIcons) return _RunGenerator(_step, _ctx, "appIcons", _AppIcons);
+	if (_step.sequenceStrip) return _RunGenerator(_step, _ctx, "sequenceStrip", _SequenceStrip);
+	throw new Error(`unknown media step: ${JSON.stringify(_step)}`);
+}
+
+function _RunCopy(_step, _ctx) {
+	const source = join(_ctx.rootDir, _step.copy);
+	if (!existsSync(source)) {
+		throw new Error(`copy: source file not found: ${source}`);
+	}
+	const target = join(_OutputBase(_step, _ctx), _step.to ?? ".", basename(_step.copy));
+	const copied = _CopyIfNewer(source, target);
+	return { type: "copy", skipped: !copied, outputs: [target] };
+}
+
+function _RunCopyFolder(_step, _ctx) {
+	const sourceDir = join(_ctx.rootDir, _step.copyFolder);
+	if (!existsSync(sourceDir)) {
+		throw new Error(`copyFolder: source folder not found: ${sourceDir} `
+			+ "(was the generation step that produces this folder run?)");
+	}
+	const targetDir = join(_OutputBase(_step, _ctx), _step.to ?? basename(_step.copyFolder));
+	// Optional filename filter (regex source string), e.g. "\\.(png|json)$".
+	const filter = _step.filter ? new RegExp(_step.filter, "i") : null;
+	const outputs = [];
+	let copiedAny = false;
+	for (const source of _ListFilesRecursive(sourceDir)) {
+		const relative = source.slice(sourceDir.length + 1);
+		if (filter && !filter.test(relative.replace(/\\/g, "/"))) continue;
+		const target = join(targetDir, relative);
+		if (_CopyIfNewer(source, target)) copiedAny = true;
+		outputs.push(target);
+	}
+	return { type: "copyFolder", skipped: !copiedAny, outputs };
+}
+
+// Generic generator step with D7 cache check: skip when the step config is
+// unchanged, all sources have unchanged mtime/size and all outputs exist.
+async function _RunGenerator(_step, _ctx, _type, _Runner) {
+	const format = _step.format ?? _ctx.imageFormat;
+	const sources = _CollectSources(_step, _ctx, _type);
+	const signature = JSON.stringify({ step: _step, format });
+	const fingerprints = FingerprintFiles(sources);
+	const cacheKey = `media:${_ctx.index}`;
+
+	const cached = _ctx.cache?.Get(cacheKey);
+	if (cached
+		&& cached.signature === signature
+		&& FingerprintsMatch(cached.sources, fingerprints)
+		&& cached.outputs.every((_file) => existsSync(_file))) {
+		return { type: _type, skipped: true, outputs: cached.outputs };
+	}
+
+	const outputs = await _Runner(_step, _ctx, format, sources);
+	_ctx.cache?.Set(cacheKey, { signature, sources: fingerprints, outputs });
+	return { type: _type, skipped: false, outputs };
+}
+
+function _CollectSources(_step, _ctx, _type) {
+	const source = join(_ctx.rootDir, _step[_type]);
+	if (!existsSync(source)) {
+		throw new Error(`${_type}: source not found: ${source}`);
+	}
+	if (_type === "sequenceStrip" && statSync(source).isDirectory()) {
+		return _ListFilesRecursive(source);
+	}
+	return [source];
+}
+
+async function _ButtonsAndIcons(_step, _ctx, _format, _sources) {
+	if (!_step.outputDir) throw new Error("buttonsAndIcons: outputDir is required.");
+	const outputDir = join(_OutputBase(_step, _ctx), _step.outputDir);
+	// mode "topLayerSets": one image per top child group (legacy
+	// CreateByTopLayerSets); default mode is the icon x state matrix.
+	if (_step.mode === "topLayerSets") {
+		return ButtonAndIconCreator.CreateByTopLayerSets(_sources[0], {
+			layout: _step.layout,
+			outputDir,
+			retina: _step.retina ?? true,
+			format: _format,
+			...(_step.setPattern ? { setPattern: _step.setPattern } : {})
+		});
+	}
+	return ButtonAndIconCreator.Create(_sources[0], {
+		layout: _step.layout,
+		outputDir,
+		retina: _step.retina ?? true,
+		format: _format
+	});
+}
+
+async function _AppIcons(_step, _ctx, _format, _sources) {
+	return AppIconMaker.Create(_sources[0], {
+		outputDir: join(_OutputBase(_step, _ctx), _step.outputDir ?? "."),
+		...(_step.profiles ? { profiles: _step.profiles } : {}),
+		...(_step.layout ? { layout: _step.layout } : {}),
+		...(_step.background ? { background: _step.background } : {}),
+		...(_step.appName ? { appName: _step.appName } : {}),
+		...(_step.themeColor ? { themeColor: _step.themeColor } : {}),
+		...(_step.shortName ? { shortName: _step.shortName } : {})
+	});
+}
+
+async function _SequenceStrip(_step, _ctx, _format, _sources) {
+	if (!_step.outputFile) throw new Error("sequenceStrip: outputFile is required.");
+	const outputFile = join(_OutputBase(_step, _ctx), _format === "png"
+		? _step.outputFile
+		: _SwapExtension(_step.outputFile, _format));
+	// A directory source is a frame sequence, a single file is a DSD image.
+	const sourceIsDir = statSync(join(_ctx.rootDir, _step.sequenceStrip)).isDirectory();
+	const result = await SequenceStrip.Create({
+		...(sourceIsDir ? { images: _sources } : { dsdImage: _sources[0] }),
+		outputFile,
+		retina: _step.retina ?? true,
+		writeMapFile: _step.writeMapFile ?? true
+	});
+	return result.files;
+}

package/src/build/SkinBuilder.mjs

@@ -0,0 +1,197 @@
+// Skin build orchestration (CONCEPT.md, D3/D7): loads a skin manifest
+// (skins/src/<skinname>.µcss.mjs), runs the media steps (microPS bridge, cached),
+// compiles all µCSS source files (*.µ.css), resolves the sprite atlas (with position cache)
+// and writes the results into the skin output directory.
+
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { join, dirname, parse, resolve } from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { CompileMcss } from "../compile/Compiler.mjs";
+import { SpriteManager } from "../api/Sprites.mjs";
+import { CursorManager } from "../api/Cursors.mjs";
+import { PreloadRegistry } from "../api/Preload.mjs";
+import { BuildCache, FingerprintFiles, FingerprintsMatch, CACHE_SCHEMA } from "./BuildCache.mjs";
+import { RunMediaStep } from "./MediaSteps.mjs";
+
+const ownPackage = JSON.parse(
+	readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf8")
+);
+
+// "imgs/sprites.png" + "webp" -> "imgs/sprites.webp"
+function _SwapExtension(_file, _format) {
+	const dot = _file.lastIndexOf(".");
+	return dot < 0 ? `${_file}.${_format}` : `${_file.slice(0, dot)}.${_format}`;
+}
+
+function _RetinaUrl(_url) {
+	const dot = _url.lastIndexOf(".");
+	return dot < 0 ? `${_url}@2x` : `${_url.slice(0, dot)}@2x${_url.slice(dot)}`;
+}
+
+// Declares a skin configuration (manifest default export). Performs basic
+// validation and fills in nothing - the structure is plain data plus helper
+// functions, see CONCEPT.md D3.
+export function DefineSkin(_config) {
+	if (!_config || typeof _config !== "object") {
+		throw new Error("DefineSkin: a configuration object is required.");
+	}
+	for (const entry of _config.files ?? []) {
+		if (!entry.source || !entry.target) {
+			throw new Error(`DefineSkin: files entries need source and target (${JSON.stringify(entry)}).`);
+		}
+	}
+	return _config;
+}
+
+// Imports the manifest module; the mtime query defeats Node's module cache
+// so watch runs pick up manifest edits.
+async function _LoadManifest(_manifestFile) {
+	const stamp = Math.round(statSync(_manifestFile).mtimeMs);
+	const module = await import(`${pathToFileURL(_manifestFile).href}?mtime=${stamp}`);
+	if (!module.default || typeof module.default !== "object") {
+		throw new Error(`BuildSkin: manifest "${_manifestFile}" has no default export (DefineSkin({...})).`);
+	}
+	return module.default;
+}
+
+// Resolves the sprite atlas with the D7 position cache: when the image set,
+// the source images (incl. @2x) and the atlas options are unchanged and the
+// atlas files still exist, the cached positions are reused and no packing or
+// encoding happens.
+async function _ResolveSprites(_sprites, _document, _cache, _force) {
+	const urls = _sprites.ImageUrls();
+	if (!urls.length) {
+		await _sprites.Resolve(_document);
+		return { atlas: null, skipped: false };
+	}
+
+	const options = _sprites.options;
+	const sourceFiles = [];
+	for (const url of urls) {
+		sourceFiles.push(join(options.baseDir, url));
+		if (options.retina) sourceFiles.push(join(options.baseDir, _RetinaUrl(url)));
+	}
+	const signature = JSON.stringify({
+		atlasFile: options.atlasFile,
+		retina: options.retina,
+		padding: options.padding,
+		urls
+	});
+	const fingerprints = FingerprintFiles(sourceFiles);
+	const atlasFiles = [join(options.baseDir, options.atlasFile)];
+	if (options.retina) atlasFiles.push(join(options.baseDir, _RetinaUrl(options.atlasFile)));
+
+	const cached = _cache.Get("atlas");
+	if (!_force
+		&& cached
+		&& cached.signature === signature
+		&& FingerprintsMatch(cached.sources, fingerprints)
+		&& atlasFiles.every((_file) => existsSync(_file))) {
+		const atlas = await _sprites.Resolve(_document, { cached: cached.atlas });
+		return { atlas, skipped: true };
+	}
+
+	const atlas = await _sprites.Resolve(_document);
+	_cache.Set("atlas", { signature, sources: fingerprints, atlas });
+	return { atlas, skipped: false };
+}
+
+// Builds one skin from its manifest file.
+//
+// Directory conventions (CONCEPT.md, D3): for skins/src/std.µcss.mjs the skin
+// name is "std", the output directory skins/std/ and the project root (base of
+// media source paths like dev/media/...) two levels above the manifest.
+// All three are overridable via _options { outputDir, rootDir, force }.
+export async function BuildSkin(_manifestPath, _options = {}) {
+	const startedAt = Date.now();
+	const manifestFile = resolve(_manifestPath);
+	const srcDir = dirname(manifestFile);
+	// Strip the manifest marker (".µcss" or ASCII ".mucss") from the basename.
+	const skinName = parse(manifestFile).name.replace(/\.(µcss|mucss)$/i, "");
+	const rootDir = _options.rootDir ? resolve(_options.rootDir) : resolve(srcDir, "..", "..");
+	const outputDir = _options.outputDir ? resolve(_options.outputDir) : resolve(srcDir, "..", skinName);
+	const force = !!_options.force;
+
+	const config = await _LoadManifest(manifestFile);
+	mkdirSync(outputDir, { recursive: true });
+
+	const cache = BuildCache.Load(join(outputDir, ".cache", "build.json"), {
+		schema: CACHE_SCHEMA,
+		package: ownPackage.version
+	});
+	if (force) cache.Clear();
+
+	// 1. Media steps (microPS bridge) - the images must exist before the
+	// sprite atlas and the cursor @2x checks run. skipMedia builds CSS only,
+	// assuming the media outputs already exist (e.g. migration comparisons).
+	const imageFormat = config.imageFormat ?? "png";
+	const media = [];
+	if (!_options.skipMedia) {
+		for (let index = 0; index < (config.media ?? []).length; index++) {
+			const step = config.media[index];
+			try {
+				media.push(await RunMediaStep(step, { rootDir, outputDir, imageFormat, cache, index }));
+			} catch (error) {
+				const label = ["copy", "copyFolder", "buttonsAndIcons", "appIcons", "sequenceStrip"]
+					.filter((_key) => step[_key]).map((_key) => `${_key}: "${step[_key]}"`).join(", ");
+				throw new Error(`BuildSkin: media step ${index + 1} of ${config.media.length} (${label || JSON.stringify(step)}) failed: ${error.message}`, { cause: error });
+			}
+		}
+	}
+
+	// 2. Managers for the µ-directives.
+	const preload = new PreloadRegistry(outputDir);
+	const cursors = new CursorManager(config.cursors ?? [], { baseDir: outputDir, preload });
+	const spritesConfig = config.sprites ?? {};
+	const atlasFile = imageFormat === "png"
+		? (spritesConfig.file ?? "imgs/sprites.png")
+		: _SwapExtension(spritesConfig.file ?? "imgs/sprites.png", imageFormat);
+	const sprites = new SpriteManager({
+		baseDir: outputDir,
+		atlasFile,
+		retina: spritesConfig.retina ?? true,
+		padding: spritesConfig.padding ?? 0,
+		preloadRule: !!spritesConfig.preloadRule,
+		preload
+	});
+
+	// 3. Compile all stylesheets (sprite rules register, nothing is packed yet).
+	const compiled = [];
+	for (const entry of config.files ?? []) {
+		const sourceFile = join(srcDir, entry.source);
+		if (!existsSync(sourceFile)) {
+			throw new Error(`BuildSkin: source file "${entry.source}" (files entry for target "${entry.target}") not found: ${sourceFile}`);
+		}
+		const document = CompileMcss(readFileSync(sourceFile, "utf8"), {
+			vars: config.vars ?? {},
+			helpers: config.helpers ?? {},
+			sprites,
+			cursors,
+			from: sourceFile
+		});
+		compiled.push({ entry, document });
+	}
+
+	// 4. Sprite atlas (cached) - rewrites the registered rules in all
+	// documents; the preload rule goes into the first stylesheet.
+	const atlasResult = await _ResolveSprites(sprites, compiled[0]?.document ?? null, cache, force);
+
+	// 5. Emit.
+	const files = [];
+	for (const { entry, document } of compiled) {
+		const target = join(outputDir, entry.target);
+		await document.ToFile(target);
+		files.push({ source: entry.source, target });
+	}
+
+	cache.Save();
+	return {
+		skin: skinName,
+		outputDir,
+		media,
+		files,
+		atlas: atlasResult.atlas,
+		atlasSkipped: atlasResult.skipped,
+		duration: Date.now() - startedAt
+	};
+}

package/src/compile/Compiler.mjs

@@ -0,0 +1,168 @@
+// The µCSS source compiler core (*.µ.css): resolves µ(expression) interpolations in values
+// and executes -µ:/-mu: directive declarations (docs/CONCEPT.md, D2).
+// Sprite/cursor/media directives are added in later milestones; this core
+// provides the mechanism plus the rule-bound manipulation builtins.
+
+import { CssDocument, CssRule } from "../css/CssDocument.mjs";
+import { MuContext } from "../eval/MuContext.mjs";
+
+const DIRECTIVE_PROP = /^-(?:µ|mu)$/i;
+
+// Finds the next µ( / mu( interpolation start in a text, returns
+// { start, exprStart } or null. "mu" must stand on a word boundary so that
+// e.g. "emu(" is not treated as an interpolation.
+function _FindStart(_text, _from) {
+	for (let i = _from; i < _text.length; i++) {
+		if (_text[i] === "\u00B5" && _text[i + 1] === "(") {
+			return { start: i, exprStart: i + 2 };
+		}
+		if (_text[i] === "m" && _text[i + 1] === "u" && _text[i + 2] === "(") {
+			const before = i > 0 ? _text[i - 1] : "";
+			if (!/[A-Za-z0-9_-]/.test(before)) return { start: i, exprStart: i + 3 };
+		}
+	}
+	return null;
+}
+
+// Returns the index of the parenthesis closing the expression that starts at
+// _exprStart (which is just behind the opening paren), honoring nested parens
+// and quoted strings.
+function _FindEnd(_text, _exprStart) {
+	let depth = 1;
+	let quote = null;
+	for (let i = _exprStart; i < _text.length; i++) {
+		const ch = _text[i];
+		if (quote) {
+			if (ch === "\\") i++;
+			else if (ch === quote) quote = null;
+		} else if (ch === "'" || ch === "\"" || ch === "`") {
+			quote = ch;
+		} else if (ch === "(") {
+			depth++;
+		} else if (ch === ")") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+
+// Replaces every µ(expr) / mu(expr) occurrence in _text with the evaluated
+// result. _evaluate receives the raw expression source.
+export function ReplaceInterpolations(_text, _evaluate) {
+	let text = _text;
+	let searchFrom = 0;
+	for (;;) {
+		const hit = _FindStart(text, searchFrom);
+		if (!hit) return text;
+		const end = _FindEnd(text, hit.exprStart);
+		if (end < 0) throw new Error(`unbalanced parentheses in interpolation: ${text.slice(hit.start)}`);
+		const expression = text.slice(hit.exprStart, end);
+		let result;
+		try {
+			result = _evaluate(expression);
+		} catch (error) {
+			// Name the failing expression - a value may contain several µ().
+			throw new Error(`µ(${expression}): ${error.message}`, { cause: error });
+		}
+		if (result === null || result === undefined) {
+			throw new Error(`interpolation µ(${expression}) returned ${result}`);
+		}
+		const replacement = String(result);
+		text = text.slice(0, hit.start) + replacement + text.slice(end + 1);
+		searchFrom = hit.start + replacement.length;
+	}
+}
+
+// Builds the extra scope for a directive: manipulation builtins bound to the
+// rule that contains the directive declaration, plus the sprite/cursor
+// directives when their managers are configured.
+function _DirectiveScope(_decl, _document, _options, _insertAnchors) {
+	const parent = _decl.parent;
+	const rule = (parent && parent.type !== "root") ? new CssRule(parent) : null;
+	const scope = {
+		rule,
+		document: _document,
+		AddProperty: (_prop, _value, _important) => rule.AddProperty(_prop, _value, _important),
+		ChangeProperty: (_prop, _value, _important) => rule.ChangeProperty(_prop, _value, _important),
+		RemoveProperty: (_prop) => rule.RemoveProperty(_prop),
+		AddRule: (_selector) => _document.AddRule(_selector),
+		// InsertRule places generated rules directly behind the rule that
+		// contains the directive; consecutive calls keep their order, even
+		// across multiple directives in the same rule (legacy AddBlock with
+		// element index).
+		InsertRule: (_selector) => {
+			const anchor = _insertAnchors.get(parent) ?? rule;
+			const inserted = _document.AddRule(_selector, { after: anchor });
+			_insertAnchors.set(parent, inserted);
+			return inserted;
+		},
+		Sprite: (_url, _spriteOptions) => {
+			if (!_options.sprites) throw new Error("Sprite(): no sprite manager configured (options.sprites).");
+			_options.sprites.Register(rule, _url, _spriteOptions);
+		},
+		Cursor: (_name) => {
+			if (!_options.cursors) throw new Error("Cursor(): no cursor manager configured (options.cursors).");
+			_options.cursors.Apply(rule, _name);
+		}
+	};
+	return scope;
+}
+
+// Extra scope for value interpolations: Cursor(...) as value function.
+function _ValueScope(_options) {
+	if (!_options.cursors) return {};
+	return { Cursor: (_name) => _options.cursors.Value(_name) };
+}
+
+// Compiles µCSS source text (*.µ.css) into a CssDocument:
+//   1. -µ:/-mu: directive declarations are evaluated (document order) and
+//      removed from the output.
+//   2. µ(expr)/mu(expr) interpolations in declaration values and at-rule
+//      params are replaced by their evaluated result.
+//
+// _options: { vars, helpers, from, context, sprites, cursors } - pass an
+// existing MuContext via context, or vars/helpers to create one. sprites
+// (SpriteManager) and cursors (CursorManager) enable the Sprite()/Cursor()
+// directives; sprite rules are only registered here and rewritten later by
+// sprites.Resolve(document).
+export function CompileMcss(_source, _options = {}) {
+	const document = _source instanceof CssDocument
+		? _source
+		: CssDocument.FromString(_source, { from: _options.from });
+	const context = _options.context ?? new MuContext(_options);
+	const valueScope = _ValueScope(_options);
+	// Last InsertRule() result per containing rule (see _DirectiveScope).
+	const insertAnchors = new Map();
+
+	// Snapshot first: directives may append nodes, which must not be walked.
+	const decls = [];
+	document.root.walkDecls((_decl) => decls.push(_decl));
+	const atrules = [];
+	document.root.walkAtRules((_atrule) => atrules.push(_atrule));
+
+	for (const decl of decls) {
+		try {
+			if (DIRECTIVE_PROP.test(decl.prop)) {
+				context.Evaluate(decl.value, _DirectiveScope(decl, document, _options, insertAnchors));
+				decl.remove();
+			} else if (decl.value.includes("(")) {
+				decl.value = ReplaceInterpolations(decl.value, (_expr) => context.Evaluate(_expr, valueScope));
+			}
+		} catch (error) {
+			throw decl.error(`microCSS: ${error.message}`, { word: decl.prop });
+		}
+	}
+
+	for (const atrule of atrules) {
+		try {
+			if (atrule.params && atrule.params.includes("(")) {
+				atrule.params = ReplaceInterpolations(atrule.params, (_expr) => context.Evaluate(_expr, valueScope));
+			}
+		} catch (error) {
+			throw atrule.error(`microCSS: ${error.message}`);
+		}
+	}
+
+	return document;
+}