@anvpx/motion-templates 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 anvpx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/** Built-in templates (data only). Callers pass this directory to the template loader as a search root. */
+export declare const TEMPLATES_DIR: string;
+/** Themes shared between templates; a manifest reaches them as `@shared/<name>.json`. */
+export declare const SHARED_THEMES_DIR: string;
+export type { NpmTemplateRoot } from "./roots.ts";
+export { isNpmTemplatePackageName, listNpmTemplateRoots } from "./roots.ts";
+/** Search stopwords for `mk template list --for`; the CLI hands them to the build search (build never imports this package). */
+export declare const STOPWORDS: readonly string[];

package/dist/index.js

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** Built-in templates (data only). Callers pass this directory to the template loader as a search root. */
+export const TEMPLATES_DIR = fileURLToPath(new URL("../templates/", import.meta.url));
+/** Themes shared between templates; a manifest reaches them as `@shared/<name>.json`. */
+export const SHARED_THEMES_DIR = fileURLToPath(new URL("../shared/themes/", import.meta.url));
+export { isNpmTemplatePackageName, listNpmTemplateRoots } from "./roots.js";
+/** Search stopwords for `mk template list --for`; the CLI hands them to the build search (build never imports this package). */
+export const STOPWORDS = JSON.parse(readFileSync(fileURLToPath(new URL("../stopwords.json", import.meta.url)), "utf8"));

package/dist/roots.d.ts

@@ -0,0 +1,41 @@
+/**
+ * npm-installed template roots (opt-in).
+ *
+ * A package counts as a template package by name convention (no new deps, no
+ * registry lookup):
+ * - unscoped `mk-template-*` or `motion-kit-template-*` (docs order also
+ *   allows the `motion-kit-template-*` spelling),
+ * - scoped `@literal-scope/mk-template-*` (e.g. `@acme/mk-template-report`),
+ * - scoped `@anvpx/motion-template-*` (the docs spelling).
+ *
+ * Layout inside a package: `<pkg>/templates/<id>/template.json` (multi-template,
+ * preferred, matches `discoverTemplates` manifest layout) or `<pkg>/template.json`
+ * (single-template package). Packages with neither are skipped.
+ *
+ * Precedence (decided + documented): built-ins win on id clash. Pass the roots
+ * from `listNpmTemplateRoots` AFTER `builtInDir` when calling `discoverTemplates`
+ * (project > env > user > built-in > npm). The npm copy then shows up as
+ * `shadowed` with reason `"root"` — a warning, never silent. Rationale: built-ins
+ * are pinned, snapshot-tested and deterministic; externals must use new ids
+ * (fork flow), not silently override core templates.
+ *
+ * Validation is fail-closed: discovery reports unparseable manifests in
+ * `problems`, and `loadTemplate`/`validateTemplate` (same functions as built-ins)
+ * return errors for incomplete externals. External templates own their assets:
+ * no ledger merge; ship licences inside the package.
+ */
+/** One npm package's contribution: a directory holding `<id>/template.json` folders. */
+export interface NpmTemplateRoot {
+    readonly path: string;
+    /** `npm:<packageName>`, e.g. `npm:@acme/mk-template-report`. */
+    readonly source: string;
+    readonly packageName: string;
+}
+/** True when the (possibly scoped) package name follows the template convention. */
+export declare const isNpmTemplatePackageName: (packageName: string) => boolean;
+/**
+ * Roots contributed by npm template packages under `<projectDir>/node_modules`
+ * (or an explicit `nodeModulesDir` for tests). Sorted by package name; missing
+ * or unreadable `node_modules` yields `[]`, never throws.
+ */
+export declare const listNpmTemplateRoots: (projectDir: string, nodeModulesDir?: string) => NpmTemplateRoot[];

package/dist/roots.js

@@ -0,0 +1,81 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+const matchesBase = (base) => (base.startsWith("mk-template-") && base.length > 12) ||
+    (base.startsWith("motion-kit-template-") && base.length > 21) ||
+    (base.startsWith("motion-template-") && base.length > 16);
+/** True when the (possibly scoped) package name follows the template convention. */
+export const isNpmTemplatePackageName = (packageName) => {
+    const parts = packageName.split("/");
+    if (parts.length === 1) {
+        const [base] = parts;
+        if (base === undefined || base === "")
+            return false;
+        return matchesBase(base);
+    }
+    if (parts.length !== 2)
+        return false;
+    const [scope, base] = parts;
+    if (scope === undefined || !scope.startsWith("@") || base === undefined || base === "") {
+        return false;
+    }
+    if (scope === "@anvpx") {
+        return matchesBase(base) || (base.startsWith("template-") && base.length > 9);
+    }
+    return matchesBase(base);
+};
+const isDirectory = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const rootForPackage = (pkgDir) => {
+    const nested = join(pkgDir, "templates");
+    if (isDirectory(nested))
+        return nested;
+    if (existsSync(join(pkgDir, "template.json")))
+        return pkgDir;
+    return undefined;
+};
+const readDirSafe = (dir) => {
+    try {
+        return readdirSync(dir).sort();
+    }
+    catch {
+        return [];
+    }
+};
+const scopedNames = (base, scope) => readDirSafe(join(base, scope))
+    .filter((child) => !child.startsWith("."))
+    .map((child) => `${scope}/${child}`);
+/** All installed package names, with `@scope` dirs expanded; hidden entries skipped. */
+const expandPackageNames = (base, entries) => entries
+    .filter((entry) => !entry.startsWith("."))
+    .flatMap((entry) => (entry.startsWith("@") ? scopedNames(base, entry) : [entry]));
+const rootForName = (base, packageName) => {
+    if (!isNpmTemplatePackageName(packageName))
+        return undefined;
+    const pkgDir = join(base, ...packageName.split("/"));
+    if (!isDirectory(pkgDir))
+        return undefined;
+    const path = rootForPackage(pkgDir);
+    if (path === undefined)
+        return undefined;
+    return { path, source: `npm:${packageName}`, packageName };
+};
+/**
+ * Roots contributed by npm template packages under `<projectDir>/node_modules`
+ * (or an explicit `nodeModulesDir` for tests). Sorted by package name; missing
+ * or unreadable `node_modules` yields `[]`, never throws.
+ */
+export const listNpmTemplateRoots = (projectDir, nodeModulesDir) => {
+    const base = nodeModulesDir ?? join(projectDir, "node_modules");
+    return expandPackageNames(base, readDirSafe(base))
+        .flatMap((packageName) => {
+        const root = rootForName(base, packageName);
+        return root === undefined ? [] : [root];
+    })
+        .sort((a, b) => a.packageName.localeCompare(b.packageName));
+};

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@anvpx/motion-templates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Built-in templates, blueprints and shared themes for @anvpx/motion.",
+  "license": "MIT",
+  "author": "anvpx",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "motion-kit",
+    "templates",
+    "themes",
+    "video",
+    "animation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "templates/**/*",
+    "shared/themes/**/*",
+    "stopwords.json"
+  ],
+  "devDependencies": {
+    "@anvpx/motion-build": "0.1.1",
+    "@anvpx/motion-schema": "0.1.1"
+  },
+  "scripts": {}
 }

package/shared/themes/README.md

@@ -0,0 +1,5 @@
+# Shared themes
+
+Theme files referenced by templates as `"file": "@shared/<name>.json"`. The loader reads them from this folder; a theme id is its file name without `.json`.
+
+Sixteen files: nine families (`calm`, `bold`, `data`, `editorial`, `tech`, `playful`, `pop`, `warm`) in `-light` and `-dark`. Family table, fonts and guarantees: `../README.md`; motion presets: `../styles-guide.md`.

package/shared/themes/bold-dark.json

@@ -0,0 +1,362 @@
+{
+  "$description": "bold: deep violet ground with an amber highlight (dark), DTCG format",
+  "color": {
+    "$type": "color",
+    "bg": {
+      "$value": "#120a26"
+    },
+    "bgEnd": {
+      "$value": "#1c1040"
+    },
+    "glow": {
+      "$value": "#4a2a9a"
+    },
+    "glow2": {
+      "$value": "#6b4300"
+    },
+    "surface": {
+      "$value": "#1a0f38"
+    },
+    "card": {
+      "$value": "#241651"
+    },
+    "divider": {
+      "$value": "#43307f"
+    },
+    "accentSoft": {
+      "$value": "#3a2275"
+    },
+    "fg": {
+      "$value": "#f7f2ff"
+    },
+    "muted": {
+      "$value": "#c6b9ea"
+    },
+    "accent": {
+      "$value": "#ffb524"
+    },
+    "accent2": {
+      "$value": "#b9a2ff"
+    },
+    "onAccent": {
+      "$value": "#1a0f00"
+    },
+    "onAccent2": {
+      "$value": "#170a3a"
+    },
+    "deep": {
+      "$value": "#2f1673"
+    },
+    "deepEnd": {
+      "$value": "#1a0b45"
+    },
+    "onDeep": {
+      "$value": "#ffffff"
+    },
+    "onDeepMuted": {
+      "$value": "#d4c8f5"
+    }
+  },
+  "chart": {
+    "1": {
+      "$value": "#ffb524"
+    },
+    "2": {
+      "$value": "#b9a2ff"
+    },
+    "3": {
+      "$value": "#4fd8b8"
+    },
+    "4": {
+      "$value": "#ff6fb0"
+    },
+    "5": {
+      "$value": "#6fa8ff"
+    },
+    "6": {
+      "$value": "#c8e65a"
+    },
+    "7": {
+      "$value": "#ff7a5a"
+    },
+    "8": {
+      "$value": "#c6b9ea"
+    },
+    "$type": "color"
+  },
+  "font": {
+    "$type": "fontFamily",
+    "sans": {
+      "$value": ["Inter", "system-ui", "sans-serif"]
+    },
+    "display": {
+      "$value": ["Space Grotesk", "system-ui", "sans-serif"]
+    },
+    "mono": {
+      "$value": ["ui-monospace", "SFMono-Regular", "Menlo", "Consolas", "monospace"]
+    }
+  },
+  "fontSize": {
+    "$type": "dimension",
+    "sm": {
+      "$value": "28px"
+    },
+    "md": {
+      "$value": "32px"
+    },
+    "lg": {
+      "$value": "52px"
+    },
+    "xl": {
+      "$value": "80px"
+    },
+    "title": {
+      "$value": "108px"
+    },
+    "display": {
+      "$value": "144px"
+    },
+    "heroSm": {
+      "$value": "176px"
+    },
+    "heroMd": {
+      "$value": "260px"
+    },
+    "hero": {
+      "$value": "380px"
+    }
+  },
+  "spacing": {
+    "$type": "dimension",
+    "xs": {
+      "$value": "4px"
+    },
+    "sm": {
+      "$value": "8px"
+    },
+    "md": {
+      "$value": "16px"
+    },
+    "lg": {
+      "$value": "32px"
+    },
+    "xl": {
+      "$value": "64px"
+    },
+    "xxl": {
+      "$value": "96px"
+    }
+  },
+  "radius": {
+    "$type": "dimension",
+    "sm": {
+      "$value": "6px"
+    },
+    "md": {
+      "$value": "12px"
+    },
+    "lg": {
+      "$value": "20px"
+    },
+    "xl": {
+      "$value": "32px"
+    },
+    "full": {
+      "$value": "9999px"
+    }
+  },
+  "opacity": {
+    "$type": "number",
+    "subtle": {
+      "$value": 0.7
+    },
+    "medium": {
+      "$value": 0.85
+    },
+    "full": {
+      "$value": 1
+    }
+  },
+  "duration": {
+    "$type": "duration",
+    "fast": {
+      "$value": "150ms"
+    },
+    "base": {
+      "$value": "300ms"
+    },
+    "slow": {
+      "$value": "600ms"
+    }
+  },
+  "status": {
+    "$type": "color",
+    "good": {
+      "$value": "#4ade80"
+    },
+    "warn": {
+      "$value": "#fbbf24"
+    },
+    "bad": {
+      "$value": "#fb7185"
+    }
+  },
+  "stroke": {
+    "$type": "dimension",
+    "card": {
+      "$value": "0px"
+    },
+    "icon": {
+      "$value": "1.75px"
+    }
+  },
+  "numeric": {
+    "mode": {
+      "$type": "string",
+      "$value": "tabular"
+    }
+  },
+  "shadow": {
+    "mode": {
+      "$type": "string",
+      "$value": "soft"
+    },
+    "color": {
+      "$type": "color",
+      "$value": "#f7f2ff"
+    }
+  },
+  "$extensions": {
+    "motion-kit": {
+      "family": "bold",
+      "mode": "dark",
+      "pair": "bold-light",
+      "textPairs": [
+        {
+          "fg": "fg",
+          "bg": "bg"
+        },
+        {
+          "fg": "fg",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "fg",
+          "bg": "glow"
+        },
+        {
+          "fg": "fg",
+          "bg": "glow2"
+        },
+        {
+          "fg": "fg",
+          "bg": "surface"
+        },
+        {
+          "fg": "fg",
+          "bg": "card"
+        },
+        {
+          "fg": "fg",
+          "bg": "accentSoft"
+        },
+        {
+          "fg": "muted",
+          "bg": "bg"
+        },
+        {
+          "fg": "muted",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "muted",
+          "bg": "glow"
+        },
+        {
+          "fg": "muted",
+          "bg": "glow2"
+        },
+        {
+          "fg": "muted",
+          "bg": "surface"
+        },
+        {
+          "fg": "muted",
+          "bg": "card"
+        },
+        {
+          "fg": "muted",
+          "bg": "accentSoft"
+        },
+        {
+          "fg": "accent",
+          "bg": "bg"
+        },
+        {
+          "fg": "accent",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "accent",
+          "bg": "glow"
+        },
+        {
+          "fg": "accent",
+          "bg": "glow2"
+        },
+        {
+          "fg": "accent",
+          "bg": "surface"
+        },
+        {
+          "fg": "accent",
+          "bg": "card"
+        },
+        {
+          "fg": "accent",
+          "bg": "accentSoft"
+        },
+        {
+          "fg": "accent2",
+          "bg": "bg"
+        },
+        {
+          "fg": "accent2",
+          "bg": "bgEnd"
+        },
+        {
+          "fg": "accent2",
+          "bg": "surface"
+        },
+        {
+          "fg": "accent2",
+          "bg": "card"
+        },
+        {
+          "fg": "onAccent",
+          "bg": "accent"
+        },
+        {
+          "fg": "onAccent2",
+          "bg": "accent2"
+        },
+        {
+          "fg": "onDeep",
+          "bg": "deep"
+        },
+        {
+          "fg": "onDeep",
+          "bg": "deepEnd"
+        },
+        {
+          "fg": "onDeepMuted",
+          "bg": "deep"
+        },
+        {
+          "fg": "onDeepMuted",
+          "bg": "deepEnd"
+        }
+      ]
+    }
+  }
+}