@xtyle/core 0.5.0

package/dist/types.d.ts

@@ -0,0 +1,152 @@
+export type TokenName = string;
+export type TokenRegister = Record<TokenName, string>;
+/** The three colors most commonly provided up front — purely a convenience grouping for the CLI's
+ * flags and the gauntlet's seed reporting. Not a derive input: every value reaches `derive` through
+ * the one token channel (`--bg-0` / `--fg-0` / `--accent`), with nothing privileged about the trio. */
+export interface Seeds {
+    bg?: string;
+    fg?: string;
+    accent?: string;
+}
+export type Scheme = "dark" | "light";
+export type Density = "compact" | "normal" | "comfortable";
+export interface FontStacks {
+    sans?: string;
+    mono?: string;
+    display?: string;
+}
+export interface Knobs {
+    scheme?: Scheme;
+    accentShiftStep?: number;
+    accentSplit?: number;
+    contrastBand?: "aa" | "aaa" | number;
+    vibrancy?: number;
+    typeScale?: number;
+    radiusScale?: number;
+    density?: Density | number;
+    cues?: "color" | "redundant";
+    fonts?: FontStacks;
+    hour?: number;
+    [knob: string]: unknown;
+}
+/**
+ * Author-pinned token values. Honored verbatim in the output, and — where the
+ * algorithm supports it — fed back in as derivation inputs so dependent tokens
+ * re-solve around the pin (e.g. pinning `--bg-0` re-derives `--fg-0` to keep
+ * contrast). Pinning a token the algorithm itself derives is an explicit opt-out
+ * of that token's own invariant.
+ */
+export type Constraints = TokenRegister;
+/**
+ * The friendly seed shape: bg / fg / accent (plus arbitrary `overrides`) named as
+ * anchors instead of raw token keys. The `derive` entry translates these into
+ * `constraints` (`bg` → `--bg-0`, `fg` → `--fg-0`, `accent` → `--accent`) before
+ * derivation, so `{ anchors: { accent } }` seeds the same channel a pinned
+ * `{ constraints: { "--accent": … } }` does. An explicit `constraints` entry for the
+ * same token wins over the anchor.
+ */
+export interface AnchorSeed {
+    bg?: string;
+    fg?: string;
+    accent?: string;
+    overrides?: Record<string, string>;
+}
+export interface DeriveOptions {
+    knobs?: Knobs;
+    constraints?: Constraints;
+    anchors?: AnchorSeed;
+}
+/**
+ * The shape of a token's value, used to apply the right validity and structural
+ * check per token. Color tokens parse as OKLCH; the rest never do — `--font-sans`,
+ * `--duration-fast`, `--text-lg`, `--elevation-2` are font / duration / length /
+ * shadow strings and would throw or NaN if parsed as a color.
+ */
+export type TokenCategory = "color" | "length" | "number" | "font" | "shadow" | "duration" | "easing" | "keyword";
+export type TokenCategories = Record<TokenName, TokenCategory>;
+export interface InvariantContext {
+    register: TokenRegister;
+    knobs: Knobs;
+    scheme: Scheme;
+    categories: TokenCategories;
+    constraints: Constraints;
+}
+export interface InvariantResult {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export type Invariant = (ctx: InvariantContext) => InvariantResult;
+export interface TokenLineageNode {
+    name: TokenName;
+    value?: string;
+    refs?: TokenName[];
+}
+/**
+ * The inputs a pass reads about the current derivation, resolved once from the
+ * provided token values and knobs. Distinct from {@link DeriveOptions} (the raw,
+ * partially-specified request): a `PassContext` is the resolved view — `scheme`
+ * decided, the pinned constraints isolated so a pass can leave them verbatim.
+ * `passIndex` is the pass's zero-based position in the pipeline.
+ */
+export interface PassContext {
+    knobs: Knobs;
+    scheme: Scheme;
+    pinned: Constraints;
+    passIndex: number;
+}
+/**
+ * One named stage in an algorithm's derivation pipeline. `run` receives the
+ * register produced so far and returns the register after this stage. The first
+ * pass receives an empty register and produces the base; each later pass transforms
+ * the register it is handed. Passes are pure register→register transforms — the
+ * aesthetic decisions a pass encodes are algorithm policy, never engine mechanism.
+ */
+export interface Pass {
+    name: string;
+    run: (register: TokenRegister, ctx: PassContext) => TokenRegister;
+}
+/** A single pass's output, captured for tracing. */
+export interface TraceSnapshot {
+    name: string;
+    register: TokenRegister;
+}
+/** The result of a traced derivation: the final register plus every intermediate snapshot. */
+export interface DeriveTrace {
+    register: TokenRegister;
+    trace: TraceSnapshot[];
+}
+export interface Algorithm {
+    id: string;
+    produces: TokenName[];
+    knobs: string[];
+    categories: TokenCategories;
+    derive(opts: DeriveOptions): TokenRegister;
+    /**
+     * The honest derivation graph for a given input: the same nodes `derive` resolves,
+     * with each token's `refs` naming what it derives from. `resolveGraph(lineage(opts))`
+     * reproduces `derive(opts)`. Built for inspectors and the CLI to read lineage as data.
+     */
+    lineage(opts?: DeriveOptions): TokenLineageNode[];
+    invariants: Invariant[];
+    /**
+     * The ordered, named stages `derive` threads the register through. Absent means the
+     * algorithm is implicitly a single-pass pipeline whose one pass is `derive`. On a
+     * baked algorithm each pass's `run` is callable; on a host facade the passes are
+     * name-only stubs (closures cannot cross the sandbox — use `deriveTraced` for layers).
+     */
+    passes?: Pass[];
+    /**
+     * Like `derive`, but retains every intermediate register snapshot. The last
+     * snapshot's register equals `derive(opts)`. Absent on a bare 1-pass algorithm,
+     * in which case the engine's top-level `deriveTraced` synthesizes a single snapshot.
+     */
+    deriveTraced?(opts: DeriveOptions): DeriveTrace;
+}
+export type EmitFormat = "css" | "json" | "prism" | "monaco";
+export type Emitter = (register: TokenRegister) => string;
+export interface CoverageResult {
+    covered: boolean;
+    missing: TokenName[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/vocab.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The canonical design-vocabulary unions shared across every binding and the
+ * component manifest. These are the authoritative names; components import from
+ * here so the vocabulary never drifts between the engine, the manifests, and the
+ * bindings.
+ */
+/** Semantic color roles — the `--{role}-*` token families. */
+export type Tone = "accent" | "neutral" | "danger" | "success" | "warn" | "info";
+/** The twelve named hues — the `--color-{hue}-*` token families. */
+export type Hue = "red" | "orange" | "yellow" | "green" | "blue" | "purple" | "brown" | "pink" | "cyan" | "gray" | "white" | "black";
+/** The accent ramp's secondary stops, each a tone in its own right. */
+export type AccentVariant = "accent-2" | "accent-3" | "accent-4";
+/**
+ * Every tone a component can render: the semantic roles, the three accent-ramp
+ * variants, and the twelve named hues. Each one resolves to the same four-token
+ * family — `--{tone}`, `--{tone}-bg`, `--{tone}-fg`, `--{tone}-text` — so any
+ * component can take any tone through one code path.
+ */
+export type FullTone = Tone | AccentVariant | Hue;
+/** Badge accepts any tone in the open vocabulary — semantic role, accent variant, or named hue. */
+export type BadgeTone = FullTone;
+export declare const TONES: readonly Tone[];
+export declare const ACCENT_VARIANTS: readonly AccentVariant[];
+export declare const HUES: readonly Hue[];
+/** Every tone in render order: semantic roles, then accent variants, then named hues. */
+export declare const FULL_TONES: readonly FullTone[];
+/** The shared size scale. */
+export type Size = "sm" | "md" | "lg";
+/** The button's variant set. */
+export type ButtonVariant = "solid" | "outline" | "ghost" | "subtle" | "link";
+/** How a button justifies its content when it is wider than that content. */
+export type ButtonAlign = "start" | "center" | "end";
+/** The heading level — maps to the `<h1>`–`<h6>` semantic tag. */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** The heading's typographic size, decoupled from its semantic level. */
+export type HeadingSize = "xs" | "sm" | "md" | "body" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "5xl";
+/**
+ * The default visual size for a heading level, used when `size` is not set.
+ * Keeps `<Heading level={1}>` reading as a hero without forcing every call to
+ * restate the size, while leaving `size` a free override.
+ */
+export declare function headingSizeForLevel(level: HeadingLevel): HeadingSize;
+/** The heading's ink: the `default`/`muted`/`subtle` emphasis ramp, or any tone in the full roster. */
+export type HeadingTone = "default" | "muted" | "subtle" | FullTone;
+//# sourceMappingURL=vocab.d.ts.map

package/dist/vocab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocab.d.ts","sourceRoot":"","sources":["../src/vocab.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjF,oEAAoE;AACpE,MAAM,MAAM,GAAG,GACZ,KAAK,GACL,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,MAAM,GACN,QAAQ,GACR,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEX,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,aAAa,GAAG,GAAG,CAAC;AAElD,mGAAmG;AACnG,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;AAEjC,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAA+D,CAAC;AACjG,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAAyC,CAAC;AAC9F,eAAO,MAAM,IAAI,EAAE,SAAS,GAAG,EAa9B,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAA4C,CAAC;AAEvF,6BAA6B;AAC7B,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEtC,gCAAgC;AAChC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9E,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjD,yEAAyE;AACzE,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAWpG;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,CAEpE;AAED,uGAAuG;AACvG,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC"}

package/dist/vocab.js

@@ -0,0 +1,41 @@
+/**
+ * The canonical design-vocabulary unions shared across every binding and the
+ * component manifest. These are the authoritative names; components import from
+ * here so the vocabulary never drifts between the engine, the manifests, and the
+ * bindings.
+ */
+export const TONES = ["accent", "neutral", "danger", "success", "warn", "info"];
+export const ACCENT_VARIANTS = ["accent-2", "accent-3", "accent-4"];
+export const HUES = [
+    "red",
+    "orange",
+    "yellow",
+    "green",
+    "blue",
+    "purple",
+    "brown",
+    "pink",
+    "cyan",
+    "gray",
+    "white",
+    "black",
+];
+/** Every tone in render order: semantic roles, then accent variants, then named hues. */
+export const FULL_TONES = [...TONES, ...ACCENT_VARIANTS, ...HUES];
+const HEADING_LEVEL_SIZE = {
+    1: "3xl",
+    2: "2xl",
+    3: "xl",
+    4: "lg",
+    5: "body",
+    6: "sm",
+};
+/**
+ * The default visual size for a heading level, used when `size` is not set.
+ * Keeps `<Heading level={1}>` reading as a hero without forcing every call to
+ * restate the size, while leaving `size` a free override.
+ */
+export function headingSizeForLevel(level) {
+    return HEADING_LEVEL_SIZE[level] ?? "body";
+}
+//# sourceMappingURL=vocab.js.map

package/dist/vocab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocab.js","sourceRoot":"","sources":["../src/vocab.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkCH,MAAM,CAAC,MAAM,KAAK,GAAoB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACjG,MAAM,CAAC,MAAM,eAAe,GAA6B,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAC9F,MAAM,CAAC,MAAM,IAAI,GAAmB;IACnC,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;CACP,CAAC;AAEF,yFAAyF;AACzF,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,GAAG,KAAK,EAAE,GAAG,eAAe,EAAE,GAAG,IAAI,CAAC,CAAC;AAiBvF,MAAM,kBAAkB,GAAsC;IAC7D,CAAC,EAAE,KAAK;IACR,CAAC,EAAE,KAAK;IACR,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,IAAI;IACP,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,IAAI;CACP,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAmB;IACtD,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;AAC5C,CAAC"}

package/manifest.json

@@ -0,0 +1,96 @@
+{
+	"$schema": "https://xript.dev/schema/manifest/v0.7.json",
+	"xript": "0.7",
+	"name": "xtyle",
+	"version": "0.0.1",
+	"title": "Xtyle",
+	"description": "The host surface a xtyle algorithm runs against: token-lineage derivation in a zero-authority sandbox.",
+	"bindings": {
+		"log": {
+			"description": "Writes a diagnostic message to the host console.",
+			"params": [{ "name": "message", "type": "string" }]
+		},
+		"cuti": {
+			"description": "Color primitives shared by the engine and every algorithm — one OKLCH implementation, so a token a mod derives is identical to one the engine derives. Colors cross as `#rrggbb`, `#rrggbbaa`, or `oklch(L C H[/A])`; coordinates cross as `{ l, c, h, alpha }`.",
+			"members": {
+				"lighten": { "description": "Add `amount` (0–1) to OKLCH lightness, clamped.", "params": [{ "name": "color", "type": "string" }, { "name": "amount", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"darken": { "description": "Subtract `amount` (0–1) from OKLCH lightness, clamped.", "params": [{ "name": "color", "type": "string" }, { "name": "amount", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"saturate": { "description": "Push chroma outward by `amount`; out-of-gamut clamps to sRGB.", "params": [{ "name": "color", "type": "string" }, { "name": "amount", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"desaturate": { "description": "Pull chroma inward by `amount`, floored at 0.", "params": [{ "name": "color", "type": "string" }, { "name": "amount", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"shiftHue": { "description": "Rotate the OKLCH hue by `degrees` (wraps at 360°).", "params": [{ "name": "color", "type": "string" }, { "name": "degrees", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"complement": { "description": "180° rotation around the OKLCH hue wheel.", "params": [{ "name": "color", "type": "string" }], "returns": "string", "capability": "color-math" },
+				"mix": { "description": "Interpolate two colors in OKLCH; `t=0` is `a`, `t=1` is `b`, hue takes the shorter path.", "params": [{ "name": "a", "type": "string" }, { "name": "b", "type": "string" }, { "name": "t", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"alpha": { "description": "Replace the alpha channel with `a` (0–1).", "params": [{ "name": "color", "type": "string" }, { "name": "a", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"fade": { "description": "Subtract `amount` from alpha (0–1).", "params": [{ "name": "color", "type": "string" }, { "name": "amount", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"fadeIn": { "description": "Add `amount` to alpha (0–1).", "params": [{ "name": "color", "type": "string" }, { "name": "amount", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"fadeOut": { "description": "Alias for `fade` — subtract `amount` from alpha.", "params": [{ "name": "color", "type": "string" }, { "name": "amount", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"scaleLuminance": { "description": "Scale OKLCH lightness by `factor`.", "params": [{ "name": "color", "type": "string" }, { "name": "factor", "type": "number" }], "returns": "string", "capability": "color-math" },
+				"contrast": { "description": "WCAG contrast ratio between two colors (1–21; alpha ignored).", "params": [{ "name": "a", "type": "string" }, { "name": "b", "type": "string" }], "returns": "number", "capability": "color-math" },
+				"isDark": { "description": "Whether the color is closer to black by WCAG luminance.", "params": [{ "name": "color", "type": "string" }], "returns": "boolean", "capability": "color-math" },
+				"isLight": { "description": "Whether the color is closer to white by WCAG luminance.", "params": [{ "name": "color", "type": "string" }], "returns": "boolean", "capability": "color-math" },
+				"scheme": { "description": "Returns `\"dark\"` or `\"light\"` for the color's luminance.", "params": [{ "name": "color", "type": "string" }], "returns": "string", "capability": "color-math" },
+				"hueDelta": { "description": "Signed shortest-path hue difference `to - from`, normalized to (-180, 180].", "params": [{ "name": "from", "type": "number" }, { "name": "to", "type": "number" }], "returns": "number", "capability": "color-math" },
+				"pickReadable": { "description": "Pick the first option clearing `floor` (default 4.5) contrast against `fill`, else the highest-contrast option.", "params": [{ "name": "fill", "type": "string" }, { "name": "options", "type": { "array": "string" } }, { "name": "floor", "type": "number", "required": false }], "returns": "string", "capability": "color-math" },
+				"toOklch": { "description": "Project a color to OKLCH coordinates.", "params": [{ "name": "color", "type": "string" }], "returns": "OklchColor", "capability": "color-math" },
+				"fromOklch": { "description": "Project OKLCH coordinates to a canonical color string.", "params": [{ "name": "l", "type": "number" }, { "name": "c", "type": "number" }, { "name": "h", "type": "number" }, { "name": "alpha", "type": "number", "required": false }], "returns": "string", "capability": "color-math" },
+				"clampGamut": { "description": "Clamp OKLCH coordinates into the sRGB gamut.", "params": [{ "name": "l", "type": "number" }, { "name": "c", "type": "number" }, { "name": "h", "type": "number" }, { "name": "alpha", "type": "number", "required": false }], "returns": "OklchColor", "capability": "color-math" },
+				"toHex": { "description": "Canonical `#rrggbb` form (alpha stripped).", "params": [{ "name": "color", "type": "string" }], "returns": "string", "capability": "color-math" },
+				"toArgb": { "description": "Canonical `#rrggbbaa` form (alpha kept).", "params": [{ "name": "color", "type": "string" }], "returns": "string", "capability": "color-math" }
+			}
+		}
+	},
+	"capabilities": {
+		"color-math": {
+			"description": "Permits the algorithm to run OKLCH color math while deriving token values.",
+			"risk": "low"
+		}
+	},
+	"types": {
+		"DeriveInput": {
+			"description": "The anchors, knobs, and pinned constraints a derivation consumes.",
+			"fields": {
+				"anchors": { "type": "map", "description": "Overridable color anchors keyed by role." },
+				"knobs": { "type": "map", "description": "Algorithm knobs keyed by name." },
+				"constraints": { "type": "map", "description": "Author-pinned token values honored verbatim.", "optional": true }
+			}
+		},
+		"TokenNode": {
+			"description": "A value-bearing lineage node naming what it derives from.",
+			"fields": {
+				"name": { "type": "string", "description": "The token name, e.g. --bg-0." },
+				"value": { "type": "string", "description": "The resolved token value.", "optional": true },
+				"refs": { "type": { "array": "string" }, "description": "Names of the tokens this node derives from.", "optional": true }
+			}
+		},
+		"AlgorithmManifest": {
+			"description": "What an algorithm produces, the category of each token, and its knobs.",
+			"fields": {
+				"produces": { "type": { "array": "string" }, "description": "Every token name the algorithm emits." },
+				"categories": { "type": "map", "description": "Token name to category." },
+				"knobs": { "type": { "array": "string" }, "description": "Declared knob names." }
+			}
+		},
+		"InvariantResult": {
+			"description": "The outcome of a single per-algorithm invariant.",
+			"fields": {
+				"name": { "type": "string", "description": "The invariant's name." },
+				"ok": { "type": "boolean", "description": "Whether the invariant held." },
+				"detail": { "type": "string", "description": "A human-readable failure detail.", "optional": true }
+			}
+		},
+		"OklchColor": {
+			"description": "OKLCH coordinates: perceptual lightness, chroma, hue, and alpha.",
+			"fields": {
+				"l": { "type": "number", "description": "Perceptual lightness, 0–1." },
+				"c": { "type": "number", "description": "Chroma, 0+." },
+				"h": { "type": "number", "description": "Hue angle in degrees, 0–360." },
+				"alpha": { "type": "number", "description": "Opacity, 0–1." }
+			}
+		}
+	},
+	"limits": {
+		"timeout_ms": 5000,
+		"memory_mb": 16,
+		"max_stack_depth": 128
+	}
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@xtyle/core",
+	"version": "0.5.0",
+	"description": "A themable-derivation engine: an algorithm plus a few anchors derive a full register of CSS-ready tokens.",
+	"type": "module",
+	"license": "MIT",
+	"bin": {
+		"xtyle": "dist/cli.js"
+	},
+	"exports": {
+		".": "./dist/index.js",
+		"./elements": "./dist/elements/index.js",
+		"./elements/ssr": "./dist/elements/fragment-ssr.js",
+		"./elements/code-highlight": "./dist/elements/code-highlight.js",
+		"./algorithms": {
+			"types": "./algorithms.d.ts",
+			"default": "./dist/batteries.js"
+		},
+		"./authoring": "./dist/authoring.js",
+		"./concepts": "./dist/concepts.js",
+		"./dom": "./dist/dom.js",
+		"./css": "./dist/css/index.js",
+		"./markup": "./dist/markup/index.js",
+		"./host": "./dist/host/registry.js",
+		"./host/load": "./dist/host/index.js",
+		"./host/bundle": "./dist/host/bundle.js"
+	},
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"concepts",
+		"algorithms.d.ts",
+		"manifest.json",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.0",
+		"@xriptjs/runtime": "^0.7.0",
+		"culori": "^4.0.2",
+		"prism-svelte": "^0.5.0",
+		"prismjs": "^1.29.0",
+		"zod": "^3.23.8"
+	},
+	"devDependencies": {
+		"@types/culori": "^4.0.1",
+		"@types/node": "^22.0.0",
+		"@types/prismjs": "^1.26.0",
+		"typescript": "^5.5.0",
+		"vitest": "^2.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nekoyoubi/xtyle.git",
+		"directory": "packages/xtyle"
+	}
+}