@gjsify/cli 0.3.5 → 0.3.7

package/lib/actions/build.js

@@ -1,116 +1,30 @@
 import { build } from "esbuild";
 import { gjsifyPlugin } from "@gjsify/esbuild-plugin-gjsify";
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, } from "@gjsify/esbuild-plugin-gjsify/globals";
-import { dirname, extname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { getBundleDir, rewriteContents } from "@gjsify/esbuild-plugin-gjsify";
+import { getPnpPlugin } from "@gjsify/resolve-npm/pnp-relay";
+import { dirname, extname } from "node:path";
 import { chmod, readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
-/** Walk up from dir until .pnp.cjs is found; return its directory or null. */
-function findPnpRoot(dir) {
-    let current = dir;
-    while (true) {
-        if (existsSync(join(current, ".pnp.cjs")))
-            return current;
-        const parent = dirname(current);
-        if (parent === current)
-            return null;
-        current = parent;
-    }
-}
 /**
- * If the current project uses Yarn PnP, return the official
- * @yarnpkg/esbuild-plugin-pnp plugin so esbuild can resolve
- * modules from zip archives without manual extraction.
+ * Resolve the gjsify-flavoured PnP plugin. Anchors the relay on this file's
+ * URL so transitive `@gjsify/*` polyfills (reached via @gjsify/cli's deps on
+ * @gjsify/{node,web}-polyfills) are resolvable for external consumers without
+ * each one having to be a direct devDep.
  *
- * Custom onResolve: when the project's PnP context throws
- * UNDECLARED_DEPENDENCY, retry via a two-hop relay:
- *   1. @gjsify/cli context (direct dep of the project using gjsify build)
- *   2. @gjsify/node-polyfills context (direct dep of @gjsify/cli, has all
- *      node polyfills as direct deps including @gjsify/node-globals)
- *   3. @gjsify/web-polyfills context (direct dep of @gjsify/cli, has all
- *      web polyfills as direct deps including @gjsify/fetch, @gjsify/abort-controller)
- * For bare specifiers that the gjsify alias plugin maps (e.g. `abort-controller`),
- * fall through so that plugin can handle the transformation first.
+ * Wires the @gjsify/esbuild-plugin-gjsify rewriter (`__filename`/`__dirname`
+ * injection for CJS code in node_modules) into the pnp plugin's onLoad —
+ * esbuild stops at the first matching onLoad, so the rewriter MUST run from
+ * inside the pnp plugin's onLoad rather than as a separate registration.
  */
-async function getPnpPlugin() {
-    if (!findPnpRoot(process.cwd()))
-        return null;
-    try {
-        const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
-        // gjsify's own file path — @gjsify/cli has node-polyfills + web-polyfills
-        // as direct deps, so we can resolve them as relay issuers from here.
-        const gjsifyIssuer = fileURLToPath(import.meta.url);
-        // Two-hop relay: node-polyfills and web-polyfills have all individual
-        // @gjsify/* packages as direct deps. Resolving from their package.json
-        // paths allows PnP to use them as issuers — sub-path imports
-        // (`@gjsify/foo/register/bar`) then resolve through the polyfill's
-        // dep graph. Resolve to package.json (always present, exports-agnostic)
-        // rather than main/module (the polyfills meta packages have no main).
-        const requireFromGjsify = createRequire(gjsifyIssuer);
-        const relayIssuers = [];
-        for (const pkg of ["@gjsify/node-polyfills", "@gjsify/web-polyfills"]) {
-            try {
-                relayIssuers.push(requireFromGjsify.resolve(`${pkg}/package.json`));
-            }
-            catch {
-                // polyfills package not in dep tree — relay won't cover it
-            }
-        }
-        let pnpApi = null;
-        try {
-            // pnpapi has no npm package — it is a virtual module injected by Yarn PnP
-            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            // @ts-expect-error
-            pnpApi = (await import("pnpapi"));
-        }
-        catch {
-            // Not in a PnP runtime (shouldn't happen since findPnpRoot passed)
-        }
-        return pnpPlugin({
-            onResolve: async (args, { resolvedPath, error, watchFiles }) => {
-                if (resolvedPath !== null) {
-                    return { namespace: "pnp", path: resolvedPath, watchFiles };
-                }
-                if (error?.pnpCode ===
-                    "UNDECLARED_DEPENDENCY") {
-                    if (pnpApi !== null) {
-                        // Try @gjsify/cli context first (covers @gjsify/* that are
-                        // direct deps of cli's own deps — unlikely but fast check).
-                        try {
-                            const rp = pnpApi.resolveRequest(args.path, gjsifyIssuer);
-                            if (rp !== null)
-                                return { namespace: "pnp", path: rp, watchFiles };
-                        }
-                        catch { }
-                        // Two-hop relay: resolve from node-polyfills / web-polyfills context
-                        // which have the individual @gjsify/* packages as direct deps.
-                        for (const relayIssuer of relayIssuers) {
-                            try {
-                                const rp = pnpApi.resolveRequest(args.path, relayIssuer);
-                                if (rp !== null)
-                                    return { namespace: "pnp", path: rp, watchFiles };
-                            }
-                            catch { }
-                        }
-                    }
-                    // Fall through — bare aliases (abort-controller, fetch/register/*)
-                    // are handled by the gjsify alias plugin after this returns null,
-                    // then the re-resolved @gjsify/* path goes through this hook again.
-                    return null;
-                }
-                return {
-                    external: true,
-                    errors: error ? [{ text: error.message }] : [],
-                    watchFiles,
-                };
-            },
-        });
-    }
-    catch {
-        return null;
-    }
+async function buildPnpPlugin() {
+    return getPnpPlugin({
+        issuerUrl: import.meta.url,
+        transformContentsFactory: (build) => {
+            const bundleDir = getBundleDir(build);
+            return (args, contents) => rewriteContents(args, contents, bundleDir);
+        },
+    });
 }
 export class BuildAction {
     configData;
@@ -134,7 +48,7 @@ export class BuildAction {
         const moduleOutExt = library.module ? extname(library.module) : ".js";
         const mainOutExt = library.main ? extname(library.main) : ".js";
         const multipleBuilds = moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
-        const pnpPlugin = await getPnpPlugin();
+        const pnpPlugin = await buildPnpPlugin();
         const pnpPlugins = pnpPlugin ? [pnpPlugin] : [];
         const results = [];
         if (multipleBuilds) {
@@ -292,7 +206,7 @@ export class BuildAction {
             ...(aliases ? { aliases } : {}),
         };
         const { autoMode, extras } = this.parseGlobalsValue(globals);
-        const pnpPlugin = await getPnpPlugin();
+        const pnpPlugin = await buildPnpPlugin();
         const pnpPlugins = pnpPlugin ? [pnpPlugin] : [];
         // --- Auto mode (with optional extras): iterative multi-pass build ---
         // The extras token is used for cases where the detector cannot

package/lib/commands/index.d.ts

@@ -7,3 +7,4 @@ export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
 export * from './dlx.js';
+export * from './install.js';

package/lib/commands/index.js

@@ -7,3 +7,4 @@ export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
 export * from './dlx.js';
+export * from './install.js';

package/lib/commands/install.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from '../types/index.js';
+interface InstallOptions {
+    packages?: string[];
+    'save-dev'?: boolean;
+    'save-peer'?: boolean;
+    'save-optional'?: boolean;
+    verbose: boolean;
+}
+export declare const installCommand: Command<any, InstallOptions>;
+export {};

package/lib/commands/install.js

@@ -0,0 +1,99 @@
+// `gjsify install [pkg...]` — thin npm wrapper with gjsify-aware post-checks.
+//
+// The actual install is delegated to `npm install` in the user's project root
+// (no `--prefix` rewrite, unlike `gjsify dlx`). After install completes we run
+// `runMinimalChecks()` so missing system deps (gjs, gtk4, libsoup, ...) surface
+// immediately, and report any installed `@gjsify/*` packages that ship native
+// prebuilds so users know they can use `gjsify run` to wire `LD_LIBRARY_PATH` /
+// `GI_TYPELIB_PATH` automatically.
+//
+// Modes:
+//   gjsify install                    → project install (npm install)
+//   gjsify install <pkg> [<pkg>...]   → add package(s) (npm install <pkg>...)
+import { spawn } from 'node:child_process';
+import { buildInstallCommand, detectPackageManager, runMinimalChecks, } from '../utils/check-system-deps.js';
+import { detectNativePackages } from '../utils/detect-native-packages.js';
+export const installCommand = {
+    command: 'install [packages..]',
+    description: 'Install npm dependencies in the current project, then run gjsify-aware post-checks.',
+    builder: (yargs) => yargs
+        .positional('packages', {
+        description: 'Optional package specs. With none, runs a full project install.',
+        type: 'string',
+        array: true,
+    })
+        .option('save-dev', { type: 'boolean', alias: 'D' })
+        .option('save-peer', { type: 'boolean' })
+        .option('save-optional', { type: 'boolean', alias: 'O' })
+        .option('verbose', {
+        description: 'Verbose npm logging.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const npmArgs = ['install'];
+        if (args['save-dev'])
+            npmArgs.push('--save-dev');
+        if (args['save-peer'])
+            npmArgs.push('--save-peer');
+        if (args['save-optional'])
+            npmArgs.push('--save-optional');
+        if (args.verbose)
+            npmArgs.push('--loglevel', 'verbose');
+        if (args.packages && args.packages.length > 0) {
+            npmArgs.push(...args.packages);
+        }
+        await spawnNpm(npmArgs);
+        await runPostInstallChecks();
+    },
+};
+async function spawnNpm(npmArgs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('npm', npmArgs, { stdio: 'inherit' });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npm install exited with code ${code}`));
+        });
+        child.on('error', (err) => {
+            const code = err.code;
+            const msg = code === 'ENOENT'
+                ? 'npm not found on PATH — install Node.js first.'
+                : `npm install failed: ${err.message}`;
+            reject(new Error(msg));
+        });
+    }).catch((err) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}
+async function runPostInstallChecks() {
+    console.log('\n--- gjsify post-install checks ---');
+    // 1. System deps that GJS apps typically need.
+    const results = runMinimalChecks();
+    const missing = results.filter((r) => !r.found && r.severity === 'required');
+    if (missing.length > 0) {
+        console.warn('Missing required system dependencies:\n');
+        for (const dep of missing) {
+            console.warn(`  ✗  ${dep.name}`);
+        }
+        const pm = detectPackageManager();
+        const cmd = buildInstallCommand(pm, missing);
+        if (cmd)
+            console.warn(`\nInstall with:\n  ${cmd}`);
+    }
+    else {
+        console.log('System dependencies OK.');
+    }
+    // 2. Surface @gjsify/* packages with native prebuilds — `gjsify run`
+    //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
+    const native = detectNativePackages(process.cwd());
+    if (native.length > 0) {
+        console.log(`\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`);
+        for (const pkg of native) {
+            console.log(`  • ${pkg.name}`);
+        }
+        console.log('\nUse `gjsify run <bundle>` to launch with LD_LIBRARY_PATH/GI_TYPELIB_PATH set.');
+    }
+}

package/lib/commands/showcase.js

@@ -1,26 +1,25 @@
 import { discoverShowcases, findShowcase } from '../utils/discover-showcases.js';
-import { runMinimalChecks, checkGwebgl, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
-import { runGjsBundle } from '../utils/run-gjs.js';
+import { runMinimalChecks, checkGwebgl, detectPackageManager, buildInstallCommand, } from '../utils/check-system-deps.js';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 export const showcaseCommand = {
     command: 'showcase [name]',
-    description: 'List or run built-in gjsify showcase applications.',
-    builder: (yargs) => {
-        return yargs
-            .positional('name', {
-            description: 'Showcase name to run (omit to list all)',
-            type: 'string',
-        })
-            .option('json', {
-            description: 'Output as JSON',
-            type: 'boolean',
-            default: false,
-        })
-            .option('list', {
-            description: 'List available showcases',
-            type: 'boolean',
-            default: false,
-        });
-    },
+    description: 'List or run curated gjsify showcase applications.',
+    builder: (yargs) => yargs
+        .positional('name', {
+        description: 'Showcase name to run (omit to list all)',
+        type: 'string',
+    })
+        .option('json', {
+        description: 'Output as JSON',
+        type: 'boolean',
+        default: false,
+    })
+        .option('list', {
+        description: 'List available showcases',
+        type: 'boolean',
+        default: false,
+    }),
     handler: async (args) => {
         // List mode: no name given, or --list flag
         if (!args.name || args.list) {
@@ -30,10 +29,9 @@ export const showcaseCommand = {
                 return;
             }
             if (showcases.length === 0) {
-                console.log('No showcases found. Showcase packages may not be installed.');
+                console.log('No showcases found. The CLI ships a curated list in `showcases.json`; if it is missing the CLI install is incomplete.');
                 return;
             }
-            // Group by category
             const grouped = new Map();
             for (const sc of showcases) {
                 const list = grouped.get(sc.category) ?? [];
@@ -43,7 +41,7 @@ export const showcaseCommand = {
             console.log('Available gjsify showcases:\n');
             for (const [category, list] of grouped) {
                 console.log(`  ${category.toUpperCase()}:`);
-                const maxNameLen = Math.max(...list.map(e => e.name.length));
+                const maxNameLen = Math.max(...list.map((e) => e.name.length));
                 for (const sc of list) {
                     const pad = ' '.repeat(maxNameLen - sc.name.length + 2);
                     const desc = sc.description ? `${pad}${sc.description}` : '';
@@ -54,23 +52,18 @@ export const showcaseCommand = {
             console.log('Run a showcase:  gjsify showcase <name>');
             return;
         }
-        // Run mode: find the showcase
         const showcase = findShowcase(args.name);
         if (!showcase) {
             console.error(`Unknown showcase: "${args.name}"`);
             console.error('Run "gjsify showcase" to list available showcases.');
             process.exit(1);
         }
-        // System dependency check before running — only check what this showcase needs.
-        // All showcases need GJS; WebGL showcases additionally need gwebgl prebuilds.
+        // System dependency check before delegating — only what this showcase needs.
         const results = runMinimalChecks();
-        const needsWebgl = showcase.packageName.includes('webgl') || showcase.packageName.includes('three');
-        if (needsWebgl) {
+        if (showcase.needsWebgl) {
             results.push(checkGwebgl(process.cwd()));
         }
-        // Hard-fail only on missing REQUIRED deps (gjs, gwebgl is required if needsWebgl).
-        // For showcase, gwebgl is treated as required because the bundle won't run without it.
-        const missingHard = results.filter(r => !r.found && (r.severity === 'required' || r.id === 'gwebgl'));
+        const missingHard = results.filter((r) => !r.found && (r.severity === 'required' || r.id === 'gwebgl'));
         if (missingHard.length > 0) {
             console.error('Missing system dependencies:\n');
             for (const dep of missingHard) {
@@ -83,8 +76,27 @@ export const showcaseCommand = {
             }
             process.exit(1);
         }
-        // Run the showcase via shared GJS runner
-        console.log(`Running showcase: ${showcase.name}\n`);
-        await runGjsBundle(showcase.bundlePath);
+        // Delegate to `gjsify dlx <package>` — same npm-cache, same atomic
+        // symlink-swap, same `gjsify.main` resolution. Re-spawning the CLI
+        // keeps the dlx logic in one place.
+        console.log(`Running showcase: ${showcase.name} (via gjsify dlx)\n`);
+        const cliBin = fileURLToPath(new URL('../index.js', import.meta.url));
+        const child = spawn(process.execPath, [cliBin, 'dlx', showcase.packageName], {
+            stdio: 'inherit',
+        });
+        await new Promise((resolvePromise, reject) => {
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`gjsify dlx exited with code ${code}`));
+                }
+                else {
+                    resolvePromise();
+                }
+            });
+            child.on('error', reject);
+        }).catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
     },
 };

package/lib/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, dlxCommand as dlx, } from './commands/index.js';
+import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, dlxCommand as dlx, installCommand as install, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
     .command(create.command, create.description, create.builder, create.handler)
+    .command(install.command, install.description, install.builder, install.handler)
     .command(build.command, build.description, build.builder, build.handler)
     .command(run.command, run.description, run.builder, run.handler)
     .command(dlx.command, dlx.description, dlx.builder, dlx.handler)

package/lib/utils/check-system-deps.js

@@ -96,8 +96,13 @@ const PACKAGE_DEPS = {
     '@gjsify/canvas2d': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/canvas2d-core': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/dom-elements': ['gdk-pixbuf'],
-    // @gjsify/webgl, @gjsify/event-bridge only need gtk4/gdk which are
-    // already in the required set, so they don't need optional entries.
+    // @gjsify/webgl needs the gwebgl npm package (Vala prebuild) — handled
+    // as a special-case checkNpmPackage rather than checkPkgConfig in
+    // runOptionalChecks. Mapping it here so its presence in the project's
+    // dep tree triggers the check.
+    '@gjsify/webgl': ['gwebgl'],
+    // @gjsify/event-bridge only needs gtk4/gdk which are already in the
+    // required set, so it doesn't need an optional entry.
 };
 /** Walk up from cwd looking for the nearest package.json. */
 function findProjectRoot(cwd) {
@@ -241,10 +246,16 @@ function runOptionalChecks(needed, cwd) {
             .map(([pkg]) => pkg);
         results.push(checkPkgConfig(dep.id, dep.name, dep.pkgName, 'optional', requiredBy));
     }
-    // gwebgl npm package — special case (not a pkg-config lib).
-    // Always reported (the npm package is bundled with the CLI), but marked
-    // optional because only @gjsify/webgl users need it.
-    results.push(checkGwebgl(cwd));
+    // gwebgl npm package — special case (not a pkg-config lib). Only checked
+    // when the project directly or transitively depends on @gjsify/webgl —
+    // since the CLI tarball no longer ships any showcase example packages,
+    // gwebgl is not part of the CLI's own dep tree, so reporting it for every
+    // project would always be `found: false`. `needed === null` means "check
+    // everything" (no project context).
+    const hasWebglDep = needed === null || needed.has('gwebgl');
+    if (hasWebglDep) {
+        results.push(checkGwebgl(cwd));
+    }
     return results;
 }
 // Per-package-manager install package names, keyed by dep id.

package/lib/utils/discover-showcases.d.ts

@@ -5,14 +5,15 @@ export interface ShowcaseInfo {
     packageName: string;
     /** Category: "dom" or "node" */
     category: string;
-    /** Description from showcase's package.json */
+    /** Description for the list view */
     description: string;
-    /** Absolute path to the GJS bundle (resolved from "main" field) */
-    bundlePath: string;
+    /** Whether the showcase needs the gwebgl native prebuild. */
+    needsWebgl: boolean;
 }
 /**
- * Discover all installed showcase packages by scanning the CLI's own dependencies.
- * Returns showcases sorted by category then name.
+ * Read the curated showcase list from `showcases.json`. Returns showcases
+ * sorted by category then name. An empty list (or missing manifest) yields
+ * an empty array — `gjsify showcase` then prints the empty-state message.
  */
 export declare function discoverShowcases(): ShowcaseInfo[];
 /** Find a single showcase by short name. */

package/lib/utils/discover-showcases.js

@@ -1,68 +1,46 @@
-// Dynamic discovery of installed showcase packages (@gjsify/example-*).
-// Scans the CLI's own package.json dependencies at runtime.
-import { readFileSync } from 'node:fs';
+// Static discovery of showcase packages from `showcases.json`.
+//
+// Earlier versions read showcases from the CLI's own `package.json#dependencies`
+// — every showcase had to be a direct CLI dependency. That made the CLI tarball
+// blow up with each new showcase and required a CLI rebuild to publish a new
+// one. Static manifest decouples both: the CLI reads the manifest at runtime,
+// `gjsify showcase <name>` delegates to `gjsify dlx <package>`.
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
-const EXAMPLE_PREFIX = '@gjsify/example-';
-/** Extract short name and category from package name. */
-function parseShowcaseName(packageName) {
-    // @gjsify/example-dom-three-postprocessing-pixel → category=dom, name=three-postprocessing-pixel
-    const suffix = packageName.slice(EXAMPLE_PREFIX.length);
-    const dashIdx = suffix.indexOf('-');
-    if (dashIdx === -1)
-        return null;
-    return {
-        category: suffix.slice(0, dashIdx),
-        name: suffix.slice(dashIdx + 1),
-    };
+function manifestPath() {
+    // `showcases.json` lives at the package root: ../../showcases.json from lib/utils/.
+    return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'showcases.json');
 }
 /**
- * Discover all installed showcase packages by scanning the CLI's own dependencies.
- * Returns showcases sorted by category then name.
+ * Read the curated showcase list from `showcases.json`. Returns showcases
+ * sorted by category then name. An empty list (or missing manifest) yields
+ * an empty array — `gjsify showcase` then prints the empty-state message.
  */
 export function discoverShowcases() {
-    const require = createRequire(import.meta.url);
-    const cliPkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
-    let cliPkg;
+    const path = manifestPath();
+    if (!existsSync(path))
+        return [];
+    let manifest;
     try {
-        cliPkg = JSON.parse(readFileSync(cliPkgPath, 'utf-8'));
+        manifest = JSON.parse(readFileSync(path, 'utf-8'));
     }
     catch {
         return [];
     }
-    const deps = cliPkg['dependencies'];
-    if (!deps)
+    if (!Array.isArray(manifest.showcases))
         return [];
-    const showcases = [];
-    for (const packageName of Object.keys(deps)) {
-        if (!packageName.startsWith(EXAMPLE_PREFIX))
-            continue;
-        const parsed = parseShowcaseName(packageName);
-        if (!parsed)
-            continue;
-        try {
-            const pkgJsonPath = require.resolve(`${packageName}/package.json`);
-            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-            const main = pkg['main'];
-            if (!main)
-                continue;
-            showcases.push({
-                name: parsed.name,
-                packageName,
-                category: parsed.category,
-                description: pkg['description'] ?? '',
-                bundlePath: join(dirname(pkgJsonPath), main),
-            });
-        }
-        catch {
-            // Package listed as dep but not resolvable — skip silently
-        }
-    }
+    const showcases = manifest.showcases.map((e) => ({
+        name: e.name,
+        packageName: e.package,
+        category: e.category,
+        description: e.description ?? '',
+        needsWebgl: Boolean(e.needsWebgl),
+    }));
     showcases.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
     return showcases;
 }
 /** Find a single showcase by short name. */
 export function findShowcase(name) {
-    return discoverShowcases().find(e => e.name === name);
+    return discoverShowcases().find((e) => e.name === name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,15 +23,11 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.3.5",
-    "@gjsify/esbuild-plugin-gjsify": "^0.3.5",
-    "@gjsify/example-dom-canvas2d-fireworks": "^0.3.5",
-    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.3.5",
-    "@gjsify/example-dom-three-geometry-teapot": "^0.3.5",
-    "@gjsify/example-dom-three-postprocessing-pixel": "^0.3.5",
-    "@gjsify/example-node-express-webserver": "^0.3.5",
-    "@gjsify/node-polyfills": "^0.3.5",
-    "@gjsify/web-polyfills": "^0.3.5",
+    "@gjsify/create-app": "^0.3.7",
+    "@gjsify/esbuild-plugin-gjsify": "^0.3.7",
+    "@gjsify/node-polyfills": "^0.3.7",
+    "@gjsify/resolve-npm": "^0.3.7",
+    "@gjsify/web-polyfills": "^0.3.7",
     "@yarnpkg/esbuild-plugin-pnp": "^3.0.0-rc.15",
     "cosmiconfig": "^9.0.1",
     "esbuild": "^0.28.0",

package/showcases.json

@@ -0,0 +1,40 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "showcases": [
+        {
+            "name": "canvas2d-fireworks",
+            "category": "dom",
+            "package": "@gjsify/example-dom-canvas2d-fireworks",
+            "description": "Colorful fireworks Canvas 2D example with Adwaita controls",
+            "needsWebgl": false
+        },
+        {
+            "name": "excalibur-jelly-jumper",
+            "category": "dom",
+            "package": "@gjsify/example-dom-excalibur-jelly-jumper",
+            "description": "Excalibur.js jelly-jumper game",
+            "needsWebgl": false
+        },
+        {
+            "name": "three-geometry-teapot",
+            "category": "dom",
+            "package": "@gjsify/example-dom-three-geometry-teapot",
+            "description": "Three.js Utah teapot",
+            "needsWebgl": true
+        },
+        {
+            "name": "three-postprocessing-pixel",
+            "category": "dom",
+            "package": "@gjsify/example-dom-three-postprocessing-pixel",
+            "description": "Three.js postprocessing pixel demo",
+            "needsWebgl": true
+        },
+        {
+            "name": "express-webserver",
+            "category": "node",
+            "package": "@gjsify/example-node-express-webserver",
+            "description": "Express web server on GJS via @gjsify/http",
+            "needsWebgl": false
+        }
+    ]
+}

package/src/actions/build.ts

@@ -7,121 +7,32 @@ import {
 	writeRegisterInjectFile,
 	detectAutoGlobals,
 } from "@gjsify/esbuild-plugin-gjsify/globals";
-import { dirname, extname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { getBundleDir, rewriteContents } from "@gjsify/esbuild-plugin-gjsify";
+import { getPnpPlugin } from "@gjsify/resolve-npm/pnp-relay";
+import { dirname, extname } from "node:path";
 import { chmod, readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
 
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
 
-/** Walk up from dir until .pnp.cjs is found; return its directory or null. */
-function findPnpRoot(dir: string): string | null {
-	let current = dir;
-	while (true) {
-		if (existsSync(join(current, ".pnp.cjs"))) return current;
-		const parent = dirname(current);
-		if (parent === current) return null;
-		current = parent;
-	}
-}
-
 /**
- * If the current project uses Yarn PnP, return the official
- * @yarnpkg/esbuild-plugin-pnp plugin so esbuild can resolve
- * modules from zip archives without manual extraction.
+ * Resolve the gjsify-flavoured PnP plugin. Anchors the relay on this file's
+ * URL so transitive `@gjsify/*` polyfills (reached via @gjsify/cli's deps on
+ * @gjsify/{node,web}-polyfills) are resolvable for external consumers without
+ * each one having to be a direct devDep.
  *
- * Custom onResolve: when the project's PnP context throws
- * UNDECLARED_DEPENDENCY, retry via a two-hop relay:
- *   1. @gjsify/cli context (direct dep of the project using gjsify build)
- *   2. @gjsify/node-polyfills context (direct dep of @gjsify/cli, has all
- *      node polyfills as direct deps including @gjsify/node-globals)
- *   3. @gjsify/web-polyfills context (direct dep of @gjsify/cli, has all
- *      web polyfills as direct deps including @gjsify/fetch, @gjsify/abort-controller)
- * For bare specifiers that the gjsify alias plugin maps (e.g. `abort-controller`),
- * fall through so that plugin can handle the transformation first.
+ * Wires the @gjsify/esbuild-plugin-gjsify rewriter (`__filename`/`__dirname`
+ * injection for CJS code in node_modules) into the pnp plugin's onLoad —
+ * esbuild stops at the first matching onLoad, so the rewriter MUST run from
+ * inside the pnp plugin's onLoad rather than as a separate registration.
  */
-async function getPnpPlugin(): Promise<Plugin | null> {
-	if (!findPnpRoot(process.cwd())) return null;
-	try {
-		const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
-
-		// gjsify's own file path — @gjsify/cli has node-polyfills + web-polyfills
-		// as direct deps, so we can resolve them as relay issuers from here.
-		const gjsifyIssuer = fileURLToPath(import.meta.url);
-
-		// Two-hop relay: node-polyfills and web-polyfills have all individual
-		// @gjsify/* packages as direct deps. Resolving from their package.json
-		// paths allows PnP to use them as issuers — sub-path imports
-		// (`@gjsify/foo/register/bar`) then resolve through the polyfill's
-		// dep graph. Resolve to package.json (always present, exports-agnostic)
-		// rather than main/module (the polyfills meta packages have no main).
-		const requireFromGjsify = createRequire(gjsifyIssuer);
-		const relayIssuers: string[] = [];
-		for (const pkg of ["@gjsify/node-polyfills", "@gjsify/web-polyfills"]) {
-			try {
-				relayIssuers.push(requireFromGjsify.resolve(`${pkg}/package.json`));
-			} catch {
-				// polyfills package not in dep tree — relay won't cover it
-			}
-		}
-
-		// pnpapi is a virtual module injected by Yarn PnP at runtime.
-		type PnpApi = {
-			resolveRequest: (req: string, issuer: string) => string | null;
-		};
-		let pnpApi: PnpApi | null = null;
-		try {
-			// pnpapi has no npm package — it is a virtual module injected by Yarn PnP
-			// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-			// @ts-expect-error
-			pnpApi = (await import("pnpapi")) as PnpApi;
-		} catch {
-			// Not in a PnP runtime (shouldn't happen since findPnpRoot passed)
-		}
-
-		return pnpPlugin({
-			onResolve: async (args, { resolvedPath, error, watchFiles }) => {
-				if (resolvedPath !== null) {
-					return { namespace: "pnp", path: resolvedPath, watchFiles };
-				}
-				if (
-					(error as { pnpCode?: string } | null)?.pnpCode ===
-					"UNDECLARED_DEPENDENCY"
-				) {
-					if (pnpApi !== null) {
-						// Try @gjsify/cli context first (covers @gjsify/* that are
-						// direct deps of cli's own deps — unlikely but fast check).
-						try {
-							const rp = pnpApi.resolveRequest(args.path, gjsifyIssuer);
-							if (rp !== null)
-								return { namespace: "pnp", path: rp, watchFiles };
-						} catch {}
-						// Two-hop relay: resolve from node-polyfills / web-polyfills context
-						// which have the individual @gjsify/* packages as direct deps.
-						for (const relayIssuer of relayIssuers) {
-							try {
-								const rp = pnpApi.resolveRequest(args.path, relayIssuer);
-								if (rp !== null)
-									return { namespace: "pnp", path: rp, watchFiles };
-							} catch {}
-						}
-					}
-					// Fall through — bare aliases (abort-controller, fetch/register/*)
-					// are handled by the gjsify alias plugin after this returns null,
-					// then the re-resolved @gjsify/* path goes through this hook again.
-					return null;
-				}
-				return {
-					external: true,
-					errors: error ? [{ text: error.message }] : [],
-					watchFiles,
-				};
-			},
-		});
-	} catch {
-		return null;
-	}
+async function buildPnpPlugin(): Promise<Plugin | null> {
+	return getPnpPlugin({
+		issuerUrl: import.meta.url,
+		transformContentsFactory: (build) => {
+			const bundleDir = getBundleDir(build);
+			return (args, contents) => rewriteContents(args, contents, bundleDir);
+		},
+	});
 }
 
 export class BuildAction {
@@ -150,7 +61,7 @@ export class BuildAction {
 		const multipleBuilds =
 			moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
 
-		const pnpPlugin = await getPnpPlugin();
+		const pnpPlugin = await buildPnpPlugin();
 		const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
 
 		const results: BuildResult[] = [];
@@ -362,7 +273,7 @@ export class BuildAction {
 
 		const { autoMode, extras } = this.parseGlobalsValue(globals);
 
-		const pnpPlugin = await getPnpPlugin();
+		const pnpPlugin = await buildPnpPlugin();
 		const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
 
 		// --- Auto mode (with optional extras): iterative multi-pass build ---

package/src/commands/index.ts

@@ -6,4 +6,5 @@ export * from './showcase.js';
 export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
-export * from './dlx.js';
+export * from './dlx.js';
+export * from './install.js';

package/src/commands/install.ts

@@ -0,0 +1,116 @@
+// `gjsify install [pkg...]` — thin npm wrapper with gjsify-aware post-checks.
+//
+// The actual install is delegated to `npm install` in the user's project root
+// (no `--prefix` rewrite, unlike `gjsify dlx`). After install completes we run
+// `runMinimalChecks()` so missing system deps (gjs, gtk4, libsoup, ...) surface
+// immediately, and report any installed `@gjsify/*` packages that ship native
+// prebuilds so users know they can use `gjsify run` to wire `LD_LIBRARY_PATH` /
+// `GI_TYPELIB_PATH` automatically.
+//
+// Modes:
+//   gjsify install                    → project install (npm install)
+//   gjsify install <pkg> [<pkg>...]   → add package(s) (npm install <pkg>...)
+
+import { spawn } from 'node:child_process';
+import type { Command } from '../types/index.js';
+import {
+    buildInstallCommand,
+    detectPackageManager,
+    runMinimalChecks,
+} from '../utils/check-system-deps.js';
+import { detectNativePackages } from '../utils/detect-native-packages.js';
+
+interface InstallOptions {
+    packages?: string[];
+    'save-dev'?: boolean;
+    'save-peer'?: boolean;
+    'save-optional'?: boolean;
+    verbose: boolean;
+}
+
+export const installCommand: Command<any, InstallOptions> = {
+    command: 'install [packages..]',
+    description:
+        'Install npm dependencies in the current project, then run gjsify-aware post-checks.',
+    builder: (yargs) =>
+        yargs
+            .positional('packages', {
+                description: 'Optional package specs. With none, runs a full project install.',
+                type: 'string',
+                array: true,
+            })
+            .option('save-dev', { type: 'boolean', alias: 'D' })
+            .option('save-peer', { type: 'boolean' })
+            .option('save-optional', { type: 'boolean', alias: 'O' })
+            .option('verbose', {
+                description: 'Verbose npm logging.',
+                type: 'boolean',
+                default: false,
+            }),
+    handler: async (args) => {
+        const npmArgs = ['install'];
+        if (args['save-dev']) npmArgs.push('--save-dev');
+        if (args['save-peer']) npmArgs.push('--save-peer');
+        if (args['save-optional']) npmArgs.push('--save-optional');
+        if (args.verbose) npmArgs.push('--loglevel', 'verbose');
+        if (args.packages && args.packages.length > 0) {
+            npmArgs.push(...args.packages);
+        }
+
+        await spawnNpm(npmArgs);
+
+        await runPostInstallChecks();
+    },
+};
+
+async function spawnNpm(npmArgs: string[]): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        const child = spawn('npm', npmArgs, { stdio: 'inherit' });
+        child.on('close', (code) => {
+            if (code === 0) resolve();
+            else reject(new Error(`npm install exited with code ${code}`));
+        });
+        child.on('error', (err) => {
+            const code = (err as NodeJS.ErrnoException).code;
+            const msg = code === 'ENOENT'
+                ? 'npm not found on PATH — install Node.js first.'
+                : `npm install failed: ${err.message}`;
+            reject(new Error(msg));
+        });
+    }).catch((err: Error) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}
+
+async function runPostInstallChecks(): Promise<void> {
+    console.log('\n--- gjsify post-install checks ---');
+
+    // 1. System deps that GJS apps typically need.
+    const results = runMinimalChecks();
+    const missing = results.filter((r) => !r.found && r.severity === 'required');
+    if (missing.length > 0) {
+        console.warn('Missing required system dependencies:\n');
+        for (const dep of missing) {
+            console.warn(`  ✗  ${dep.name}`);
+        }
+        const pm = detectPackageManager();
+        const cmd = buildInstallCommand(pm, missing);
+        if (cmd) console.warn(`\nInstall with:\n  ${cmd}`);
+    } else {
+        console.log('System dependencies OK.');
+    }
+
+    // 2. Surface @gjsify/* packages with native prebuilds — `gjsify run`
+    //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
+    const native = detectNativePackages(process.cwd());
+    if (native.length > 0) {
+        console.log(
+            `\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`,
+        );
+        for (const pkg of native) {
+            console.log(`  • ${pkg.name}`);
+        }
+        console.log('\nUse `gjsify run <bundle>` to launch with LD_LIBRARY_PATH/GI_TYPELIB_PATH set.');
+    }
+}

package/src/commands/showcase.ts

@@ -1,7 +1,13 @@
 import type { Command } from '../types/index.js';
 import { discoverShowcases, findShowcase } from '../utils/discover-showcases.js';
-import { runMinimalChecks, checkGwebgl, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
-import { runGjsBundle } from '../utils/run-gjs.js';
+import {
+    runMinimalChecks,
+    checkGwebgl,
+    detectPackageManager,
+    buildInstallCommand,
+} from '../utils/check-system-deps.js';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 interface ShowcaseOptions {
     name?: string;
@@ -11,9 +17,9 @@ interface ShowcaseOptions {
 
 export const showcaseCommand: Command<any, ShowcaseOptions> = {
     command: 'showcase [name]',
-    description: 'List or run built-in gjsify showcase applications.',
-    builder: (yargs) => {
-        return yargs
+    description: 'List or run curated gjsify showcase applications.',
+    builder: (yargs) =>
+        yargs
             .positional('name', {
                 description: 'Showcase name to run (omit to list all)',
                 type: 'string',
@@ -27,8 +33,7 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
                 description: 'List available showcases',
                 type: 'boolean',
                 default: false,
-            });
-    },
+            }),
     handler: async (args) => {
         // List mode: no name given, or --list flag
         if (!args.name || args.list) {
@@ -40,11 +45,10 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             }
 
             if (showcases.length === 0) {
-                console.log('No showcases found. Showcase packages may not be installed.');
+                console.log('No showcases found. The CLI ships a curated list in `showcases.json`; if it is missing the CLI install is incomplete.');
                 return;
             }
 
-            // Group by category
             const grouped = new Map<string, typeof showcases>();
             for (const sc of showcases) {
                 const list = grouped.get(sc.category) ?? [];
@@ -55,7 +59,7 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             console.log('Available gjsify showcases:\n');
             for (const [category, list] of grouped) {
                 console.log(`  ${category.toUpperCase()}:`);
-                const maxNameLen = Math.max(...list.map(e => e.name.length));
+                const maxNameLen = Math.max(...list.map((e) => e.name.length));
                 for (const sc of list) {
                     const pad = ' '.repeat(maxNameLen - sc.name.length + 2);
                     const desc = sc.description ? `${pad}${sc.description}` : '';
@@ -68,7 +72,6 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             return;
         }
 
-        // Run mode: find the showcase
         const showcase = findShowcase(args.name);
         if (!showcase) {
             console.error(`Unknown showcase: "${args.name}"`);
@@ -76,16 +79,14 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             process.exit(1);
         }
 
-        // System dependency check before running — only check what this showcase needs.
-        // All showcases need GJS; WebGL showcases additionally need gwebgl prebuilds.
+        // System dependency check before delegating — only what this showcase needs.
         const results = runMinimalChecks();
-        const needsWebgl = showcase.packageName.includes('webgl') || showcase.packageName.includes('three');
-        if (needsWebgl) {
+        if (showcase.needsWebgl) {
             results.push(checkGwebgl(process.cwd()));
         }
-        // Hard-fail only on missing REQUIRED deps (gjs, gwebgl is required if needsWebgl).
-        // For showcase, gwebgl is treated as required because the bundle won't run without it.
-        const missingHard = results.filter(r => !r.found && (r.severity === 'required' || r.id === 'gwebgl'));
+        const missingHard = results.filter(
+            (r) => !r.found && (r.severity === 'required' || r.id === 'gwebgl'),
+        );
         if (missingHard.length > 0) {
             console.error('Missing system dependencies:\n');
             for (const dep of missingHard) {
@@ -99,8 +100,26 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             process.exit(1);
         }
 
-        // Run the showcase via shared GJS runner
-        console.log(`Running showcase: ${showcase.name}\n`);
-        await runGjsBundle(showcase.bundlePath);
+        // Delegate to `gjsify dlx <package>` — same npm-cache, same atomic
+        // symlink-swap, same `gjsify.main` resolution. Re-spawning the CLI
+        // keeps the dlx logic in one place.
+        console.log(`Running showcase: ${showcase.name} (via gjsify dlx)\n`);
+        const cliBin = fileURLToPath(new URL('../index.js', import.meta.url));
+        const child = spawn(process.execPath, [cliBin, 'dlx', showcase.packageName], {
+            stdio: 'inherit',
+        });
+        await new Promise<void>((resolvePromise, reject) => {
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`gjsify dlx exited with code ${code}`));
+                } else {
+                    resolvePromise();
+                }
+            });
+            child.on('error', reject);
+        }).catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
     },
 };

package/src/index.ts

@@ -12,6 +12,7 @@ import {
     gresourceCommand as gresource,
     gettextCommand as gettext,
     dlxCommand as dlx,
+    installCommand as install,
 } from './commands/index.js'
 import { APP_NAME } from './constants.js'
 
@@ -19,6 +20,7 @@ void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
     .command(create.command, create.description, create.builder, create.handler)
+    .command(install.command, install.description, install.builder, install.handler)
     .command(build.command, build.description, build.builder, build.handler)
     .command(run.command, run.description, run.builder, run.handler)
     .command(dlx.command, dlx.description, dlx.builder, dlx.handler)

package/src/utils/check-system-deps.ts

@@ -159,8 +159,13 @@ const PACKAGE_DEPS: Record<string, string[]> = {
     '@gjsify/canvas2d':      ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/canvas2d-core': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/dom-elements':  ['gdk-pixbuf'],
-    // @gjsify/webgl, @gjsify/event-bridge only need gtk4/gdk which are
-    // already in the required set, so they don't need optional entries.
+    // @gjsify/webgl needs the gwebgl npm package (Vala prebuild) — handled
+    // as a special-case checkNpmPackage rather than checkPkgConfig in
+    // runOptionalChecks. Mapping it here so its presence in the project's
+    // dep tree triggers the check.
+    '@gjsify/webgl':         ['gwebgl'],
+    // @gjsify/event-bridge only needs gtk4/gdk which are already in the
+    // required set, so it doesn't need an optional entry.
 };
 
 /** Walk up from cwd looking for the nearest package.json. */
@@ -322,10 +327,16 @@ function runOptionalChecks(needed: Set<string> | null, cwd: string): DepCheck[]
         results.push(checkPkgConfig(dep.id, dep.name, dep.pkgName, 'optional', requiredBy));
     }
 
-    // gwebgl npm package — special case (not a pkg-config lib).
-    // Always reported (the npm package is bundled with the CLI), but marked
-    // optional because only @gjsify/webgl users need it.
-    results.push(checkGwebgl(cwd));
+    // gwebgl npm package — special case (not a pkg-config lib). Only checked
+    // when the project directly or transitively depends on @gjsify/webgl —
+    // since the CLI tarball no longer ships any showcase example packages,
+    // gwebgl is not part of the CLI's own dep tree, so reporting it for every
+    // project would always be `found: false`. `needed === null` means "check
+    // everything" (no project context).
+    const hasWebglDep = needed === null || needed.has('gwebgl');
+    if (hasWebglDep) {
+        results.push(checkGwebgl(cwd));
+    }
 
     return results;
 }

package/src/utils/discover-showcases.ts

@@ -1,9 +1,13 @@
-// Dynamic discovery of installed showcase packages (@gjsify/example-*).
-// Scans the CLI's own package.json dependencies at runtime.
+// Static discovery of showcase packages from `showcases.json`.
+//
+// Earlier versions read showcases from the CLI's own `package.json#dependencies`
+// — every showcase had to be a direct CLI dependency. That made the CLI tarball
+// blow up with each new showcase and required a CLI rebuild to publish a new
+// one. Static manifest decouples both: the CLI reads the manifest at runtime,
+// `gjsify showcase <name>` delegates to `gjsify dlx <package>`.
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
 export interface ShowcaseInfo {
@@ -13,68 +17,53 @@ export interface ShowcaseInfo {
     packageName: string;
     /** Category: "dom" or "node" */
     category: string;
-    /** Description from showcase's package.json */
+    /** Description for the list view */
     description: string;
-    /** Absolute path to the GJS bundle (resolved from "main" field) */
-    bundlePath: string;
+    /** Whether the showcase needs the gwebgl native prebuild. */
+    needsWebgl: boolean;
 }
 
-const EXAMPLE_PREFIX = '@gjsify/example-';
+interface ManifestEntry {
+    name: string;
+    package: string;
+    category: string;
+    description?: string;
+    needsWebgl?: boolean;
+}
 
-/** Extract short name and category from package name. */
-function parseShowcaseName(packageName: string): { name: string; category: string } | null {
-    // @gjsify/example-dom-three-postprocessing-pixel → category=dom, name=three-postprocessing-pixel
-    const suffix = packageName.slice(EXAMPLE_PREFIX.length);
-    const dashIdx = suffix.indexOf('-');
-    if (dashIdx === -1) return null;
-    return {
-        category: suffix.slice(0, dashIdx),
-        name: suffix.slice(dashIdx + 1),
-    };
+interface Manifest {
+    showcases: ManifestEntry[];
+}
+
+function manifestPath(): string {
+    // `showcases.json` lives at the package root: ../../showcases.json from lib/utils/.
+    return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'showcases.json');
 }
 
 /**
- * Discover all installed showcase packages by scanning the CLI's own dependencies.
- * Returns showcases sorted by category then name.
+ * Read the curated showcase list from `showcases.json`. Returns showcases
+ * sorted by category then name. An empty list (or missing manifest) yields
+ * an empty array — `gjsify showcase` then prints the empty-state message.
  */
 export function discoverShowcases(): ShowcaseInfo[] {
-    const require = createRequire(import.meta.url);
-    const cliPkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
-    let cliPkg: Record<string, unknown>;
+    const path = manifestPath();
+    if (!existsSync(path)) return [];
+
+    let manifest: Manifest;
     try {
-        cliPkg = JSON.parse(readFileSync(cliPkgPath, 'utf-8')) as Record<string, unknown>;
+        manifest = JSON.parse(readFileSync(path, 'utf-8')) as Manifest;
     } catch {
         return [];
     }
+    if (!Array.isArray(manifest.showcases)) return [];
 
-    const deps = cliPkg['dependencies'] as Record<string, string> | undefined;
-    if (!deps) return [];
-
-    const showcases: ShowcaseInfo[] = [];
-
-    for (const packageName of Object.keys(deps)) {
-        if (!packageName.startsWith(EXAMPLE_PREFIX)) continue;
-
-        const parsed = parseShowcaseName(packageName);
-        if (!parsed) continue;
-
-        try {
-            const pkgJsonPath = require.resolve(`${packageName}/package.json`);
-            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as Record<string, unknown>;
-            const main = pkg['main'] as string | undefined;
-            if (!main) continue;
-
-            showcases.push({
-                name: parsed.name,
-                packageName,
-                category: parsed.category,
-                description: (pkg['description'] as string) ?? '',
-                bundlePath: join(dirname(pkgJsonPath), main),
-            });
-        } catch {
-            // Package listed as dep but not resolvable — skip silently
-        }
-    }
+    const showcases: ShowcaseInfo[] = manifest.showcases.map((e) => ({
+        name: e.name,
+        packageName: e.package,
+        category: e.category,
+        description: e.description ?? '',
+        needsWebgl: Boolean(e.needsWebgl),
+    }));
 
     showcases.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
     return showcases;
@@ -82,5 +71,5 @@ export function discoverShowcases(): ShowcaseInfo[] {
 
 /** Find a single showcase by short name. */
 export function findShowcase(name: string): ShowcaseInfo | undefined {
-    return discoverShowcases().find(e => e.name === name);
+    return discoverShowcases().find((e) => e.name === name);
 }