@azphalt/importer-transition 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Az
+
+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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/** CLI for `@azphalt/importer-transition`: wrap a GL Transition into a `.azp` package. */
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { importGlTransition } from "./index.js";
+const USAGE = "usage: azphalt-import-transition <input.glsl> --id <reverse.dns.id> " +
+    "[-o out.azp] [--name N] [--version V] [--license SPDX] [--license-file PATH] [--author A]";
+function parse(argv) {
+    const a = {};
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        switch (t) {
+            case "-o":
+            case "--out":
+                a.out = argv[++i];
+                break;
+            case "--id":
+                a.id = argv[++i];
+                break;
+            case "--name":
+                a.name = argv[++i];
+                break;
+            case "--version":
+                a.version = argv[++i];
+                break;
+            case "--license":
+                a.license = argv[++i];
+                break;
+            case "--license-file":
+                a.licenseFile = argv[++i];
+                break;
+            case "--author":
+                a.author = argv[++i];
+                break;
+            default:
+                if (!t.startsWith("-") && !a.input)
+                    a.input = t;
+                else
+                    fail(`unknown argument: ${t}`);
+        }
+    }
+    return a;
+}
+function fail(msg) {
+    console.error(`error: ${msg}`);
+    console.error(USAGE);
+    process.exit(2);
+}
+const args = parse(process.argv.slice(2));
+if (!args.input)
+    fail("an input .glsl transition file is required");
+if (!args.id)
+    fail("--id <reverse-DNS id> is required (e.g. com.hereliesaz.crosswarp)");
+let source;
+try {
+    source = readFileSync(args.input, "utf8");
+}
+catch (e) {
+    fail(`failed to read input file: ${e.message}`);
+}
+let licenseText;
+if (args.licenseFile) {
+    try {
+        licenseText = readFileSync(args.licenseFile, "utf8");
+    }
+    catch (e) {
+        fail(`failed to read license file: ${e.message}`);
+    }
+}
+else {
+    const spdx = args.license ?? "MIT";
+    licenseText = `${spdx}\n\nProvide the full license text with --license-file.\n`;
+    console.error(`warning: no --license-file; writing a placeholder LICENSE (SPDX: ${spdx}).`);
+}
+const out = args.out ?? basename(args.input, extname(args.input)) + ".azp";
+const { azp, manifest, panel } = importGlTransition(source, licenseText, {
+    id: args.id,
+    name: args.name,
+    version: args.version,
+    license: args.license,
+    author: args.author,
+});
+writeFileSync(out, azp);
+console.error(`wrote ${out}  (${manifest.id} v${manifest.version}, ${panel.controls.length} control(s), ${azp.length} bytes)`);

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `@azphalt/importer-transition` — normalize a GL Transition (gl-transitions.com) into a `.azp`
+ * asset package. The GLSL source is stored verbatim; its tunable uniforms become an azphalt UI
+ * panel plus manifest params, so an adopting host — e.g. Guillotine, the video editor whose
+ * clip-to-clip transitions this feeds — renders the controls natively and runs the transition with
+ * its own engine. See `spec/package-format.md` § Assets.
+ */
+import { type WriteResult } from "@azphalt/azp";
+import type { Panel } from "@azphalt/sdk";
+import { type ParsedGlTransition } from "./parse-gl-transition.js";
+export interface TransitionImportOptions {
+    /** Reverse-DNS id, e.g. `"com.hereliesaz.crosswarp"`. Required. */
+    id: string;
+    /** Display name; defaults to the transition's `name` metadata, then the asset stem. */
+    name?: string;
+    /** Semver; default `"1.0.0"`. */
+    version?: string;
+    /** SPDX id for the manifest; default the transition's `License`, then `"MIT"`. */
+    license?: string;
+    author?: string;
+    /** Base name for the stored shader, e.g. `"crosswarp"` -> `assets/crosswarp.glsl`. */
+    assetName?: string;
+}
+export interface TransitionImportResult extends WriteResult {
+    parsed: ParsedGlTransition;
+    panel: Panel;
+}
+/** Parse a gl-transition, derive its UI panel, and package it as a `.azp` transition asset. */
+export declare function importGlTransition(source: string, licenseText: string, opts: TransitionImportOptions): TransitionImportResult;
+export { parseGlTransition, HOST_PROVIDED } from "./parse-gl-transition.js";
+export type { ParsedGlTransition, GlUniform } from "./parse-gl-transition.js";
+export { uniformsToPanel, uniformToControl, isHostBound } from "./ui.js";

package/dist/index.js

@@ -0,0 +1,58 @@
+/**
+ * `@azphalt/importer-transition` — normalize a GL Transition (gl-transitions.com) into a `.azp`
+ * asset package. The GLSL source is stored verbatim; its tunable uniforms become an azphalt UI
+ * panel plus manifest params, so an adopting host — e.g. Guillotine, the video editor whose
+ * clip-to-clip transitions this feeds — renders the controls natively and runs the transition with
+ * its own engine. See `spec/package-format.md` § Assets.
+ */
+import { writeAzp } from "@azphalt/azp";
+import { parseGlTransition } from "./parse-gl-transition.js";
+import { isHostBound, uniformsToPanel } from "./ui.js";
+const FORMAT = "0.1";
+/** Parse a gl-transition, derive its UI panel, and package it as a `.azp` transition asset. */
+export function importGlTransition(source, licenseText, opts) {
+    const parsed = parseGlTransition(source);
+    const stem = opts.assetName ?? slug(opts.name ?? parsed.name ?? "transition");
+    const assetPath = `assets/${stem}.glsl`;
+    const uiPath = `ui/${stem}.json`;
+    const panel = uniformsToPanel(parsed.uniforms);
+    const hasUi = panel.controls.length > 0;
+    const manifest = {
+        azphalt: FORMAT,
+        id: opts.id,
+        name: opts.name ?? parsed.name ?? stem,
+        version: opts.version ?? "1.0.0",
+        kind: "asset",
+        license: opts.license ?? parsed.license ?? "MIT",
+        compat: ">=0.1",
+        author: opts.author ?? parsed.author,
+        assets: [
+            {
+                type: "transition",
+                path: assetPath,
+                ...(hasUi ? { ui: uiPath } : {}),
+                params: {
+                    format: "gl-transition",
+                    ...(parsed.name ? { title: parsed.name } : {}),
+                    // Declared uniforms (including host-bound textures the host wires to the clips).
+                    uniforms: parsed.uniforms.map((u) => ({
+                        name: u.name,
+                        type: u.glslType,
+                        hostBound: isHostBound(u),
+                    })),
+                },
+            },
+        ],
+    };
+    const payload = { [assetPath]: new TextEncoder().encode(source) };
+    if (hasUi)
+        payload[uiPath] = new TextEncoder().encode(JSON.stringify(panel, null, 2) + "\n");
+    const result = writeAzp({ manifest, payload, license: licenseText });
+    return { ...result, parsed, panel };
+}
+/** Filesystem-safe stem: lowercase, runs of non-alphanumerics to single hyphens. */
+function slug(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "transition";
+}
+export { parseGlTransition, HOST_PROVIDED } from "./parse-gl-transition.js";
+export { uniformsToPanel, uniformToControl, isHostBound } from "./ui.js";

package/dist/parse-gl-transition.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Parser for the GL Transitions format (gl-transitions.com) — a GLSL fragment defining
+ * `vec4 transition(vec2 uv)`, with metadata in `//` comments and tunable `uniform` parameters
+ * annotated with a default (`uniform float intensity; // = 1.0`). The host supplies `from`/`to`
+ * (the two clips), `progress`, and `ratio`; those are not user parameters. We validate + describe
+ * — the original source is stored verbatim in the package.
+ */
+export interface GlUniform {
+    name: string;
+    /** GLSL type: `float` | `int` | `bool` | `vec2..4` | `ivec2..4` | `sampler2D` | … */
+    glslType: string;
+    /** Parsed default from the `// = …` annotation, if any. */
+    default?: number | boolean | number[];
+}
+export interface ParsedGlTransition {
+    name?: string;
+    author?: string;
+    license?: string;
+    /** User-tunable uniforms (excludes the host-provided `from`/`to`/`progress`/`ratio`). */
+    uniforms: GlUniform[];
+    source: string;
+}
+/** Uniforms the gl-transitions runtime provides — never user controls. */
+export declare const HOST_PROVIDED: ReadonlySet<string>;
+/** Parse gl-transition GLSL into a {@link ParsedGlTransition}. */
+export declare function parseGlTransition(source: string): ParsedGlTransition;

package/dist/parse-gl-transition.js

@@ -0,0 +1,66 @@
+/**
+ * Parser for the GL Transitions format (gl-transitions.com) — a GLSL fragment defining
+ * `vec4 transition(vec2 uv)`, with metadata in `//` comments and tunable `uniform` parameters
+ * annotated with a default (`uniform float intensity; // = 1.0`). The host supplies `from`/`to`
+ * (the two clips), `progress`, and `ratio`; those are not user parameters. We validate + describe
+ * — the original source is stored verbatim in the package.
+ */
+/** Uniforms the gl-transitions runtime provides — never user controls. */
+export const HOST_PROVIDED = new Set(["from", "to", "progress", "ratio"]);
+const VEC_SIZE = { vec2: 2, vec3: 3, vec4: 4, ivec2: 2, ivec3: 3, ivec4: 4 };
+function numbersIn(expr) {
+    // Strip GLSL identifiers (vec3, mix, …) so their digits aren't parsed as numbers, then match
+    // int/float literals including trailing-dot (`1.`) and exponent forms.
+    const clean = expr.replace(/\b[a-zA-Z_]\w*\b/g, "");
+    const matches = clean.match(/-?\d+(?:\.\d*)?(?:[eE][+-]?\d+)?|-?\.\d+(?:[eE][+-]?\d+)?/g) ?? [];
+    return matches.map(Number);
+}
+function parseDefault(glslType, expr) {
+    if (expr === undefined)
+        return undefined;
+    const e = expr.trim();
+    if (glslType === "bool")
+        return e === "true" || e === "1";
+    if (glslType === "float" || glslType === "int") {
+        const n = numbersIn(e)[0];
+        return n !== undefined && Number.isFinite(n) ? n : undefined;
+    }
+    const size = VEC_SIZE[glslType];
+    if (size) {
+        let nums = numbersIn(e); // identifiers are stripped, so vecN(...)'s own digit isn't captured
+        if (nums.length === 1)
+            nums = Array(size).fill(nums[0]); // GLSL vecN(x) fills all components
+        return nums.slice(0, size);
+    }
+    return undefined;
+}
+function scanMeta(source, key) {
+    const m = new RegExp(`//\\s*${key}\\s*:\\s*(.+)`, "i").exec(source);
+    return m ? m[1].trim() : undefined;
+}
+/** Parse gl-transition GLSL into a {@link ParsedGlTransition}. */
+export function parseGlTransition(source) {
+    if (!/\btransition\s*\(/.test(source)) {
+        throw new Error("gl-transition: source does not define a transition(...) function");
+    }
+    const uniforms = [];
+    const seen = new Set();
+    const re = /uniform\s+(?:(?:lowp|mediump|highp)\s+)?(\w+)\s+(\w+)\s*;[ \t]*(?:\/\/\s*=\s*([^\n\r]*))?/g;
+    let m;
+    while ((m = re.exec(source)) !== null) {
+        const [, glslType, name, defExpr] = m;
+        if (HOST_PROVIDED.has(name))
+            continue; // host binds these
+        if (seen.has(name))
+            throw new Error(`gl-transition: duplicate uniform '${name}'`);
+        seen.add(name);
+        uniforms.push({ name, glslType, default: parseDefault(glslType, defExpr) });
+    }
+    return {
+        name: scanMeta(source, "name"),
+        author: scanMeta(source, "author"),
+        license: scanMeta(source, "license"),
+        uniforms,
+        source,
+    };
+}

package/dist/ui.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Map gl-transition uniforms onto azphalt's host-rendered UI schema (`spec/ui-schema.md`), so a
+ * transition's parameters render natively in any adopting host. `sampler2D` uniforms are textures
+ * the host binds, not user controls, so they are excluded from the panel.
+ */
+import type { Control, Panel } from "@azphalt/sdk";
+import type { GlUniform } from "./parse-gl-transition.js";
+/** A texture uniform the host binds — not a user control. */
+export declare function isHostBound(u: GlUniform): boolean;
+/** Convert one uniform to an azphalt control, or `null` if it is host-bound / unmappable. */
+export declare function uniformToControl(u: GlUniform): Control | null;
+/** Build a {@link Panel} from a uniform list, skipping host-bound textures. */
+export declare function uniformsToPanel(uniforms: GlUniform[]): Panel;

package/dist/ui.js

@@ -0,0 +1,43 @@
+const VEC_SIZE = { vec2: 2, vec3: 3, vec4: 4, ivec2: 2, ivec3: 3, ivec4: 4 };
+/** A texture uniform the host binds — not a user control. */
+export function isHostBound(u) {
+    return u.glslType === "sampler2D";
+}
+/** Convert one uniform to an azphalt control, or `null` if it is host-bound / unmappable. */
+export function uniformToControl(u) {
+    const key = u.name;
+    const label = u.name;
+    if (u.glslType === "bool") {
+        return { type: "toggle", key, label, default: u.default === true };
+    }
+    if (u.glslType === "float" || u.glslType === "int") {
+        return { type: "number", key, label, default: typeof u.default === "number" ? u.default : 0 };
+    }
+    const size = VEC_SIZE[u.glslType];
+    if (size) {
+        const d = Array.isArray(u.default) ? u.default : [];
+        const controls = [];
+        for (let i = 0; i < size; i++) {
+            controls.push({
+                type: "number",
+                key: `${key}.${i}`,
+                label: `${label} ${i}`,
+                default: typeof d[i] === "number" ? d[i] : 0,
+            });
+        }
+        return { type: "group", key, label, controls };
+    }
+    return null; // sampler2D and unknown types
+}
+/** Build a {@link Panel} from a uniform list, skipping host-bound textures. */
+export function uniformsToPanel(uniforms) {
+    const controls = [];
+    for (const u of uniforms) {
+        if (isHostBound(u))
+            continue;
+        const c = uniformToControl(u);
+        if (c)
+            controls.push(c);
+    }
+    return { controls };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@azphalt/importer-transition",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Import GL Transitions (gl-transitions.com) into .azp transition assets.",
+  "license": "MIT",
+  "author": "Az (https://hereliesaz.com)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "azphalt-import-transition": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@azphalt/azp": "0.1.0",
+    "@azphalt/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.6",
+    "@types/node": "^22.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/readme.md

@@ -0,0 +1,35 @@
+# @azphalt/importer-transition
+
+Normalize a **GL Transition** ([gl-transitions.com](https://gl-transitions.com)) into a `.azp`
+transition asset. A gl-transition is a GLSL fragment defining `vec4 transition(vec2 uv)` with
+metadata in `//` comments and tunable `uniform` parameters (`uniform float intensity; // = 1.0`).
+The source is stored verbatim; its uniforms become an azphalt UI panel plus manifest params, so an
+adopting host — e.g. [Guillotine](https://github.com/HereLiesAz/Guillotine), whose clip-to-clip
+transitions this feeds — renders the controls natively and runs the transition with its own engine.
+
+This completes Guillotine's format trio alongside `@azphalt/importer-cube` (LUTs) and
+`@azphalt/importer-isf` (shaders).
+
+## uniforms → controls
+
+| GLSL uniform | azphalt control |
+|---|---|
+| `float` / `int` | `number` |
+| `bool` | `toggle` |
+| `vec2..4` / `ivec2..4` | `group` of `number`s |
+| `sampler2D`, and `from`/`to`/`progress`/`ratio` | *host-provided* — bound by the host, not user controls |
+
+## CLI
+
+~~~sh
+pnpm --filter @azphalt/importer-transition build
+azphalt-import-transition crosswarp.glsl --id com.hereliesaz.crosswarp -o crosswarp.azp
+~~~
+
+## Library
+
+~~~ts
+import { importGlTransition, parseGlTransition } from "@azphalt/importer-transition";
+
+const { azp, manifest, panel } = importGlTransition(glslSource, licenseText, { id: "com.hereliesaz.crosswarp" });
+~~~