@ispriter/core 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 iazrael.
+
+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/chunk-3JTOVWUA.js

@@ -0,0 +1,111 @@
+// src/packer.ts
+function pack(blocks, margin = 0) {
+  if (blocks.length === 0) return { placed: [], unfit: [] };
+  const sorted = [...blocks].sort((a, b) => b.width * b.height - a.width * a.height);
+  const packerBlocks = sorted.map((b) => ({
+    x: 0,
+    y: 0,
+    w: b.width + margin,
+    h: b.height + margin,
+    data: b.data
+  }));
+  const packer = new GrowingPacker();
+  packer.fit(packerBlocks);
+  const placed = [];
+  const unfit = [];
+  for (let i = 0; i < packerBlocks.length; i++) {
+    const b = packerBlocks[i];
+    if (b.fit) {
+      placed.push({
+        width: b.w - margin,
+        height: b.h - margin,
+        x: b.fit.x,
+        y: b.fit.y,
+        rotated: false,
+        data: b.data
+      });
+    } else {
+      unfit.push(sorted[i]);
+      console.warn(`[ispriter] Image could not be packed (too large): skipping`);
+    }
+  }
+  return { placed, unfit };
+}
+var GrowingPacker = class {
+  root;
+  fit(blocks) {
+    const first = blocks[0];
+    this.root = { x: 0, y: 0, w: first.w, h: first.h };
+    for (const block of blocks) {
+      const node = this.findNode(this.root, block.w, block.h);
+      if (node) {
+        block.fit = { x: node.x, y: node.y, w: node.w, h: node.h };
+        this.splitNode(node, block.w, block.h);
+      } else {
+        const result = this.growNode(block.w, block.h);
+        if (result) {
+          block.fit = { x: result.x, y: result.y, w: result.w, h: result.h };
+          this.splitNode(result, block.w, block.h);
+        }
+      }
+    }
+  }
+  findNode(root, w, h) {
+    if (root.used) {
+      return this.findNode(root.right, w, h) || this.findNode(root.down, w, h);
+    }
+    if (w <= root.w && h <= root.h) {
+      return root;
+    }
+    return null;
+  }
+  splitNode(node, w, h) {
+    node.used = true;
+    node.down = { x: node.x, y: node.y + h, w: node.w, h: node.h - h };
+    node.right = { x: node.x + w, y: node.y, w: node.w - w, h };
+  }
+  growNode(w, h) {
+    const canGrowDown = w <= this.root.w;
+    const canGrowRight = h <= this.root.h;
+    const shouldGrowDown = canGrowDown && this.root.w >= this.root.h;
+    const shouldGrowRight = canGrowRight && this.root.h >= this.root.w;
+    if (shouldGrowRight) {
+      return this.growRight(w, h);
+    } else if (shouldGrowDown) {
+      return this.growDown(w, h);
+    } else if (canGrowRight) {
+      return this.growRight(w, h);
+    } else if (canGrowDown) {
+      return this.growDown(w, h);
+    }
+    return null;
+  }
+  growRight(w, h) {
+    this.root = {
+      used: true,
+      x: 0,
+      y: 0,
+      w: this.root.w + w,
+      h: this.root.h,
+      down: this.root,
+      right: { x: this.root.w, y: 0, w, h: this.root.h }
+    };
+    return this.findNode(this.root, w, h);
+  }
+  growDown(w, h) {
+    this.root = {
+      used: true,
+      x: 0,
+      y: 0,
+      w: this.root.w,
+      h: this.root.h + h,
+      down: { x: 0, y: this.root.h, w: this.root.w, h },
+      right: this.root
+    };
+    return this.findNode(this.root, w, h);
+  }
+};
+
+export {
+  pack
+};

package/dist/index.d.ts

@@ -0,0 +1,284 @@
+import { ErrorCode } from '@ispriter/shared';
+import { z } from 'zod';
+import { Rule } from 'postcss';
+
+declare class IspriterError extends Error {
+    readonly code: ErrorCode;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: ErrorCode, context?: Record<string, unknown> | undefined);
+}
+
+declare const SpriterConfigSchema: z.ZodObject<{
+    workspace: z.ZodDefault<z.ZodString>;
+    input: z.ZodObject<{
+        cssSource: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+        ignoreImages: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    }, "strip", z.ZodTypeAny, {
+        cssSource: string | string[];
+        ignoreImages?: string | string[] | undefined;
+    }, {
+        cssSource: string | string[];
+        ignoreImages?: string | string[] | undefined;
+    }>;
+    output: z.ZodObject<{
+        cssDist: z.ZodString;
+        imageDist: z.ZodDefault<z.ZodString>;
+        format: z.ZodDefault<z.ZodEnum<["png", "webp"]>>;
+        quality: z.ZodDefault<z.ZodNumber>;
+        retina: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
+        maxSingleSize: z.ZodOptional<z.ZodNumber>;
+        margin: z.ZodDefault<z.ZodNumber>;
+        prefix: z.ZodDefault<z.ZodString>;
+        compress: z.ZodDefault<z.ZodUnion<[z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        combine: z.ZodDefault<z.ZodBoolean>;
+        combineCSSRule: z.ZodDefault<z.ZodBoolean>;
+        unit: z.ZodDefault<z.ZodEnum<["px", "rem"]>>;
+        remBase: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        cssDist: string;
+        imageDist: string;
+        format: "png" | "webp";
+        quality: number;
+        margin: number;
+        prefix: string;
+        compress: boolean | Record<string, unknown>;
+        combine: boolean;
+        combineCSSRule: boolean;
+        unit: "px" | "rem";
+        remBase: number;
+        retina?: 2 | 3 | undefined;
+        maxSingleSize?: number | undefined;
+    }, {
+        cssDist: string;
+        imageDist?: string | undefined;
+        format?: "png" | "webp" | undefined;
+        quality?: number | undefined;
+        retina?: 2 | 3 | undefined;
+        maxSingleSize?: number | undefined;
+        margin?: number | undefined;
+        prefix?: string | undefined;
+        compress?: boolean | Record<string, unknown> | undefined;
+        combine?: boolean | undefined;
+        combineCSSRule?: boolean | undefined;
+        unit?: "px" | "rem" | undefined;
+        remBase?: number | undefined;
+    }>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        images: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        images: string | string[];
+    }, {
+        name: string;
+        images: string | string[];
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    workspace: string;
+    input: {
+        cssSource: string | string[];
+        ignoreImages?: string | string[] | undefined;
+    };
+    output: {
+        cssDist: string;
+        imageDist: string;
+        format: "png" | "webp";
+        quality: number;
+        margin: number;
+        prefix: string;
+        compress: boolean | Record<string, unknown>;
+        combine: boolean;
+        combineCSSRule: boolean;
+        unit: "px" | "rem";
+        remBase: number;
+        retina?: 2 | 3 | undefined;
+        maxSingleSize?: number | undefined;
+    };
+    groups?: {
+        name: string;
+        images: string | string[];
+    }[] | undefined;
+}, {
+    input: {
+        cssSource: string | string[];
+        ignoreImages?: string | string[] | undefined;
+    };
+    output: {
+        cssDist: string;
+        imageDist?: string | undefined;
+        format?: "png" | "webp" | undefined;
+        quality?: number | undefined;
+        retina?: 2 | 3 | undefined;
+        maxSingleSize?: number | undefined;
+        margin?: number | undefined;
+        prefix?: string | undefined;
+        compress?: boolean | Record<string, unknown> | undefined;
+        combine?: boolean | undefined;
+        combineCSSRule?: boolean | undefined;
+        unit?: "px" | "rem" | undefined;
+        remBase?: number | undefined;
+    };
+    workspace?: string | undefined;
+    groups?: {
+        name: string;
+        images: string | string[];
+    }[] | undefined;
+}>;
+type SpriterConfig = z.input<typeof SpriterConfigSchema>;
+type ResolvedConfig = z.output<typeof SpriterConfigSchema>;
+declare function normalizeConfig(input: string | SpriterConfig): SpriterConfig;
+declare function parseConfig(raw: unknown): ResolvedConfig;
+
+/** 待打包的图片块 */
+interface PackInput<T = unknown> {
+    width: number;
+    height: number;
+    data: T;
+}
+/** 打包后的定位结果 */
+interface PackResult<T = unknown> {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    rotated: boolean;
+    data: T;
+}
+/** 图片资产信息 */
+interface ImageAsset {
+    url: string;
+    buffer: Buffer;
+    naturalWidth: number;
+    naturalHeight: number;
+    rules: BackgroundRule[];
+}
+
+/** CSS background 规则提取结果 */
+interface BackgroundRule {
+    file: string;
+    selector: string;
+    imageUrl: string;
+    position: {
+        x: number | string;
+        y: number | string;
+    };
+    size?: {
+        w: number;
+        h: number;
+    };
+    repeat: string;
+    node: Rule;
+    inAnimation: boolean;
+}
+/** Spriter.run() 输入 */
+interface SpriterRunInput {
+    css: Map<string, string>;
+    images: Map<string, Buffer>;
+    cssBaseDir: string;
+}
+/** 打包后的精灵图条目 */
+interface PackedSprite {
+    spriteFile: string;
+    canvasWidth: number;
+    canvasHeight: number;
+    items: Array<{
+        asset: ImageAsset;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+}
+/** Spriter.run() 输出 */
+interface SpriterResult {
+    cssFiles: Map<string, string>;
+    spriteImages: Map<string, Buffer>;
+    manifest: Map<string, {
+        spriteFile: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    skippedImages: string[];
+}
+
+interface PackOutput<T> {
+    placed: PackResult<T>[];
+    unfit: PackInput<T>[];
+}
+declare function pack<T>(blocks: PackInput<T>[], margin?: number): PackOutput<T>;
+
+/**
+ * 从多个 CSS 文件中提取所有 background 规则
+ * Fix #15/#18: 自动展开 @import
+ */
+declare function extractBackgrounds(cssContents: Map<string, string>): Promise<BackgroundRule[]>;
+
+interface ParsedBackground {
+    imageUrl: string | null;
+    positionX: string | number;
+    positionY: string | number;
+    repeat: string;
+    size: string;
+}
+/**
+ * 分析 background 简写属性
+ * 提取 url、position、repeat、size
+ */
+declare function analyseBackground(value: string): ParsedBackground;
+/**
+ * 检查是否应该跳过该规则（right/center/bottom position 或 repeat）
+ */
+declare function shouldSkip(parsed: ParsedBackground): boolean;
+/**
+ * 清理 URL 中的 hash 和 query string，统一使用 shared cleanUrl
+ */
+declare function cleanImageUrl(url: string): string;
+/**
+ * 判断是否为 #unsprite 标记
+ */
+declare function isUnsprite(url: string): boolean;
+
+interface RetinaInfo {
+    width: number;
+    height: number;
+    scale: number;
+}
+/**
+ * 更新 CSS 内容：替换 background-image url 和 background-position
+ * Fix #8: 支持传入 retinaInfo，自动添加 background-size
+ * Fix #12: 支持 combineCSSRule 合并同一精灵图的选择器
+ */
+declare function emitCSS(cssContents: Map<string, string>, packedSprites: PackedSprite[], config: ResolvedConfig, retinaInfo?: Map<string, RetinaInfo>): Promise<Map<string, string>>;
+
+/**
+ * 根据打包结果生成精灵图 Buffer
+ */
+declare function generateSprites(packedSprites: PackedSprite[], config: ResolvedConfig): Promise<Map<string, Buffer>>;
+
+declare class Spriter {
+    private config;
+    constructor(config: SpriterConfig);
+    run(input: SpriterRunInput): Promise<SpriterResult>;
+    private buildSpriteTasks;
+    /** B1: Promise.allSettled with error handling */
+    private fillImageSizes;
+    /** Fix #14: 按 groups 配置分桶 */
+    private groupAssets;
+    private packSprites;
+    /** Fix #13: 按 maxSingleSize 拆分精灵图 */
+    private splitByMaxSize;
+    private buildManifest;
+}
+
+interface PluginRunOptions {
+    config: SpriterConfig;
+    outputDir: string;
+}
+/**
+ * Common sprite generation flow shared by CLI and build plugins.
+ */
+declare function runSpriteGeneration(options: PluginRunOptions): Promise<void>;
+
+export { type BackgroundRule, type ImageAsset, IspriterError, type PackInput, type PackOutput, type PackResult, type PackedSprite, type PluginRunOptions, type ResolvedConfig, Spriter, type SpriterConfig, SpriterConfigSchema, type SpriterResult, type SpriterRunInput, analyseBackground, cleanImageUrl, emitCSS, extractBackgrounds, generateSprites, isUnsprite, normalizeConfig, pack, parseConfig, runSpriteGeneration, shouldSkip };

package/dist/index.js

@@ -0,0 +1,658 @@
+import {
+  pack
+} from "./chunk-3JTOVWUA.js";
+
+// src/error.ts
+var IspriterError = class extends Error {
+  constructor(message, code, context) {
+    super(message);
+    this.code = code;
+    this.context = context;
+    this.name = "IspriterError";
+  }
+  code;
+  context;
+};
+
+// src/config.ts
+import { z } from "zod";
+var SpriterConfigSchema = z.object({
+  workspace: z.string().default("./"),
+  input: z.object({
+    cssSource: z.union([z.string(), z.array(z.string())]),
+    ignoreImages: z.union([z.string(), z.array(z.string())]).optional()
+  }),
+  output: z.object({
+    cssDist: z.string(),
+    imageDist: z.string().default("./img/"),
+    format: z.enum(["png", "webp"]).default("png"),
+    quality: z.number().min(1).max(100).default(80),
+    retina: z.union([z.literal(2), z.literal(3)]).optional(),
+    maxSingleSize: z.number().positive().optional(),
+    margin: z.number().nonnegative().default(2),
+    prefix: z.string().default("sprite_"),
+    compress: z.union([z.boolean(), z.record(z.unknown())]).default(false),
+    combine: z.boolean().default(false),
+    combineCSSRule: z.boolean().default(true),
+    unit: z.enum(["px", "rem"]).default("px"),
+    remBase: z.number().positive().default(16)
+  }),
+  groups: z.array(z.object({
+    name: z.string(),
+    images: z.union([z.string(), z.array(z.string())])
+  })).optional()
+});
+function normalizeConfig(input) {
+  if (typeof input === "string") {
+    return { input: { cssSource: input }, output: { cssDist: input } };
+  }
+  return input;
+}
+function parseConfig(raw) {
+  if (raw !== null && raw !== void 0 && typeof raw !== "string" && typeof raw !== "object") {
+    throw new IspriterError("Config must be a string or object", "CONFIG_INVALID");
+  }
+  const config = normalizeConfig(raw);
+  const result = SpriterConfigSchema.safeParse(config);
+  if (!result.success) {
+    throw new IspriterError(
+      `Invalid config: ${result.error.issues.map((i) => i.message).join(", ")}`,
+      "CONFIG_INVALID",
+      { issues: result.error.issues }
+    );
+  }
+  validateNoTraversal(result.data.workspace, "workspace");
+  validateNoTraversal(result.data.output.cssDist, "output.cssDist");
+  validateNoTraversal(result.data.output.imageDist, "output.imageDist");
+  return result.data;
+}
+function validateNoTraversal(pathStr, fieldName) {
+  if (pathStr.includes("..")) {
+    throw new IspriterError(
+      `Path traversal detected in ${fieldName}: "${pathStr}"`,
+      "CONFIG_INVALID",
+      { field: fieldName }
+    );
+  }
+}
+
+// src/css/parser.ts
+import postcss2 from "postcss";
+
+// src/css/background.ts
+import { cleanUrl as sharedCleanUrl } from "@ispriter/shared";
+function analyseBackground(value) {
+  const result = {
+    imageUrl: null,
+    positionX: "0",
+    positionY: "0",
+    repeat: "no-repeat",
+    size: ""
+  };
+  const urlMatch = value.match(/url\(['"]?([^'")]+)['"]?\)/);
+  if (urlMatch) {
+    result.imageUrl = urlMatch[1];
+  }
+  if (/\bno-repeat\b/i.test(value)) result.repeat = "no-repeat";
+  else if (/\brepeat-x\b/i.test(value)) result.repeat = "repeat-x";
+  else if (/\brepeat-y\b/i.test(value)) result.repeat = "repeat-y";
+  else if (/\brepeat\b/i.test(value)) result.repeat = "repeat";
+  const sizeMatch = value.match(/\/\s*(.+?)(?:\s|$)/);
+  if (sizeMatch) {
+    result.size = sizeMatch[1].trim();
+  }
+  if (result.imageUrl) {
+    const afterUrl = value.replace(/url\([^)]*\)/, "").trim();
+    const posTokens = afterUrl.split(/\s+/).filter((t) => t && !["no-repeat", "repeat", "repeat-x", "repeat-y", "repeat-space"].includes(t)).filter((t) => !t.startsWith("/") && !t.startsWith("#"));
+    if (posTokens.length >= 1) {
+      result.positionX = parsePositionValue(posTokens[0]);
+    }
+    if (posTokens.length >= 2) {
+      result.positionY = parsePositionValue(posTokens[1]);
+    }
+  }
+  return result;
+}
+function parsePositionValue(val) {
+  if (val === "left" || val === "top") return 0;
+  if (val === "center") return "center";
+  if (val === "right" || val === "bottom") return "100%";
+  const pxMatch = val.match(/^(-?\d+(?:\.\d+)?)px$/i);
+  if (pxMatch) return Number(pxMatch[1]);
+  if (val.endsWith("%")) return val;
+  return val;
+}
+function shouldSkip(parsed) {
+  if (parsed.repeat === "repeat" || parsed.repeat === "repeat-x" || parsed.repeat === "repeat-y") {
+    return true;
+  }
+  if (parsed.positionX === "100%" || parsed.positionY === "100%") return true;
+  if (parsed.positionX === "center" || parsed.positionY === "center") return true;
+  if (typeof parsed.positionX === "string" && parsed.positionX.endsWith("%") && parsed.positionX !== "100%") return true;
+  if (typeof parsed.positionY === "string" && parsed.positionY.endsWith("%") && parsed.positionY !== "100%") return true;
+  return false;
+}
+function cleanImageUrl(url) {
+  if (url.length > 4096) return url;
+  if (url.includes("#unsprite")) return url;
+  return sharedCleanUrl(url);
+}
+function isUnsprite(url) {
+  return url.includes("#unsprite");
+}
+
+// src/css/imports.ts
+import postcss from "postcss";
+import postcssImport from "postcss-import";
+async function expandImports(css, fromFile) {
+  try {
+    const result = await postcss([postcssImport()]).process(css, { from: fromFile });
+    return result.css;
+  } catch (e) {
+    throw new IspriterError(
+      `Failed to expand @import in ${fromFile}: ${e.message}`,
+      "CSS_PARSE_ERROR",
+      { file: fromFile }
+    );
+  }
+}
+
+// src/css/parser.ts
+async function extractBackgrounds(cssContents) {
+  const rules = [];
+  for (const [filename, css] of cssContents) {
+    try {
+      let expandedCss = css;
+      if (css.includes("@import")) {
+        try {
+          expandedCss = await expandImports(css, filename);
+        } catch {
+        }
+      }
+      const root = postcss2.parse(expandedCss);
+      processRules(root, filename, false, rules);
+      root.walkAtRules(/keyframes/i, (atRule) => {
+        if (atRule.nodes) {
+          const kfRoot = postcss2.parse(atRule.toString().replace(/@[^{]+\{/, "").replace(/\}$/, ""));
+          processRules(kfRoot, filename, true, rules);
+        }
+      });
+    } catch (e) {
+      if (e.message?.includes("At-rule")) continue;
+      throw e;
+    }
+  }
+  return rules;
+}
+function processRules(root, file, inAnimation, results) {
+  root.walkRules((rule) => {
+    const bgDecls = [];
+    const sizeDecls = [];
+    for (const node of rule.nodes) {
+      if (node.type === "decl") {
+        const decl = node;
+        if (decl.prop === "background" || decl.prop === "background-image") {
+          bgDecls.push(decl);
+        }
+        if (decl.prop === "background-size") {
+          sizeDecls.push(decl);
+        }
+      }
+    }
+    for (const decl of bgDecls) {
+      const parsed = analyseBackground(decl.value);
+      if (!parsed.imageUrl) continue;
+      if (isUnsprite(parsed.imageUrl)) continue;
+      const hasSize = sizeDecls.length > 0;
+      if (shouldSkip(parsed)) continue;
+      const cleanUrl = cleanImageUrl(parsed.imageUrl);
+      results.push({
+        file,
+        selector: rule.selector,
+        imageUrl: cleanUrl,
+        position: { x: parsed.positionX, y: parsed.positionY },
+        repeat: parsed.repeat,
+        node: rule,
+        inAnimation,
+        ...hasSize ? { size: parseSizeDecl(sizeDecls[0]) } : {}
+      });
+    }
+  });
+}
+function parseSizeDecl(decl) {
+  const parts = decl.value.split(/\s+/);
+  const first = parts[0];
+  if (!/^-?\d+(\.\d+)?(px)?$/.test(first)) return void 0;
+  const w = parseFloat(first) || 0;
+  const hStr = parts[1];
+  if (hStr && !/^-?\d+(\.\d+)?(px)?$/.test(hStr)) return void 0;
+  const h = hStr ? parseFloat(hStr) || w : w;
+  return { w, h };
+}
+
+// src/css/emitter.ts
+import postcss3 from "postcss";
+import CleanCSS from "clean-css";
+async function emitCSS(cssContents, packedSprites, config, retinaInfo) {
+  const urlToSprite = /* @__PURE__ */ new Map();
+  for (const sprite of packedSprites) {
+    for (const item of sprite.items) {
+      urlToSprite.set(item.asset.url, {
+        spriteFile: sprite.spriteFile,
+        x: item.x,
+        y: item.y,
+        w: item.width,
+        h: item.height
+      });
+    }
+  }
+  const results = /* @__PURE__ */ new Map();
+  for (const [filename, css] of cssContents) {
+    try {
+      const root = postcss3.parse(css);
+      const spriteSelectors = /* @__PURE__ */ new Map();
+      root.walkRules((rule) => {
+        for (const node of rule.nodes) {
+          if (node.type === "decl") {
+            const decl = node;
+            if (decl.prop === "background" || decl.prop === "background-image") {
+              const urlMatch = decl.value.match(/url\(['"]?([^'")]+)['"]?\)/);
+              if (!urlMatch) continue;
+              const originalUrl = cleanImageUrl(urlMatch[1]);
+              const mapping = urlToSprite.get(originalUrl);
+              if (!mapping) continue;
+              const newUrl = `${config.output.imageDist}${mapping.spriteFile}`;
+              decl.value = decl.value.replace(urlMatch[0], `url('${newUrl}')`);
+              const posX = convertUnit(-mapping.x, config);
+              const posY = convertUnit(-mapping.y, config);
+              let posDecl;
+              for (const n of rule.nodes) {
+                if (n.type === "decl" && n.prop === "background-position") {
+                  posDecl = n;
+                  break;
+                }
+              }
+              if (posDecl) {
+                posDecl.value = `${posX} ${posY}`;
+              } else {
+                rule.append({ prop: "background-position", value: `${posX} ${posY}` });
+              }
+              if (retinaInfo) {
+                const info = retinaInfo.get(originalUrl);
+                if (info) {
+                  const bgW = convertUnit(Math.round(info.width / info.scale), config);
+                  const bgH = convertUnit(Math.round(info.height / info.scale), config);
+                  let sizeDecl;
+                  for (const n of rule.nodes) {
+                    if (n.type === "decl" && n.prop === "background-size") {
+                      sizeDecl = n;
+                      break;
+                    }
+                  }
+                  if (sizeDecl) {
+                    sizeDecl.value = `${bgW} ${bgH}`;
+                  } else {
+                    rule.append({ prop: "background-size", value: `${bgW} ${bgH}` });
+                  }
+                }
+              }
+              if (config.output.combineCSSRule) {
+                const key = mapping.spriteFile;
+                if (!spriteSelectors.has(key)) {
+                  spriteSelectors.set(key, []);
+                }
+                spriteSelectors.get(key).push({ rule, decl });
+              }
+            }
+          }
+        }
+      });
+      if (config.output.combineCSSRule) {
+        for (const [, entries] of spriteSelectors) {
+          if (entries.length <= 1) continue;
+          const selectors = entries.map((e) => e.rule.selector);
+          const combinedRule = postcss3.rule({ selector: selectors.join(", ") });
+          const firstEntry = entries[0];
+          const bgImageDecl = firstEntry.decl.clone();
+          combinedRule.append(bgImageDecl);
+          for (const entry of entries) {
+            entry.decl.remove();
+          }
+          firstEntry.rule.before(combinedRule);
+        }
+      }
+      let output = root.toString();
+      if (config.output.compress) {
+        const cleaner = new CleanCSS(
+          typeof config.output.compress === "object" ? config.output.compress : {}
+        );
+        const minified = cleaner.minify(output);
+        if (minified.errors.length > 0) {
+          throw new IspriterError(`CSS compression failed: ${minified.errors.join(", ")}`, "OUTPUT_ERROR");
+        }
+        output = minified.styles;
+      }
+      results.set(filename, output);
+    } catch (e) {
+      if (e instanceof IspriterError) throw e;
+      throw new IspriterError(`Failed to emit CSS for ${filename}`, "OUTPUT_ERROR", { file: filename });
+    }
+  }
+  if (config.output.combine && results.size > 1) {
+    const combined = Array.from(results.values()).join("\n");
+    const combinedName = Array.from(results.keys())[0];
+    results.clear();
+    results.set(combinedName, combined);
+  }
+  return results;
+}
+function convertUnit(px, config) {
+  if (config.output.unit === "rem") {
+    return `${(px / config.output.remBase).toFixed(6).replace(/\.?0+$/, "")}rem`;
+  }
+  return `${px}px`;
+}
+
+// src/image/sprite.ts
+import sharp from "sharp";
+async function generateSprites(packedSprites, config) {
+  const results = /* @__PURE__ */ new Map();
+  for (const sprite of packedSprites) {
+    try {
+      const { canvasWidth, canvasHeight, items } = sprite;
+      const canvas = sharp({
+        create: {
+          width: canvasWidth,
+          height: canvasHeight,
+          channels: 4,
+          background: { r: 0, g: 0, b: 0, alpha: 0 }
+        }
+      });
+      const composites = await Promise.all(items.map(async (item) => {
+        let inputBuf = item.asset.buffer;
+        if (item.width !== item.asset.naturalWidth || item.height !== item.asset.naturalHeight) {
+          inputBuf = await sharp(item.asset.buffer).resize(item.width, item.height, { fit: "fill" }).toBuffer();
+        }
+        return { input: inputBuf, left: item.x, top: item.y };
+      }));
+      let output = canvas.composite(composites);
+      if (config.output.format === "webp") {
+        output = output.webp({ quality: config.output.quality });
+      } else {
+        output = output.png();
+      }
+      const buffer = await output.toBuffer();
+      results.set(sprite.spriteFile, buffer);
+    } catch (e) {
+      if (e instanceof IspriterError) throw e;
+      throw new IspriterError(`Failed to generate sprite: ${sprite.spriteFile}: ${e.message}`, "OUTPUT_ERROR", {
+        spriteFile: sprite.spriteFile,
+        cause: e
+      });
+    }
+  }
+  return results;
+}
+
+// src/spriter.ts
+import { matchesAny } from "@ispriter/shared";
+import sharp2 from "sharp";
+var Spriter = class {
+  config;
+  constructor(config) {
+    this.config = parseConfig(config);
+  }
+  async run(input) {
+    const { css, images } = input;
+    const rules = await extractBackgrounds(css);
+    const { assets, skipped } = this.buildSpriteTasks(rules, images);
+    await this.fillImageSizes(assets);
+    const assetGroups = this.groupAssets(assets);
+    const allPackedSprites = [];
+    for (let gi = 0; gi < assetGroups.length; gi++) {
+      const group = assetGroups[gi];
+      const packed = this.packSprites(group, gi);
+      allPackedSprites.push(...packed);
+    }
+    const finalSprites = this.splitByMaxSize(allPackedSprites);
+    const spriteImages = await generateSprites(finalSprites, this.config);
+    let retinaInfo;
+    if (this.config.output.retina) {
+      const { generateRetinaSprites } = await import("./retina-NHUTNCL6.js");
+      const scale = this.config.output.retina;
+      const { packedSprites: retinaPacked, scaledAssets } = await generateRetinaSprites(
+        assets,
+        this.config,
+        scale
+      );
+      const retinaImages = await generateSprites(retinaPacked, this.config);
+      for (const [name, buf] of retinaImages) {
+        spriteImages.set(name, buf);
+      }
+      retinaInfo = /* @__PURE__ */ new Map();
+      for (const [url, dims] of scaledAssets) {
+        retinaInfo.set(url, { width: dims.width, height: dims.height, scale });
+      }
+    }
+    const cssFiles = await emitCSS(css, finalSprites, this.config, retinaInfo);
+    const manifest = this.buildManifest(finalSprites);
+    return { cssFiles, spriteImages, manifest, skippedImages: skipped };
+  }
+  buildSpriteTasks(rules, images) {
+    const assetMap = /* @__PURE__ */ new Map();
+    const skipped = [];
+    const ignorePatterns = this.config.input.ignoreImages ? Array.isArray(this.config.input.ignoreImages) ? this.config.input.ignoreImages : [this.config.input.ignoreImages] : [];
+    for (const rule of rules) {
+      const url = rule.imageUrl;
+      if (ignorePatterns.length > 0 && matchesAny(ignorePatterns, url)) {
+        continue;
+      }
+      if (assetMap.has(url)) {
+        assetMap.get(url).rules.push(rule);
+        continue;
+      }
+      const buffer = images.get(url);
+      if (!buffer) {
+        skipped.push(url);
+        continue;
+      }
+      assetMap.set(url, {
+        url,
+        buffer,
+        naturalWidth: 0,
+        naturalHeight: 0,
+        rules: [rule]
+      });
+    }
+    return { assets: Array.from(assetMap.values()), skipped };
+  }
+  /** B1: Promise.allSettled with error handling */
+  async fillImageSizes(assets) {
+    const results = await Promise.allSettled(
+      assets.map(async (asset) => {
+        const meta = await sharp2(asset.buffer).metadata();
+        return { asset, width: meta.width || 0, height: meta.height || 0 };
+      })
+    );
+    for (const result of results) {
+      if (result.status === "fulfilled") {
+        result.value.asset.naturalWidth = result.value.width;
+        result.value.asset.naturalHeight = result.value.height;
+      } else {
+        console.warn(`Failed to read image metadata: ${result.reason}`);
+      }
+    }
+  }
+  /** Fix #14: 按 groups 配置分桶 */
+  groupAssets(assets) {
+    const groups = this.config.groups;
+    if (!groups || groups.length === 0) {
+      return [assets];
+    }
+    const buckets = groups.map(() => []);
+    const assigned = /* @__PURE__ */ new Set();
+    for (let gi = 0; gi < groups.length; gi++) {
+      const group = groups[gi];
+      const patterns = Array.isArray(group.images) ? group.images : [group.images];
+      for (const asset of assets) {
+        if (assigned.has(asset.url)) continue;
+        if (matchesAny(patterns, asset.url)) {
+          buckets[gi].push(asset);
+          assigned.add(asset.url);
+        }
+      }
+    }
+    const lastBucket = buckets[buckets.length - 1];
+    for (const asset of assets) {
+      if (!assigned.has(asset.url)) {
+        lastBucket.push(asset);
+      }
+    }
+    return buckets.filter((b) => b.length > 0);
+  }
+  packSprites(assets, groupIndex = 0) {
+    if (assets.length === 0) return [];
+    const inputs = assets.map((a) => ({
+      width: a.naturalWidth,
+      height: a.naturalHeight,
+      data: a
+    }));
+    const { placed: results, unfit } = pack(inputs, this.config.output.margin);
+    if (unfit.length > 0) {
+      console.warn(`[ispriter] ${unfit.length} image(s) could not be packed and were skipped`);
+    }
+    if (results.length === 0) return [];
+    const spriteFile = `${this.config.output.prefix}${groupIndex}.${this.config.output.format === "webp" ? "webp" : "png"}`;
+    return [
+      {
+        spriteFile,
+        canvasWidth: results.reduce((max, r) => Math.max(max, r.x + r.width), 0),
+        canvasHeight: results.reduce((max, r) => Math.max(max, r.y + r.height), 0),
+        items: results.map((r) => ({
+          asset: r.data,
+          x: r.x,
+          y: r.y,
+          width: r.width,
+          height: r.height
+        }))
+      }
+    ];
+  }
+  /** Fix #13: 按 maxSingleSize 拆分精灵图 */
+  splitByMaxSize(sprites) {
+    const maxSize = this.config.output.maxSingleSize;
+    if (!maxSize) return sprites;
+    const maxBytes = maxSize * 1024;
+    const result = [];
+    for (const sprite of sprites) {
+      const estimatedSize = sprite.canvasWidth * sprite.canvasHeight * 4;
+      if (estimatedSize <= maxBytes) {
+        result.push(sprite);
+        continue;
+      }
+      const mid = Math.ceil(sprite.items.length / 2);
+      const chunks = [sprite.items.slice(0, mid), sprite.items.slice(mid)];
+      for (let ci = 0; ci < chunks.length; ci++) {
+        const items = chunks[ci];
+        if (items.length === 0) continue;
+        const ext = this.config.output.format === "webp" ? "webp" : "png";
+        const baseName = sprite.spriteFile.replace(`.${ext}`, "");
+        const newFile = `${baseName}_part${ci}.${ext}`;
+        result.push({
+          spriteFile: newFile,
+          canvasWidth: items.reduce((max, it) => Math.max(max, it.x + it.width), 0),
+          canvasHeight: items.reduce((max, it) => Math.max(max, it.y + it.height), 0),
+          items
+        });
+      }
+    }
+    return result;
+  }
+  buildManifest(packedSprites) {
+    const manifest = /* @__PURE__ */ new Map();
+    for (const sprite of packedSprites) {
+      for (const item of sprite.items) {
+        manifest.set(item.asset.url, {
+          spriteFile: sprite.spriteFile,
+          x: item.x,
+          y: item.y,
+          width: item.width,
+          height: item.height
+        });
+      }
+    }
+    return manifest;
+  }
+};
+
+// src/plugin-helper.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { glob } from "fs/promises";
+import path from "path";
+async function runSpriteGeneration(options) {
+  const { config, outputDir } = options;
+  const resolved = parseConfig(config);
+  const cssSource = Array.isArray(resolved.input.cssSource) ? resolved.input.cssSource : [resolved.input.cssSource];
+  const cssFiles = /* @__PURE__ */ new Map();
+  for (const pattern of cssSource) {
+    const absPattern = path.resolve(outputDir, pattern);
+    try {
+      const matches = await Array.fromAsync(glob(absPattern));
+      for (const file of matches) {
+        if (!file.endsWith(".css")) continue;
+        const content = await readFile(file, "utf-8");
+        cssFiles.set(file, content);
+      }
+    } catch {
+    }
+  }
+  if (cssFiles.size === 0) return;
+  const rules = await extractBackgrounds(cssFiles);
+  const imageUrls = /* @__PURE__ */ new Set();
+  for (const rule of rules) {
+    imageUrls.add(rule.imageUrl);
+  }
+  const images = /* @__PURE__ */ new Map();
+  const allowedDir = path.resolve(outputDir);
+  for (const url of imageUrls) {
+    if (url.startsWith("data:") || url.startsWith("http")) continue;
+    if (url.length > 4096) continue;
+    for (const [cssFile] of cssFiles) {
+      const absPath = path.resolve(path.dirname(cssFile), url);
+      if (!absPath.startsWith(allowedDir)) continue;
+      try {
+        if (!images.has(url)) {
+          images.set(url, await readFile(absPath));
+        }
+      } catch {
+      }
+    }
+  }
+  const spriter = new Spriter(config);
+  const result = await spriter.run({ css: cssFiles, images, cssBaseDir: outputDir });
+  const cssDist = path.resolve(outputDir, resolved.output.cssDist);
+  const imgDist = path.resolve(cssDist, resolved.output.imageDist);
+  await mkdir(imgDist, { recursive: true });
+  for (const [name, buf] of result.spriteImages) {
+    await writeFile(path.join(imgDist, name), buf);
+  }
+  for (const [name, content] of result.cssFiles) {
+    await writeFile(path.join(cssDist, path.basename(name)), content);
+  }
+}
+export {
+  IspriterError,
+  Spriter,
+  SpriterConfigSchema,
+  analyseBackground,
+  cleanImageUrl,
+  emitCSS,
+  extractBackgrounds,
+  generateSprites,
+  isUnsprite,
+  normalizeConfig,
+  pack,
+  parseConfig,
+  runSpriteGeneration,
+  shouldSkip
+};

package/dist/retina-NHUTNCL6.js

@@ -0,0 +1,83 @@
+import {
+  pack
+} from "./chunk-3JTOVWUA.js";
+
+// src/image/retina.ts
+import sharp from "sharp";
+function matchRetinaImages(assets, scale) {
+  const retinaMap = /* @__PURE__ */ new Map();
+  const standard = [];
+  for (const asset of assets) {
+    const retinaSuffix = `@${scale}x`;
+    const match = asset.url.match(/^(.+?)(@\dx)(\.\w+)$/);
+    if (match && match[2] === retinaSuffix) {
+      retinaMap.set(match[1] + match[3], asset);
+    } else if (!asset.url.includes("@2x") && !asset.url.includes("@3x")) {
+      standard.push(asset);
+    }
+  }
+  return { standard, retina: retinaMap };
+}
+async function generateRetinaSprites(assets, config, scale) {
+  const scaledAssets = /* @__PURE__ */ new Map();
+  const retinaMatch = matchRetinaImages(assets, scale);
+  const preparedAssets = [];
+  for (const asset of assets) {
+    if (asset.url.includes("@2x") || asset.url.includes("@3x")) continue;
+    const retinaAsset = retinaMatch.retina.get(asset.url);
+    let buffer;
+    let width;
+    let height;
+    if (retinaAsset) {
+      buffer = retinaAsset.buffer;
+      width = retinaAsset.naturalWidth;
+      height = retinaAsset.naturalHeight;
+    } else {
+      const scaledWidth = asset.naturalWidth * scale;
+      const scaledHeight = asset.naturalHeight * scale;
+      buffer = await sharp(asset.buffer).resize(scaledWidth, scaledHeight, { fit: "fill" }).toBuffer();
+      width = scaledWidth;
+      height = scaledHeight;
+    }
+    preparedAssets.push({
+      ...asset,
+      buffer,
+      naturalWidth: width,
+      naturalHeight: height
+    });
+    scaledAssets.set(asset.url, { width, height });
+  }
+  const inputs = preparedAssets.map((a) => ({
+    width: a.naturalWidth,
+    height: a.naturalHeight,
+    data: a
+  }));
+  const { placed: packedResults, unfit } = pack(inputs, config.output.margin * scale);
+  if (unfit.length > 0) {
+    console.warn(`[ispriter] ${unfit.length} retina image(s) could not be packed`);
+  }
+  if (packedResults.length === 0) {
+    return { packedSprites: [], scaledAssets };
+  }
+  const ext = config.output.format === "webp" ? "webp" : "png";
+  const spriteFile = `${config.output.prefix}retina_${scale}x.${ext}`;
+  const canvasWidth = packedResults.reduce((max, r) => Math.max(max, r.x + r.width), 0);
+  const canvasHeight = packedResults.reduce((max, r) => Math.max(max, r.y + r.height), 0);
+  const packedSprite = {
+    spriteFile,
+    canvasWidth,
+    canvasHeight,
+    items: packedResults.map((r) => ({
+      asset: r.data,
+      x: r.x,
+      y: r.y,
+      width: r.width,
+      height: r.height
+    }))
+  };
+  return { packedSprites: [packedSprite], scaledAssets };
+}
+export {
+  generateRetinaSprites,
+  matchRetinaImages
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ispriter/core",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "clean-css": "^5.3.0",
+    "postcss": "^8.5.0",
+    "postcss-import": "^16.1.1",
+    "sharp": "^0.33.0",
+    "zod": "^3.24.0",
+    "@ispriter/shared": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/clean-css": "^4.2.0",
+    "tsup": "^8.4.0",
+    "vitest": "^3.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run"
+  }
+}