@pebbly/aseprite-ai-artist 0.1.0

package/dist/lib/color.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Colour maths for palette-legal editing.
+ *
+ * Pixel art lives or dies by palette discipline, and "nearest colour" in RGB
+ * space is not the colour a human would pick — RGB distance weights green far
+ * too heavily and ignores lightness. Everything here works in CIELAB with
+ * CIE76 ΔE, which is close enough to perceptual for a ≤64-colour palette and
+ * cheap enough to run per-pixel.
+ */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export interface Lab {
+    l: number;
+    a: number;
+    b: number;
+}
+export declare function parseHex(hex: string): Rgb;
+export declare function toHex({ r, g, b, a }: Rgb, includeAlpha?: boolean): string;
+export declare function rgbToLab({ r, g, b }: Rgb): Lab;
+/** CIE76 ΔE. Values below ~2.3 are indistinguishable to most viewers. */
+export declare function deltaE(a: Lab, b: Lab): number;
+export interface SnapResult {
+    index: number;
+    hex: string;
+    distance: number;
+}
+/**
+ * Nearest palette entry to `colour`, by ΔE.
+ *
+ * A fully transparent input snaps to itself: a palette has no entry for
+ * "nothing", and picking the nearest opaque colour for it would paint over
+ * holes the artist left on purpose.
+ */
+export declare function snapToPalette(colour: Rgb, palette: readonly string[]): SnapResult;
+export interface HueShiftOptions {
+    /** Positive lightens, negative darkens. Roughly one ramp step per 0.15. */
+    amount: number;
+    /** Degrees of hue rotation applied at full amount. */
+    hueShiftDegrees?: number;
+}
+/**
+ * Shade a colour the way a pixel artist does, not the way a brightness slider
+ * does: shadows rotate toward blue and desaturate slightly, highlights rotate
+ * toward yellow/orange and saturate. Flat luminance ramps are the single most
+ * common tell of machine-made pixel art.
+ */
+export declare function hueShiftShade(colour: Rgb, opts: HueShiftOptions): Rgb;
+export interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+}
+export declare function rgbToHsl({ r, g, b }: Rgb): Hsl;
+export declare function hslToRgb({ h, s, l }: Hsl): Omit<Rgb, "a">;
+/**
+ * Build a hue-shifted ramp of `steps` colours around a base colour.
+ * The base sits at the ramp's midpoint so callers get equal shadow and light.
+ */
+export declare function buildRamp(base: Rgb, steps: number, spread?: number): string[];
+/** Perceptual luminance, used by contrast and readability checks. */
+export declare function luminance({ r, g, b }: Rgb): number;
+export declare function contrastRatio(a: Rgb, b: Rgb): number;

package/dist/lib/color.js

@@ -0,0 +1,170 @@
+/**
+ * Colour maths for palette-legal editing.
+ *
+ * Pixel art lives or dies by palette discipline, and "nearest colour" in RGB
+ * space is not the colour a human would pick — RGB distance weights green far
+ * too heavily and ignores lightness. Everything here works in CIELAB with
+ * CIE76 ΔE, which is close enough to perceptual for a ≤64-colour palette and
+ * cheap enough to run per-pixel.
+ */
+const HEX_RE = /^#?([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+export function parseHex(hex) {
+    const m = HEX_RE.exec(hex.trim());
+    if (!m || !m[1])
+        throw new Error(`Invalid colour '${hex}'. Expected #rrggbb or #rrggbbaa.`);
+    const s = m[1];
+    return {
+        r: parseInt(s.slice(0, 2), 16),
+        g: parseInt(s.slice(2, 4), 16),
+        b: parseInt(s.slice(4, 6), 16),
+        a: s.length === 8 ? parseInt(s.slice(6, 8), 16) : 255,
+    };
+}
+export function toHex({ r, g, b, a }, includeAlpha = false) {
+    const h = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+    return includeAlpha && a !== 255 ? `#${h(r)}${h(g)}${h(b)}${h(a)}` : `#${h(r)}${h(g)}${h(b)}`;
+}
+function srgbToLinear(c) {
+    const v = c / 255;
+    return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+/** D65 reference white. */
+const XN = 0.95047;
+const YN = 1.0;
+const ZN = 1.08883;
+export function rgbToLab({ r, g, b }) {
+    const lr = srgbToLinear(r);
+    const lg = srgbToLinear(g);
+    const lb = srgbToLinear(b);
+    const x = (0.4124564 * lr + 0.3575761 * lg + 0.1804375 * lb) / XN;
+    const y = (0.2126729 * lr + 0.7151522 * lg + 0.072175 * lb) / YN;
+    const z = (0.0193339 * lr + 0.119192 * lg + 0.9503041 * lb) / ZN;
+    const f = (t) => (t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27) * t / 116 + 16 / 116);
+    const fx = f(x);
+    const fy = f(y);
+    const fz = f(z);
+    return { l: 116 * fy - 16, a: 500 * (fx - fy), b: 200 * (fy - fz) };
+}
+/** CIE76 ΔE. Values below ~2.3 are indistinguishable to most viewers. */
+export function deltaE(a, b) {
+    return Math.hypot(a.l - b.l, a.a - b.a, a.b - b.b);
+}
+/**
+ * Nearest palette entry to `colour`, by ΔE.
+ *
+ * A fully transparent input snaps to itself: a palette has no entry for
+ * "nothing", and picking the nearest opaque colour for it would paint over
+ * holes the artist left on purpose.
+ */
+export function snapToPalette(colour, palette) {
+    if (palette.length === 0)
+        throw new Error("Palette is empty.");
+    if (colour.a === 0)
+        return { index: -1, hex: toHex(colour, true), distance: 0 };
+    const target = rgbToLab(colour);
+    let best = 0;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < palette.length; i++) {
+        const entry = palette[i];
+        if (entry === undefined)
+            continue;
+        const d = deltaE(target, rgbToLab(parseHex(entry)));
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = i;
+        }
+    }
+    return { index: best, hex: palette[best], distance: bestDistance };
+}
+/**
+ * Shade a colour the way a pixel artist does, not the way a brightness slider
+ * does: shadows rotate toward blue and desaturate slightly, highlights rotate
+ * toward yellow/orange and saturate. Flat luminance ramps are the single most
+ * common tell of machine-made pixel art.
+ */
+export function hueShiftShade(colour, opts) {
+    const { amount } = opts;
+    const degrees = opts.hueShiftDegrees ?? 25;
+    const { h, s, l } = rgbToHsl(colour);
+    const shift = -Math.sign(amount) * degrees * Math.abs(amount);
+    const newHue = (((h + shift) % 360) + 360) % 360;
+    const newLight = clamp01(l + amount * 0.5);
+    const newSat = clamp01(s + (amount > 0 ? 0.06 : -0.04) * Math.abs(amount) * 2);
+    return { ...hslToRgb({ h: newHue, s: newSat, l: newLight }), a: colour.a };
+}
+export function rgbToHsl({ r, g, b }) {
+    const rn = r / 255;
+    const gn = g / 255;
+    const bn = b / 255;
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const l = (max + min) / 2;
+    const d = max - min;
+    if (d === 0)
+        return { h: 0, s: 0, l };
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h;
+    if (max === rn)
+        h = ((gn - bn) / d + (gn < bn ? 6 : 0)) * 60;
+    else if (max === gn)
+        h = ((bn - rn) / d + 2) * 60;
+    else
+        h = ((rn - gn) / d + 4) * 60;
+    return { h, s, l };
+}
+export function hslToRgb({ h, s, l }) {
+    if (s === 0) {
+        const v = Math.round(l * 255);
+        return { r: v, g: v, b: v };
+    }
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const hk = (((h % 360) + 360) % 360) / 360;
+    const channel = (t) => {
+        let tt = t;
+        if (tt < 0)
+            tt += 1;
+        if (tt > 1)
+            tt -= 1;
+        if (tt < 1 / 6)
+            return p + (q - p) * 6 * tt;
+        if (tt < 1 / 2)
+            return q;
+        if (tt < 2 / 3)
+            return p + (q - p) * (2 / 3 - tt) * 6;
+        return p;
+    };
+    return {
+        r: Math.round(channel(hk + 1 / 3) * 255),
+        g: Math.round(channel(hk) * 255),
+        b: Math.round(channel(hk - 1 / 3) * 255),
+    };
+}
+/**
+ * Build a hue-shifted ramp of `steps` colours around a base colour.
+ * The base sits at the ramp's midpoint so callers get equal shadow and light.
+ */
+export function buildRamp(base, steps, spread = 0.55) {
+    if (steps < 2)
+        throw new Error("A ramp needs at least 2 steps.");
+    const out = [];
+    for (let i = 0; i < steps; i++) {
+        const t = steps === 1 ? 0 : (i / (steps - 1)) * 2 - 1; // -1 … +1
+        out.push(toHex(hueShiftShade(base, { amount: t * spread })));
+    }
+    return out;
+}
+function clamp01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+/** Perceptual luminance, used by contrast and readability checks. */
+export function luminance({ r, g, b }) {
+    return 0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b);
+}
+export function contrastRatio(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+//# sourceMappingURL=color.js.map

package/dist/lib/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","sourceRoot":"","sources":["../../src/lib/color.ts"],"names":[],"mappings":"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"}

package/dist/lib/protocol.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Wire protocol shared by the MCP server, the standalone bridge and the
+ * Aseprite Lua extension.
+ *
+ * Design constraints that shape this file:
+ *  - Aseprite's Lua `WebSocket` is a *client only*; something else must listen.
+ *    That listener is the bridge (see docs/ARCHITECTURE.md).
+ *  - The MCP server process is owned by the agent host and may restart or be
+ *    duplicated, so the bridge must outlive it and accept N control clients.
+ *  - Everything on the wire is newline-free JSON, one frame per message.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/** Default port the Aseprite extension dials. */
+export declare const DEFAULT_PLUGIN_PORT = 9931;
+/** Default port MCP servers dial as control clients. Always plugin port + 1. */
+export declare const DEFAULT_CONTROL_PORT: number;
+/** Separator used to namespace a request id per control client. */
+export declare const ID_SEPARATOR = "::";
+export interface CommandFrame {
+    id: string;
+    cmd: string;
+    args?: Record<string, unknown>;
+}
+export interface ResultFrame {
+    id: string;
+    ok: boolean;
+    data?: unknown;
+    error?: WireError;
+}
+export interface WireError {
+    code: ErrorCode;
+    message: string;
+    /** Machine-readable remediation hint; never free-form prose the agent must parse. */
+    details?: Record<string, unknown>;
+}
+export type ErrorCode = "not_connected" | "no_active_sprite" | "unsupported_command" | "invalid_args" | "aseprite_error" | "timeout" | "refused" | "too_large";
+/** Sent by the extension right after it connects, and on demand. */
+export interface HelloFrame {
+    type: "hello";
+    protocol: number;
+    extensionVersion: string;
+    asepriteVersion: string;
+    features: string[];
+}
+/** Broadcast by the bridge to every control client whenever liveness changes. */
+export interface BridgeStateFrame {
+    type: "bridge_state";
+    pluginConnected: boolean;
+    hello: HelloFrame | null;
+    bridgeVersion: string;
+    since: number;
+}
+export type PluginFrame = ResultFrame | HelloFrame | {
+    type: string;
+    [k: string]: unknown;
+};
+export declare function makeNamespacedId(clientId: number, originalId: string): string;
+export declare function splitNamespacedId(id: string): {
+    clientId: number;
+    originalId: string;
+} | null;
+export declare function isHello(frame: unknown): frame is HelloFrame;
+export declare function isBridgeState(frame: unknown): frame is BridgeStateFrame;
+export declare function isResult(frame: unknown): frame is ResultFrame;
+export declare class LiveError extends Error {
+    readonly code: ErrorCode;
+    readonly details: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
+    toWire(): WireError;
+}
+/**
+ * The one error every mutating tool raises when Aseprite is not reachable.
+ *
+ * `doNotFallBackToDisk` is load-bearing: an agent that silently retargets a
+ * failed live edit at the .aseprite file on disk produces changes the user
+ * never sees in their open window, and that later get overwritten by a save.
+ */
+export declare function notConnected(detail?: string): LiveError;

package/dist/lib/protocol.js

@@ -0,0 +1,72 @@
+/**
+ * Wire protocol shared by the MCP server, the standalone bridge and the
+ * Aseprite Lua extension.
+ *
+ * Design constraints that shape this file:
+ *  - Aseprite's Lua `WebSocket` is a *client only*; something else must listen.
+ *    That listener is the bridge (see docs/ARCHITECTURE.md).
+ *  - The MCP server process is owned by the agent host and may restart or be
+ *    duplicated, so the bridge must outlive it and accept N control clients.
+ *  - Everything on the wire is newline-free JSON, one frame per message.
+ */
+export const PROTOCOL_VERSION = 1;
+/** Default port the Aseprite extension dials. */
+export const DEFAULT_PLUGIN_PORT = 9931;
+/** Default port MCP servers dial as control clients. Always plugin port + 1. */
+export const DEFAULT_CONTROL_PORT = DEFAULT_PLUGIN_PORT + 1;
+/** Separator used to namespace a request id per control client. */
+export const ID_SEPARATOR = "::";
+export function makeNamespacedId(clientId, originalId) {
+    return `c${clientId}${ID_SEPARATOR}${originalId}`;
+}
+export function splitNamespacedId(id) {
+    const idx = id.indexOf(ID_SEPARATOR);
+    if (idx <= 1 || id[0] !== "c")
+        return null;
+    const clientId = Number(id.slice(1, idx));
+    if (!Number.isInteger(clientId))
+        return null;
+    return { clientId, originalId: id.slice(idx + ID_SEPARATOR.length) };
+}
+export function isHello(frame) {
+    return typeof frame === "object" && frame !== null && frame.type === "hello";
+}
+export function isBridgeState(frame) {
+    return (typeof frame === "object" &&
+        frame !== null &&
+        frame.type === "bridge_state");
+}
+export function isResult(frame) {
+    return (typeof frame === "object" &&
+        frame !== null &&
+        typeof frame.id === "string" &&
+        typeof frame.ok === "boolean");
+}
+export class LiveError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "LiveError";
+        this.code = code;
+        this.details = details;
+    }
+    toWire() {
+        return { code: this.code, message: this.message, details: this.details };
+    }
+}
+/**
+ * The one error every mutating tool raises when Aseprite is not reachable.
+ *
+ * `doNotFallBackToDisk` is load-bearing: an agent that silently retargets a
+ * failed live edit at the .aseprite file on disk produces changes the user
+ * never sees in their open window, and that later get overwritten by a save.
+ */
+export function notConnected(detail) {
+    return new LiveError("not_connected", detail ??
+        "Aseprite is not connected. Open Aseprite with the aseprite-ai-artist extension installed, then retry.", {
+        doNotFallBackToDisk: true,
+        remediation: "Run `npx @pebbly/aseprite-ai-artist doctor` for a step-by-step check.",
+    });
+}
+//# sourceMappingURL=protocol.js.map

package/dist/lib/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/lib/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAElC,iDAAiD;AACjD,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACxC,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,GAAG,CAAC,CAAC;AAE5D,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAoDjC,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,UAAkB;IACnE,OAAO,IAAI,QAAQ,GAAG,YAAY,GAAG,UAAU,EAAE,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,EAAU;IAEV,MAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IACrC,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA2B,CAAC,IAAI,KAAK,OAAO,CAAC;AACtG,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA2B,CAAC,IAAI,KAAK,cAAc,CACrD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAA0B,CAAC,EAAE,KAAK,QAAQ;QAClD,OAAQ,KAA0B,CAAC,EAAE,KAAK,SAAS,CACpD,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAY;IAChB,OAAO,CAA0B;IAE1C,YAAY,IAAe,EAAE,OAAe,EAAE,UAAmC,EAAE;QACjF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,OAAO,IAAI,SAAS,CAClB,eAAe,EACf,MAAM;QACJ,uGAAuG,EACzG;QACE,mBAAmB,EAAE,IAAI;QACzB,WAAW,EAAE,uEAAuE;KACrF,CACF,CAAC;AACJ,CAAC"}

package/dist/lib/render.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Turning pixels into something a language model can actually read.
+ *
+ * A 32×32 sprite rendered as a PNG is ~8 screen pixels wide once a vision model
+ * downsamples it; the model then guesses. Two representations fix that:
+ *   - an upscaled preview PNG (done inside Aseprite, see the `preview` tool);
+ *   - a text grid, one glyph per pixel, which is exact and works on clients
+ *     with no vision at all.
+ *
+ * The text grid is the verification half of the draw → look → fix loop.
+ */
+export interface PixelRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Distinct colours in the region. Index 0 is always fully transparent. */
+    colors: string[];
+    /** Row-major indices into `colors`, length = width * height. */
+    grid: number[];
+}
+export interface AsciiOptions {
+    /** Refuse above this many cells; a wall of text is worse than no answer. */
+    maxCells?: number;
+    showRulers?: boolean;
+}
+export interface AsciiView {
+    text: string;
+    legend: Record<string, string>;
+    width: number;
+    height: number;
+    originX: number;
+    originY: number;
+}
+export declare function renderAscii(region: PixelRegion, opts?: AsciiOptions): AsciiView;
+export interface DiffView {
+    text: string;
+    legend: Record<string, string>;
+    changed: number;
+    total: number;
+}
+/**
+ * Pixel-level diff between two regions of equal size.
+ *   `.` unchanged   `-` became transparent   glyph = the *new* colour
+ * This answers "what did my edit actually touch", which a before/after image
+ * pair does not, at small sizes.
+ */
+export declare function renderDiff(before: PixelRegion, after: PixelRegion): DiffView;
+/**
+ * Pick an integer upscale factor that lands a sprite's long edge near `target`.
+ * Nearest-neighbour only — any smoothing destroys the thing being reviewed.
+ *
+ * The bound is on the OUTPUT size, not the factor. Capping the factor at 16 —
+ * as this once did — renders an 8px sprite at 128px and a 16px one at 256px,
+ * which are precisely the cases where a vision model is otherwise guessing.
+ */
+export declare function previewScale(width: number, height: number, target?: number, maxEdge?: number): number;
+/** Grid layout for a filmstrip: as close to square as whole cells allow. */
+export declare function filmstripLayout(frames: number): {
+    cols: number;
+    rows: number;
+};

package/dist/lib/render.js

@@ -0,0 +1,134 @@
+import { LiveError } from "./protocol.js";
+/** Glyph alphabet, ordered so the most common colours get the most distinct shapes. */
+const GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789#@%&$?!+=*";
+const TRANSPARENT_GLYPH = ".";
+export function renderAscii(region, opts = {}) {
+    const maxCells = opts.maxCells ?? 4096; // 64×64
+    const cells = region.width * region.height;
+    if (cells > maxCells) {
+        throw new LiveError("too_large", `Region is ${region.width}×${region.height} (${cells} cells) which exceeds the ${maxCells}-cell text-grid limit. ` +
+            `Pass a smaller region, or use the preview tool for a whole-sprite look.`, { cells, maxCells });
+    }
+    const legend = {};
+    const glyphFor = new Map();
+    glyphFor.set(0, TRANSPARENT_GLYPH);
+    const distinct = region.colors.length - 1;
+    if (distinct > GLYPHS.length) {
+        throw new LiveError("too_large", `Region has ${distinct} distinct colours but the text grid only has ${GLYPHS.length} glyphs. ` +
+            `Past that, different colours would share a glyph and the grid would lie about what is where. ` +
+            `Read a smaller region, or use the preview op instead.`, { distinctColors: distinct, maxColors: GLYPHS.length });
+    }
+    let next = 0;
+    for (let i = 1; i < region.colors.length; i++) {
+        const glyph = GLYPHS[next++];
+        glyphFor.set(i, glyph);
+        legend[glyph] = region.colors[i] ?? "#000000";
+    }
+    const showRulers = opts.showRulers ?? true;
+    const lines = [];
+    const rowLabelWidth = String(region.y + region.height - 1).length;
+    const pad = " ".repeat(rowLabelWidth + 1);
+    if (showRulers) {
+        // Two ruler rows: tens then units, so a 3-digit x is still readable.
+        let tens = pad;
+        let units = pad;
+        for (let x = 0; x < region.width; x++) {
+            const abs = region.x + x;
+            tens += abs % 10 === 0 ? String(Math.floor(abs / 10) % 10) : " ";
+            units += String(abs % 10);
+        }
+        lines.push(tens.trimEnd());
+        lines.push(units);
+    }
+    for (let row = 0; row < region.height; row++) {
+        let line = String(region.y + row).padStart(rowLabelWidth) + " ";
+        for (let col = 0; col < region.width; col++) {
+            const idx = region.grid[row * region.width + col] ?? 0;
+            line += glyphFor.get(idx) ?? "?";
+        }
+        lines.push(line);
+    }
+    return {
+        text: lines.join("\n"),
+        legend,
+        width: region.width,
+        height: region.height,
+        originX: region.x,
+        originY: region.y,
+    };
+}
+/**
+ * Pixel-level diff between two regions of equal size.
+ *   `.` unchanged   `-` became transparent   glyph = the *new* colour
+ * This answers "what did my edit actually touch", which a before/after image
+ * pair does not, at small sizes.
+ */
+export function renderDiff(before, after) {
+    if (before.width !== after.width || before.height !== after.height) {
+        throw new LiveError("invalid_args", `Cannot diff regions of different sizes (${before.width}×${before.height} vs ${after.width}×${after.height}).`);
+    }
+    const legend = {};
+    const glyphForColor = new Map();
+    let next = 0;
+    const lines = [];
+    let changed = 0;
+    for (let row = 0; row < before.height; row++) {
+        let line = "";
+        for (let col = 0; col < before.width; col++) {
+            const i = row * before.width + col;
+            const beforeColor = before.colors[before.grid[i] ?? 0] ?? "transparent";
+            const afterIdx = after.grid[i] ?? 0;
+            const afterColor = after.colors[afterIdx] ?? "transparent";
+            if (beforeColor === afterColor) {
+                line += ".";
+                continue;
+            }
+            changed++;
+            if (afterIdx === 0) {
+                line += "-";
+                continue;
+            }
+            let glyph = glyphForColor.get(afterColor);
+            if (!glyph) {
+                if (next >= GLYPHS.length) {
+                    throw new LiveError("too_large", `More than ${GLYPHS.length} distinct colours appear in this diff, so glyphs would start ` +
+                        `colliding and the grid would misreport which colour landed where. Diff a smaller region.`, { maxColors: GLYPHS.length });
+                }
+                glyph = GLYPHS[next++];
+                glyphForColor.set(afterColor, glyph);
+                legend[glyph] = afterColor;
+            }
+            line += glyph;
+        }
+        lines.push(line);
+    }
+    return {
+        text: lines.join("\n"),
+        legend,
+        changed,
+        total: before.width * before.height,
+    };
+}
+/**
+ * Pick an integer upscale factor that lands a sprite's long edge near `target`.
+ * Nearest-neighbour only — any smoothing destroys the thing being reviewed.
+ *
+ * The bound is on the OUTPUT size, not the factor. Capping the factor at 16 —
+ * as this once did — renders an 8px sprite at 128px and a 16px one at 256px,
+ * which are precisely the cases where a vision model is otherwise guessing.
+ */
+export function previewScale(width, height, target = 1024, maxEdge = 2048) {
+    const longEdge = Math.max(width, height, 1);
+    const wanted = Math.max(1, Math.round(target / longEdge));
+    const byOutput = Math.max(1, Math.floor(maxEdge / longEdge));
+    return Math.min(wanted, byOutput);
+}
+/** Grid layout for a filmstrip: as close to square as whole cells allow. */
+export function filmstripLayout(frames) {
+    if (frames <= 0)
+        return { cols: 0, rows: 0 };
+    const cols = Math.ceil(Math.sqrt(frames));
+    const rows = Math.ceil(frames / cols);
+    return { cols, rows };
+}
+//# sourceMappingURL=render.js.map

package/dist/lib/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/lib/render.ts"],"names":[],"mappings":"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"}

package/dist/lib/skills.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Skills, served over MCP.
+ *
+ * Claude Code reads `skills/` out of the plugin directory directly. Codex,
+ * Gemini CLI and Cursor have no such concept — so without this, everyone except
+ * Claude Code gets raw tools and none of the craft that makes the tools produce
+ * decent sprites. Serving the same markdown as MCP resources *and* MCP prompts
+ * closes that gap with one source of truth on disk.
+ *
+ * Resources are the discovery surface (an agent can list and read them at will);
+ * prompts are the invocation surface (they show up as slash commands in clients
+ * that render them). Both point at the same file.
+ *
+ * Tracks the Skills Extension direction of the MCP Skills-over-MCP WG
+ * (SEP-2640, resources-based). When that lands in the SDK the transport here
+ * becomes the standard one; the on-disk format does not change.
+ */
+export interface SkillDoc {
+    /** Directory name, and the name the agent invokes. */
+    name: string;
+    title: string;
+    description: string;
+    /** Full markdown body, frontmatter stripped. */
+    body: string;
+    file: string;
+    /** Extra files shipped next to SKILL.md, exposed as sub-resources. */
+    assets: string[];
+}
+export interface RuleDoc {
+    name: string;
+    title: string;
+    body: string;
+    file: string;
+}
+export declare function loadSkills(root: string): SkillDoc[];
+export declare function loadRules(root: string): RuleDoc[];
+/**
+ * The server's `instructions` string — the one piece of guidance every MCP
+ * client sees, whether or not it understands skills or plugins. Keep it short:
+ * it is paid for on every session, so it carries only the rules an agent gets
+ * wrong catastrophically, and points at the skills for everything else.
+ */
+export declare function serverInstructions(skills: SkillDoc[]): string;