@xenosystem/generate 0.0.1

package/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2026 XENO Corporation. All rights reserved.
+
+PROPRIETARY AND CONFIDENTIAL.
+
+This software and its source code are the confidential and proprietary property
+of XENO Corporation. No licence, express or implied, is granted to any person to
+use, copy, modify, merge, publish, distribute, sublicense, or sell copies of this
+software, in whole or in part, without the prior written permission of XENO
+Corporation.
+
+Unauthorised copying of this file, via any medium, is strictly prohibited.
+
+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/README.md

@@ -0,0 +1,33 @@
+# @xenosystem/generate
+
+**Declarations → per-platform artifacts**
+
+> Status: 🔵 **planned** — see [`../../SPEC.md`](../../SPEC.md) §13 for the build order.
+
+Turns `@xenosystem/elements` declarations into artifacts for each runtime — the Style
+Dictionary model, generalised past tokens to geometry and state machines.
+
+**Not built yet** — Phase 2.
+
+## Pipeline
+
+```
+Figma / XENO Canvas → SVGO (30–70% reduction) → declaration generator → @xenosystem/elements → CI
+                                                                              │
+                                    ┌─────────────────────────────────────────┤
+                                    ▼                    ▼                    ▼
+                             elements-react       XenoElementsKit      xenosystem-elements
+                                  (npm)              (SPM)                  (Maven)
+```
+
+Swift cannot be an npm package, which is why renderers ship on each runtime's native channel
+rather than pretending to be siblings in one scope.
+
+## Rules
+
+- **Never hand-author a renderer component.** 300 hand-maintained animated components will rot.
+- The generator is the only writer of generated output; generated files are marked as such and
+  are not edited by hand or by an agent.
+
+---
+Part of [`xeno-elements`](../../README.md). Visual authority: [`DESIGN_SYSTEM.md`](../../DESIGN_SYSTEM.md) — LOCKED.

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@xenosystem/generate` — the pipeline that turns declarations into per-platform artifacts.
+ *
+ * It is the ONLY writer of generated output (SPEC §6, README): renderers are generated, never
+ * hand-authored, so this package owns the geometry→markup interpretation and the pack manifest.
+ * Framework-free and platform-free; a native target adds its own emitter alongside `renderSvg`.
+ *
+ * @module
+ */
+export { interpret, type Scene, type SceneOptions, type ShapeNode, type RectNode, type PathNode, } from './scene.js';
+export { renderSvg, sceneToSvg, type RenderOptions } from './svg.js';
+export { buildManifest, toEntry, type Manifest, type ManifestEntry } from './manifest.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@xenosystem/generate` — the pipeline that turns declarations into per-platform artifacts.
+ *
+ * It is the ONLY writer of generated output (SPEC §6, README): renderers are generated, never
+ * hand-authored, so this package owns the geometry→markup interpretation and the pack manifest.
+ * Framework-free and platform-free; a native target adds its own emitter alongside `renderSvg`.
+ *
+ * @module
+ */
+export { interpret, } from './scene.js';
+export { renderSvg, sceneToSvg } from './svg.js';
+export { buildManifest, toEntry } from './manifest.js';

package/dist/manifest.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The MANIFEST: a flat, sorted index of every element in a pack — the catalogue a foundry, a docs
+ * site, or a consumer's build reads to know what exists WITHOUT importing 300 declaration modules.
+ * Pure projection of the declarations; carries no geometry (that lives in the per-element artifacts).
+ */
+import type { ElementDeclaration } from '@xenosystem/elements/schema';
+export interface ManifestEntry {
+    readonly id: string;
+    readonly kind: ElementDeclaration['kind'];
+    readonly viewBox: string;
+    readonly weight: string;
+    /** Axes the element honours — empty for a degenerate icon. */
+    readonly axes: readonly string[];
+    readonly signals: readonly string[];
+    /** Geometry variant keys beyond `base` (e.g. `selection:on`), sorted. */
+    readonly variants: readonly string[];
+    readonly tags: readonly string[];
+    readonly since: string | null;
+    readonly role: string;
+    readonly label: string;
+}
+export interface Manifest {
+    readonly count: number;
+    readonly elements: readonly ManifestEntry[];
+}
+export declare const toEntry: (d: ElementDeclaration) => ManifestEntry;
+export declare const buildManifest: (decls: readonly ElementDeclaration[]) => Manifest;

package/dist/manifest.js

@@ -0,0 +1,20 @@
+const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+export const toEntry = (d) => ({
+    id: d.id,
+    kind: d.kind,
+    viewBox: d.contract.viewBox,
+    weight: d.contract.weight,
+    axes: d.contract.axes,
+    signals: d.contract.signals,
+    variants: Object.keys(d.geometry)
+        .filter((k) => k !== 'base')
+        .sort(),
+    tags: d.meta?.tags ?? [],
+    since: d.meta?.since ?? null,
+    role: d.a11y.role,
+    label: d.a11y.label,
+});
+export const buildManifest = (decls) => {
+    const elements = decls.map(toEntry).sort(byId);
+    return { count: elements.length, elements };
+};

package/dist/scene.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The one INTERPRETATION of a declaration, shared by every web-side renderer. It resolves the axis
+ * state to a geometry variant, turns each primitive into a neutral draw node, and resolves fill
+ * TOKENS to paint — all the fail-closed decisions live here, exactly once. A serializer (SVG string,
+ * {@link ./svg.ts}) and a framework renderer (`elements-react`) each consume this Scene and map it to
+ * their own attribute dialect (`stroke-width` vs `strokeWidth`), so the two can never drift on what
+ * to draw — only on how to spell it.
+ */
+import type { ElementDeclaration, ElementState } from '@xenosystem/elements/schema';
+export interface SceneOptions {
+    /** Discrete state to render. Missing axes fall back to the default (enabled / off / idle). */
+    readonly state?: Partial<ElementState>;
+    /** Pixel width/height on the root. Default 24. The viewBox is always the declared one. */
+    readonly size?: number;
+    /** Override the weight-derived stroke width. */
+    readonly strokeWidth?: number;
+    /** Extra class on the root element. */
+    readonly className?: string;
+}
+/**
+ * A resolved draw node. `fill` is the RESOLVED paint (`currentColor`) for a solid part, or `undefined`
+ * for an outline part that inherits the root's `stroke:currentColor; fill:none`.
+ */
+export interface RectNode {
+    readonly kind: 'rect';
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly rx?: number;
+    readonly fill?: string;
+}
+export interface PathNode {
+    readonly kind: 'path';
+    readonly d: string;
+    readonly fill?: string;
+    readonly fillRule?: 'nonzero' | 'evenodd';
+}
+export type ShapeNode = RectNode | PathNode;
+/** The fully-resolved thing to draw. Neutral: no attribute-name dialect committed to yet. */
+export interface Scene {
+    readonly viewBox: string;
+    readonly size: number;
+    readonly strokeWidth: number;
+    readonly role: string;
+    readonly label: string;
+    /** Short glyph name (id without the `xeno.` prefix) — emitted as `data-glyph`, the hook the
+     * animated-icon stylesheet targets so each glyph can carry its own motion. */
+    readonly glyph: string;
+    /** `data-<axis>` values for the axes the element DECLARES it honours (empty for a degenerate icon). */
+    readonly data: Readonly<Record<`data-${string}`, string>>;
+    readonly className: string | undefined;
+    /**
+     * Whether what is being drawn can be interpolated back to `base` — same primitive count, same kind at
+     * every index.
+     *
+     * The interpreter does not animate anything; it says only that an animation is POSSIBLE, which is the
+     * whole point. A scene that reports `morph` lets a stylesheet interpolate the path data, one that does
+     * not lets it swap, and neither needs an animation runtime to decide which. `geometryMorphable` has sat
+     * in the schema since the start as a check nothing consumed; this is what consumes it.
+     *
+     * `base` itself counts as morphable, because a control that morphs has to morph BACK — and the state
+     * it returns to is base. Answering `false` there would animate the outbound half and snap the return.
+     */
+    readonly morph: boolean;
+    readonly shapes: readonly ShapeNode[];
+}
+/** Interpret a declaration + state into a neutral, fully-resolved {@link Scene}. Fails closed. */
+export declare const interpret: (decl: ElementDeclaration, opts?: SceneOptions) => Scene;

package/dist/scene.js

@@ -0,0 +1,99 @@
+import { geometryMorphable } from '@xenosystem/elements/schema';
+/**
+ * The state a renderer shows when an axis is unspecified — the same values as the contract's
+ * `DEFAULT_STATE`, kept local so the interpreter stays a pure emitter with no runtime import from the
+ * contract package (type-only imports keep the shipped code platform-free).
+ */
+const DEFAULT_STATE = {
+    availability: 'enabled',
+    selection: 'off',
+    interaction: 'idle',
+};
+/**
+ * Weight → stroke width, in viewBox units. A RENDERER decision (the declaration names a `weight`
+ * family, not a number), so it lives here and is revisable without touching a single declaration.
+ * `regular` = 1.75 matches the value the foundry workbench shipped and the design approved.
+ */
+const WEIGHT_STROKE = { light: 1.25, regular: 1.75, bold: 2.25 };
+/**
+ * Fill token → CSS paint. The XENO grammar is monochrome: the single ink is `currentColor`, so it
+ * inherits the surrounding text colour on every surface. Extend this map when the design system adds
+ * a painted role — never by letting a literal colour through.
+ */
+const FILL_PAINT = { foreground: 'currentColor' };
+/**
+ * When more than one axis has a matching `<axis>:<value>` geometry variant, the more TRANSIENT axis
+ * wins — a press should read over a selection, a selection over mere availability. Rarely collides
+ * (most elements vary on one axis), but the order must be defined, not incidental.
+ */
+const AXIS_PRECEDENCE = ['availability', 'selection', 'interaction'];
+const finite = (n) => {
+    if (!Number.isFinite(n))
+        throw new Error(`interpret: non-finite coordinate ${String(n)}`);
+    return n;
+};
+const paintFor = (token) => {
+    if (token === 'none')
+        return 'none';
+    const paint = FILL_PAINT[token];
+    if (paint === undefined) {
+        throw new Error(`interpret: unknown fill token '${token}'. A fill must reference a design-system token, ` +
+            `never a literal colour (SPEC §14.2 — the guard fails closed).`);
+    }
+    return paint;
+};
+const listOf = (g) => typeof g === 'string' ? [{ kind: 'path', d: g }] : g;
+/** Pick the geometry variant the state addresses: `base`, overridden by any matching `<axis>:<value>`. */
+const activeGeometry = (decl, state) => {
+    let geometry = decl.geometry.base;
+    for (const axis of AXIS_PRECEDENCE) {
+        const variant = decl.geometry[`${axis}:${state[axis]}`];
+        if (variant !== undefined)
+            geometry = variant;
+    }
+    return geometry;
+};
+const shapeOf = (p) => {
+    if (p.kind === 'rect') {
+        const base = {
+            kind: 'rect',
+            x: finite(p.x),
+            y: finite(p.y),
+            w: finite(p.w),
+            h: finite(p.h),
+        };
+        return {
+            ...base,
+            ...(p.rx !== undefined ? { rx: finite(p.rx) } : {}),
+            ...(p.fill !== undefined ? { fill: paintFor(p.fill) } : {}),
+        };
+    }
+    return {
+        kind: 'path',
+        d: p.d,
+        ...(p.fill !== undefined ? { fill: paintFor(p.fill) } : {}),
+        ...(p.fillRule ? { fillRule: p.fillRule } : {}),
+    };
+};
+/** Interpret a declaration + state into a neutral, fully-resolved {@link Scene}. Fails closed. */
+export const interpret = (decl, opts = {}) => {
+    const state = { ...DEFAULT_STATE, ...opts.state };
+    const data = {};
+    for (const axis of decl.contract.axes)
+        data[`data-${axis}`] = state[axis];
+    const active = activeGeometry(decl, state);
+    return {
+        viewBox: decl.contract.viewBox,
+        size: opts.size ?? 24,
+        strokeWidth: opts.strokeWidth ?? WEIGHT_STROKE[decl.contract.weight],
+        role: decl.a11y.role,
+        label: decl.a11y.label,
+        glyph: decl.id.replace(/^xeno\./, ''),
+        data,
+        className: opts.className,
+        // A declaration with only `base` has nowhere to morph TO. It would trivially pass the check, and
+        // marking it would put a `d` transition on every path of every icon in the set to animate nothing.
+        morph: Object.keys(decl.geometry).length > 1 && geometryMorphable(decl.geometry.base, active),
+        shapes: listOf(active).map(shapeOf),
+    };
+};

package/dist/svg.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SVG-string serializer: one dialect of the shared {@link interpret} Scene. Turns a declaration into
+ * a self-contained `<svg>` string — the artifact the build writes to disk, the foundry previews, and
+ * the reference for what "visually indistinguishable" means on the web (SPEC §6).
+ *
+ * All the drawing DECISIONS (variant selection, token→paint, fail-closed guards) live in
+ * {@link ./scene.ts}; this file only spells the resolved Scene as SVG markup.
+ */
+import type { ElementDeclaration } from '@xenosystem/elements/schema';
+import { type Scene, type SceneOptions } from './scene.js';
+export type RenderOptions = SceneOptions;
+/** Serialize a resolved {@link Scene} to an SVG string. */
+export declare const sceneToSvg: (scene: Scene) => string;
+/**
+ * Interpret a declaration into an SVG string. The root carries the outline defaults plus one
+ * `data-<axis>` attribute for every axis the element declares — the CSS-first seam a stylesheet
+ * targets to drive state transitions with zero JS. Degenerate icons (no axes) get none.
+ */
+export declare const renderSvg: (decl: ElementDeclaration, opts?: RenderOptions) => string;

package/dist/svg.js

@@ -0,0 +1,50 @@
+import { interpret } from './scene.js';
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/**
+ * Paint attributes for one shape. An outline part (no `fill`) inherits the root's
+ * `fill:none; stroke:currentColor`, so we emit nothing. A solid part is painted and explicitly
+ * un-stroked, so its ink is crisp instead of haloed by the outline stroke.
+ */
+const paintAttrs = (fill) => fill === undefined ? '' : ` fill="${fill}" stroke="none"`;
+// Each shape carries a stable `xeno-part` class + `data-part` index (its position in the geometry),
+// so a stylesheet can animate an icon's INDIVIDUAL parts — the hook for representative icon motion.
+const shapeSvg = (s, i, morph) => {
+    const part = ` class="xeno-part" data-part="${i}"`;
+    // A morphable path carries its own `d` a SECOND time, as a custom property. The attribute stays the
+    // fallback (and stays authoritative where CSS `d` is unsupported); the property is what a stylesheet
+    // can interpolate, because a custom property changing is a computed-value change and `d` transitions.
+    // The quotes are written as entities on purpose: React escapes apostrophes inside a style attribute
+    // and this serializer does not, and the two renderers are held to byte-for-byte parity (SPEC §6). One
+    // of them had to give, and the entity is what both agree on.
+    const morphD = morph && s.kind === 'path' ? ` style="--part-d:path(&#x27;${esc(s.d)}&#x27;)"` : '';
+    if (s.kind === 'rect') {
+        const rx = s.rx !== undefined ? ` rx="${s.rx}"` : '';
+        return `<rect x="${s.x}" y="${s.y}" width="${s.w}" height="${s.h}"${rx}${paintAttrs(s.fill)}${part}/>`;
+    }
+    const fillRule = s.fillRule ? ` fill-rule="${s.fillRule}"` : '';
+    // `d` is escaped like every other attribute value. It has never needed it — no shipped glyph has a
+    // quote in its path data — but it was the one place this serializer was fail-OPEN, in a pipeline
+    // whose whole point is that it is not: `interpret` throws on a non-finite coordinate and on a fill
+    // that is not a token, and then this let an arbitrary string through into markup unchecked.
+    return `<path d="${esc(s.d)}"${fillRule}${paintAttrs(s.fill)}${part}${morphD}/>`;
+};
+/** Serialize a resolved {@link Scene} to an SVG string. */
+export const sceneToSvg = (scene) => {
+    const data = Object.entries(scene.data)
+        .map(([k, v]) => ` ${k}="${v}"`)
+        .join('');
+    const className = scene.className ? ` class="${esc(scene.className)}"` : '';
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${scene.size}" height="${scene.size}" ` +
+        `viewBox="${scene.viewBox}" fill="none" stroke="currentColor" ` +
+        `stroke-width="${scene.strokeWidth}" stroke-linecap="butt" stroke-linejoin="round" ` +
+        `role="${esc(scene.role)}" aria-label="${esc(scene.label)}" data-glyph="${esc(scene.glyph)}"` +
+        `${scene.morph ? ' data-morph="on"' : ''}${data}${className}>` +
+        scene.shapes.map((s, i) => shapeSvg(s, i, scene.morph)).join('') +
+        `</svg>`);
+};
+/**
+ * Interpret a declaration into an SVG string. The root carries the outline defaults plus one
+ * `data-<axis>` attribute for every axis the element declares — the CSS-first seam a stylesheet
+ * targets to drive state transitions with zero JS. Degenerate icons (no axes) get none.
+ */
+export const renderSvg = (decl, opts = {}) => sceneToSvg(interpret(decl, opts));

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xenosystem/generate",
+  "version": "0.0.1",
+  "license": "UNLICENSED",
+  "description": "XENO declarations \u2192 per-platform artifacts. The only writer of generated output.",
+  "author": "XENO Corporation <emilian@bnkrsys.com>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "npm run build -w @xenosystem/elements",
+    "build": "tsc -p tsconfig.json",
+    "pretypecheck": "npm run build -w @xenosystem/elements",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "artifacts": "npm run build && node scripts/build-artifacts.mjs"
+  },
+  "dependencies": {
+    "@xenosystem/elements": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}