@featherk/icons 0.13.8 → 0.14.0

package/docs/fontawesome/FontAwesome.md

@@ -0,0 +1,251 @@
+# Font Awesome Build Integration
+
+Font Awesome support is opt-in. To use Font Awesome icons, Dev configures this build workflow to generate Kendo-compatible descriptors from the npm packages named by each manifest's `package` and exact `version` fields. UX/Design owns choosing the desired icon variants and recording them in the manifest; start with [Choose Font Awesome Icons and Create a Manifest](CreateFontAwesomeManifest.md). Consumers using only `getCustomIcon()` do not need this integration. `@featherk/icons` contains no Font Awesome artwork, Free or paid, and does not supply a license or authentication token.
+
+Once UX/Design has supplied the approved manifest, Dev owns source installation, Vite configuration, validation, and application integration. For licensed sources, see [Pro licensing and setup](LICENSING.md), including optional local profiles, secret handling, GitHub Actions/TeamCity, and consuming applications.
+
+## Quick Start
+
+1. UX/Design selects and approves each exact icon variant and records it in the [manifest](CreateFontAwesomeManifest.md); the license owner confirms Pro entitlement and approved release coverage.
+2. Dev installs `@featherk/icons` with the Font Awesome Vite entry point and ensures compatible Vite 7.x is available using [Install the Vite Integration](#install-the-vite-integration).
+3. Dev confirms access and availability for each manifest `package` and exact `version`, configures authorized registry access when required, then installs those matching pinned npm packages using [Install Source Packages](#install-source-packages). For Pro, follow [Pro token setup](LICENSING.md#dev-setup-quick-start) before installation.
+4. Dev configures the Vite plugin to use the approved manifest and validates the installed selections in [Vite Setup](#vite-setup).
+5. Dev renders the selected descriptors through the virtual module using the [rendering example](#render-the-selected-key).
+6. Dev preserves emitted license notices in application distribution as described in [Preserve license notices](#preserve-license-notices).
+
+This Free example uses an illustrative `fa-solid-v7` installed alias. Resolve its actual package, availability, version, and entitlement before use. Install a FeatherK release/build containing these entry points; a prior published release does not gain them automatically. For CLI generation, including declaration preparation before an early type check, see [CLI and non-Vite setup](FontAwesomeCLI.md).
+
+```json
+{
+  "icons": [
+    {
+      "key": "account",
+      "name": "user",
+      "version": "7.0.0",
+      "family": "classic",
+      "style": "solid",
+      "package": "fa-solid-v7"
+    }
+  ]
+}
+```
+
+### Pro Demo Example
+
+The repository's Pro demo selects Classic Light `house` from Font Awesome Pro 7 and exposes it with the manifest key `pro-house-light`. Use this selection only when the application has the required Font Awesome Pro access and license coverage:
+
+```json
+{
+  "icons": [
+    {
+      "key": "pro-house-light",
+      "name": "house",
+      "version": "7.0.0",
+      "family": "classic",
+      "style": "light",
+      "package": "@fortawesome/pro-light-svg-icons"
+    }
+  ]
+}
+```
+
+This follows the demo's Vite virtual-module flow. The Pro page filters generated provenance for `pro-` keys and passes the choices to its shared renderer; an application can also render this selected icon directly:
+
+```vue
+<template>
+  <SvgIcon :icon="houseIcon" />
+</template>
+
+<script setup lang="ts">
+import { SvgIcon } from "@progress/kendo-vue-common";
+import { getFaIcon } from "virtual:featherk/fontawesome";
+
+const houseIcon = getFaIcon("pro-house-light");
+</script>
+```
+
+## Install the Vite Integration
+
+The Dev integration requires `@featherk/icons` to export `@featherk/icons/fontawesome/vite`. Its Vite peer dependency is `^7.0.0`, which supports Vite 7.x (not a later major). Install them as development dependencies if they are not already available in the application:
+
+```sh
+npm install --save-dev @featherk/icons vite@^7.0.0
+```
+
+## Install Source Packages
+
+Dev installs the npm package or alias named by each UX-approved manifest `package` field, pinned to that entry's exact `version`. The Free example uses the `fa-solid-v7` alias shown in the manifest; the Pro example installs `@fortawesome/pro-light-svg-icons@7.0.0` as recorded in its manifest entry and requires authorized Font Awesome package access before installation.
+
+```sh
+# Free alias used by the example manifest.
+npm install --save-dev --save-exact fa-solid-v7@npm:@fortawesome/free-solid-svg-icons@7.0.0
+
+# Pro package used by the example manifest.
+npm install --save-dev --save-exact @fortawesome/pro-light-svg-icons@7.0.0
+```
+
+The Free command uses an alias to match the example manifest.
+
+Note: Aliases (i.e Like `fa-solid-v7` in the example above) let one project install multiple versions of the same npm package under distinct dependency names. See [alias details](#about-aliases-and-why-use-them).
+
+Never put a Pro token in the command or commit it. See [Pro licensing and setup](LICENSING.md) for secure registry configuration.
+
+## Vite Setup
+
+The following setup is Dev-owned and assumes the UX-approved manifest and required license approvals are in place.
+
+```ts
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { featherkFontAwesome } from "@featherk/icons/fontawesome/vite";
+import type { FontAwesomeSelection } from "@featherk/icons/fontawesome";
+import manifest from "./fontawesome.icons.json";
+
+// Step 1: Use the UX-approved manifest and verify required entitlement.
+// Step 2: Ensure @featherk/icons and Vite 7 are available.
+// Step 3: Install the npm packages matching each manifest package and version before Vite starts.
+export default defineConfig({
+  // Step 4: Use the selections from the manifest approved and installed above.
+  plugins: [
+    vue(),
+    featherkFontAwesome({
+      icons: manifest.icons as FontAwesomeSelection[],
+    }),
+  ],
+});
+```
+
+Enable JSON imports in the consumer's TypeScript configuration if necessary. The assertion above supplies TypeScript's selection type; the generator still validates the manifest's supported fields and resolved identities at runtime.
+
+### Render the Selected Key
+
+```vue
+<template>
+  <!-- Step 5: Render the generated descriptor directly through Kendo. -->
+  <SvgIcon :icon="accountIcon" />
+</template>
+
+<script setup lang="ts">
+import { SvgIcon } from "@progress/kendo-vue-common";
+import { getFaIcon } from "virtual:featherk/fontawesome";
+
+const accountIcon = getFaIcon("account");
+</script>
+```
+
+The plugin requires Vite 7. It writes `src/featherk-fontawesome.d.ts` on startup by default; include that file in TypeScript and ignore it in version control. `virtualTypesFile` selects another project-local `.d.ts` file or disables writing with `false`. Startup is too late for a type checker invoked before Vite, so retain the explicit CLI preparation step in that build order.
+
+### Preserve License Notices
+
+The plugin emits `featherk-fontawesome.licenses.txt` into Vite build output (Step 6); Dev must preserve this file in application distribution. It registers source dependencies and refreshes on observed changes, failing rather than serving stale successful artwork after a bad refresh. Restart Vite after installing/upgrading packages: watcher exclusions, including `node_modules`, may prevent live events.
+
+## Inspecting an Icon Descriptor
+
+`getFaIcon(key)` returns a runtime `FontAwesomeIcon` object with `{ name, content, viewBox }`, structurally compatible with Kendo's `SVGIcon`. `name` is the selected manifest key, `content` is the inner SVG path markup without an outer `<svg>`, and `viewBox` preserves the source geometry. The property is case-sensitive: `viewBox`, not `viewbox`.
+
+The following examples assume `rocket` is included in the project's enabled selections. Replace it with your selected key, such as `account` in the Quick Start manifest.
+
+### Application Code
+
+Use the supported virtual-module import in a Vite application:
+
+```ts
+import { getFaIcon } from "virtual:featherk/fontawesome";
+
+console.log(getFaIcon("rocket"));
+```
+
+An illustrative result, with path data shortened, is:
+
+```js
+{
+  name: "rocket",
+  content: '<path d="..." fill="currentColor"/>',
+  viewBox: "0 0 512 512"
+}
+```
+
+The real `content` contains the complete path data; the abbreviated example is not renderable SVG. Appearance changes applied through CSS in the demo do not rewrite this descriptor's `currentColor` paths.
+
+### Browser DevTools
+
+While viewing the application on a running Vite dev server, inspect a descriptor from the browser console:
+
+```js
+const { getFaIcon } =
+  await import("/@id/__x00__virtual:featherk/fontawesome");
+
+console.log(getFaIcon("rocket"));
+```
+
+This URL is Vite's internal representation of the virtual module, not a public FeatherK API. The example assumes a root (`/`) base path; adjust for a different dev-server base. Do not use it in application imports or expect it to work in production/preview builds. Prefer the supported application import or a breakpoint on the demo's `selectedIcon` computed value for normal debugging.
+
+Generated `.d.ts` files contain declarations and the selected-key union, not SVG objects or artwork. With Vite, descriptor values live in the transformed virtual module and application bundle. Pro descriptors exist only when the licensed profile is enabled and the selected sources resolve successfully; no package token is needed to inspect already generated values.
+
+## Generated Output and Source Checks
+
+The Vite plugin writes `src/featherk-fontawesome.d.ts` on startup by default. Keep this file included in TypeScript, but exclude it from source linting and formatting. Generation overwrites the file, so running a formatter after every build is not a durable fix; output formatting is not guaranteed to match each consumer's Prettier rules.
+
+Add the exact generated declaration path to ESLint's global ignores, `.prettierignore`, and `.gitignore`. These are independent exclusions, not substitutes for one another. Do not ignore all `.d.ts` files or exclude the generated declaration from TypeScript.
+
+For a Vite consumer using the default output, merge this entry into the existing ESLint flat configuration. The entry should contain only `ignores`, so it applies globally:
+
+```js
+export default [
+  // Step 1: Add this entry alongside the project's existing configuration.
+  { ignores: ["src/featherk-fontawesome.d.ts"] },
+];
+```
+
+Add this pattern separately to both `.prettierignore` and `.gitignore`:
+
+```text
+# Step 2: Ignore generated output, not handwritten declarations.
+src/featherk-fontawesome.d.ts
+```
+
+Keep this file covered by the project's TypeScript `include` patterns, such as `src/**/*`. If `virtualTypesFile` is customized, use that configured path in all three ignore mechanisms and ensure TypeScript includes it.
+
+In the FeatherK monorepo, the exact root-relative pattern is `demos/src/featherk-fontawesome.d.ts`. ESLint's global ignores, `.prettierignore`, and `.gitignore` exclude that file; the demo TypeScript configuration still includes it. The generator, plugin, and handwritten declarations remain linted. If a type checker runs before Vite starts, see [CLI and non-Vite setup](FontAwesomeCLI.md) for declaration preparation. The library does not modify consumer lint configuration or inject ESLint-disable directives.
+
+## Supported Sources and Licensing
+
+### Verified Free Consumer
+
+The private demo workspace pins `@fortawesome/free-solid-svg-icons@7.0.0` and selects Free Classic Solid `rocket`, `feather`, `heart`, `star`, and `user` through its JSON manifest. It also selects `rocket-v5` from `5.15.4` and `rocket-v6` from `6.7.2` using pinned npm aliases. After building `@featherk/icons`, run `npm run verify:fontawesome --workspace=@featherk/demos` from the repository root.
+
+This generates the ignored demo-local virtual declaration, builds an isolated Vite consumer in memory, and checks every selected export's original path, viewBox, exact version, the generated key union, selected-only lookup, and emitted Free license notices. Font Awesome artwork is not copied into tracked source or published FeatherK artifacts. This validates these specific Free packages/exports, not all releases, Pro entitlement, or v4 artwork.
+
+The local `/icons` page links to the owned gallery at `/icons/custom`, `FontAwesomeFreeDemo` at `/icons/fontawesome/free`, and `FontAwesomeProDemo` at `/icons/fontawesome/pro`. The old `/icons/fontawesome` URL redirects to Free. Free has ten Solid/Regular selections, top-level appearance controls, and version/source details. Pro is an opt-in licensed profile; without it, the Pro page shows an unavailable state. Both reuse the same demo renderer and remain separate from custom icons.
+
+### Mixed Versions and Free Styles
+
+#### About Aliases and Why Use Them
+
+Font Awesome v5, v6, and v7 are different releases of the same npm package, `@fortawesome/free-solid-svg-icons`. A project can expose only one version under that package name at the top level. npm aliases give additional releases distinct local dependency names, allowing this integration to resolve each one through the manifest's `package` field. The manifest's `version` records the upstream release; the alias does not change it. If an application uses only one release, an alias is not needed.
+
+The demo uses the canonical package name for v7 and aliases for v5 and v6:
+
+```json
+{
+  "@fortawesome/free-solid-svg-icons": "7.0.0",
+  "fa-solid-v5": "npm:@fortawesome/free-solid-svg-icons@5.15.4",
+  "fa-solid-v6": "npm:@fortawesome/free-solid-svg-icons@6.7.2"
+}
+```
+
+For aliased selections, set manifest `package` to the local dependency name, `version` to its exact upstream release, and `key` to a unique application identifier such as `rocket-v5`. Identical canonical names from different releases can then coexist without resolving to the wrong installed version.
+
+The generated `FontAwesomeKey` union now contains `"rocket" | "feather" | "heart" | "star" | "user" | "rocket-v5" | "rocket-v6"`. Descriptor geometry stays in generated browser output, not in the declaration file; adding selections expands the compile-time key union without adding SVG artwork to the types.
+
+None of the selected icons has a Free Classic Light variant: Classic Light is a Pro style. Some icons have Free Regular variants, but Regular is not Light, and not every Solid icon has a Free Regular counterpart. A different style requires its matching installed source package and an available definition.
+
+Version 4 remains pending by design. Its legacy font assets are not supported individual SVG definitions for this generator; exact v4 rendering needs an explicitly designed font-to-SVG conversion or a separate web-font example. The demo does not substitute newer artwork and label it as v4.
+
+The npm package named by each manifest `package` field must expose `package.json`, individual CommonJS icon exports, and non-empty `LICENSE.txt`. Its exact installed `version`, canonical icon `name`, and family/style prefix must match the manifest. An optional `exportName` identifies the individual export when default name derivation is unsuitable. Only structured path definitions are supported; raw SVG parsing, ESM-only packages, automatic downloads, v4 artwork conversion, and Kits are not implemented.
+
+Single-color paths use `currentColor`; supported duotone definitions retain their two layers with primary/secondary CSS variables. Unsupported layer structures and unsafe path content are rejected. No source module or Node acquisition code belongs in browser output.
+
+License/registry authentication is the consumer's responsibility. Use secret environment variables in trusted GitHub Actions or TeamCity jobs, never browser-prefixed variables or committed tokens. Locked dependencies, access controls, and approved Creator coverage are required where applicable. Synthetic tests do not establish entitlement or real-package compatibility.
+
+See the [design and licensing notes](https://github.com/NantHealth/featherk/blob/integration/docs/design/fa-integration.md) and the [Font Awesome license](https://fontawesome.com/license) before licensed deployment. Pro+ collections and exact historical versions require separate availability/entitlement verification.

package/docs/fontawesome/FontAwesomeCLI.md

@@ -0,0 +1,64 @@
+# Font Awesome CLI and Non-Vite Setup
+
+This Dev-owned supplement assumes UX/Design has supplied the approved selections in a manifest. For icon choice, approval, naming, and manifest authoring, start with [Choose Font Awesome Icons and Create a Manifest](CreateFontAwesomeManifest.md). For the default Vite integration, see [Font Awesome Build Integration](FontAwesome.md).
+
+## Quick Start
+
+1. Receive the UX-approved manifest and required license approvals.
+2. Dev installs `@featherk/icons` at a release containing the CLI or Node API; for example, `npm install --save-dev @featherk/icons`.
+3. Dev installs the npm package or alias named by each manifest `package` field at its exact `version` using authorized package access. For Pro, follow [Pro token setup](LICENSING.md#dev-setup-quick-start) before installation; package examples are in [Install Source Packages](FontAwesome.md#install-source-packages).
+4. Dev generates virtual-module declarations or a regular ESM module from the manifest.
+5. Dev imports the generated module where needed, type-checks declarations, and preserves emitted license notices.
+
+The CLI validates installed Font Awesome source packages; it does not install them or authenticate with a registry. A prior FeatherK release does not gain the CLI or Node API entry points automatically.
+
+### Generate declarations before a Vite type check
+
+The Vite plugin writes `src/featherk-fontawesome.d.ts` on startup by default. If `vue-tsc` or `tsc` runs before Vite starts, prepare that file first:
+
+```sh
+# Step 4: Generate the virtual-module declarations before standalone type checking.
+npm exec -- featherk-fontawesome --manifest fontawesome.icons.json --virtual-types src/featherk-fontawesome.d.ts
+```
+
+Configure `featherkFontAwesome` with the same selections. The CLI and plugin must use the same manifest; do not maintain conflicting selection lists. `virtualTypesFile` can select another project-local `.d.ts` path or disable plugin writing with `false`.
+
+### Generate a module for a non-Vite application
+
+No migration to Vite is required. Generate a regular ESM module and adjacent declarations/notices:
+
+```sh
+# Step 4: Generate application-local ESM output from the selected manifest.
+npm exec -- featherk-fontawesome --manifest fontawesome.icons.json --out src/generated/fontawesome/icons.mjs
+```
+
+Import the generated module before running the existing application build:
+
+```js
+// Step 5: Use the manifest key selected for this application.
+import { getFaIcon } from "./generated/fontawesome/icons.mjs";
+
+const accountIcon = getFaIcon("account");
+```
+
+Run generation again when selections change, including before local development. A generation failure exits nonzero and must stop CI; do not continue with prior output. Preserve the emitted `icons.mjs.licenses.txt` notice in application distribution. Non-Vite bundlers do not automatically copy that sidecar.
+
+## Node API and CLI Options
+
+`generateFaIcons` from `@featherk/icons/fontawesome/build` accepts `icons`, optional `root`, `sourceRoot`, `outFile`, and `virtualTypesFile`. It returns ESM code, file-module declarations, ambient virtual-module declarations, notices, provenance, and source dependency paths. Without output options, it writes nothing.
+
+The CLI accepts `--manifest`, `--root`, `--source-root`, `--out`, `--virtual-types`, and `--help`. The manifest must contain an `icons` array; specify at least one output. Paths are relative to `--root` or the current directory. File output uses `.js`/`.mjs` with `.d.ts`/`.d.mts` declarations; ambient output uses `.d.ts` and must not overwrite the file-module declaration.
+
+Output must remain inside the consumer project, outside `node_modules` and the `@featherk/icons` package. The independent runtime `createFontAwesomeService` is available from `@featherk/icons/fontawesome`; Node tooling is never imported through the custom-icon root service.
+
+The API and Vite plugin accept `sourceRoot` to resolve installed packages from a separate source project without moving the output boundary. The CLI equivalent is `--source-root`. Relative source paths resolve from `root`; authentication still happens during npm installation, never in the generator or browser.
+
+## Generated Output and Source Checks
+
+Generated declarations belong in TypeScript so selected keys receive type checking, but should be excluded from source linting, formatting, and version control. Add the exact output path separately to ESLint's global ignores, `.prettierignore`, and `.gitignore`; these are independent settings. Do not ignore all `.d.ts` files or exclude generated declarations from TypeScript.
+
+For a Vite consumer using the default output, use `src/featherk-fontawesome.d.ts` in each ignore mechanism. In this monorepo, the path is `demos/src/featherk-fontawesome.d.ts`.
+
+For non-Vite consumers, prefer a directory dedicated exclusively to generated Font Awesome output, such as `src/generated/fontawesome/`. Ignore that directory in ESLint, Prettier, and Git. If output is kept in a shared directory, ignore the exact generated module, declaration, and notice sidecar paths rather than handwritten files nearby. Keep generated declarations available to TypeScript and preserve license notices in application distribution.
+
+Vite builds emit `featherk-fontawesome.licenses.txt` into the build output. Preserve that notice when distributing the application. Generation overwrites output, so do not rely on formatting generated files after every build; generated output formatting is not guaranteed to match consumer formatter rules.

package/docs/fontawesome/LICENSING.md

@@ -0,0 +1,140 @@
+# Font Awesome Pro Licensing and Setup
+
+`@featherk/icons` supplies tooling, not Pro assets, entitlement, or credentials. Paid source packages belong to authorized application/development environments, never FeatherK's owned icon registry, public package, or tracked artwork.
+
+## Requirements
+
+The organization's license owner must confirm download/authenticated package access, the approved releases, Creator seats covering the people working with Pro assets, build automation, application embedding/deployment, and any restrictions after subscription expiry. An older perpetual license does not automatically cover new releases; limited plans can have different rights. A shared token or enterprise repository access does not grant additional seats.
+
+The [published Pro license](https://fontawesome.com/license) permits covered Creators to embed icons in projects and restricts standalone distribution to non-Creators. End users viewing an embedded application are different from developers making new projects. Confirm your actual agreement with the license owner or Font Awesome; this guide is not a legal determination.
+
+## Dev Setup Quick Start
+
+The steps below are for Dev after UX/Design has selected the desired Pro variants and recorded them in an approved manifest. See [Choose Font Awesome Icons and Create a Manifest](CreateFontAwesomeManifest.md) for that UX-owned work.
+
+1. Confirm entitlement, Creator coverage, and approved releases with the license owner.
+2. Dev obtains an authorized **Pro Package Token** from the Font Awesome account and supplies it privately as `FONTAWESOME_PACKAGE_TOKEN`.
+3. Dev installs the npm packages named by the manifest's `package` fields at their exact `version`s into the dedicated private project through its environment-referenced npm configuration.
+4. Dev enables the Pro profile and prepares declarations before type checking/building the application.
+5. Dev preserves upstream notices and verifies publication/deployment boundaries before distribution.
+
+A package token is not a Kit code, account password, or Kendo license key. Never paste it into chat, screenshots, source files, command arguments, or logs. Follow the organization's approved token issuance/rotation process; do not share account passwords.
+
+## This FeatherK Repository
+
+Normal root installation/build, Free demos, tests, and public package publishing require no Pro token. `demos/pro` is a separate private source project, not a root workspace. It requests exact `@fortawesome/pro-regular-svg-icons@7.0.0` and `@fortawesome/pro-light-svg-icons@7.0.0` packages; no paid dependency is added to the normal demo workspace or public icons package.
+
+The committed source-project npm configuration contains only a placeholder:
+
+```ini
+@fortawesome:registry=https://npm.fontawesome.com/
+//npm.fontawesome.com/:_authToken=${FONTAWESOME_PACKAGE_TOKEN}
+```
+
+Do not replace the placeholder with a token or move this private registry configuration into the repository root. This keeps normal Free installation independent of Pro authentication.
+
+From the repository root, after confirming Steps 1-2:
+
+```sh
+# Step 3: Authenticated installation runs only inside demos/pro.
+npm run setup:fontawesome:pro --workspace=@featherk/demos
+# Step 4: Start the explicitly licensed local profile.
+npm run dev:pro --workspace=@featherk/demos
+# Step 5: Build the application and preserve emitted notices.
+npm run build:pro --workspace=@featherk/demos
+```
+
+The installer checks for the token without printing it. Initial installation creates an isolated lockfile; later runs use `npm ci` when it exists. Review and commit dependency/integrity metadata for reproducible CI, ensuring it contains no credentials. Source `node_modules` and application artifacts remain ignored. No paid installation has been performed as part of implementing this setup.
+
+The UX-approved Pro manifest requests Regular Rocket, Light Feather, and Light Heart. These pins are requested examples, not verified downloads. If entitlement, releases, or exports are unavailable, Dev must stop installation/generation and return to UX/Design for approval before changing the manifest or dependencies; never substitute silently.
+
+The profile wrappers enable the non-secret `FEATHERK_FONTAWESOME_PRO=1` build flag and remove the package token from child build environments. They invoke the demo's own commands, not the root Turborepo cached build. Do not put paid outputs into shared/untrusted caches.
+
+`sourceRoot: "pro"` resolves installed licensed packages while output guards remain relative to the demo project. Node resolution also finds already installed Free packages in parent workspace directories. The next normal preparation restores the Free-only generated key union.
+
+Routes are `/icons/fontawesome/free` and `/icons/fontawesome/pro`; `/icons/fontawesome` redirects to Free. The Pro page shows an unavailable state without a licensed profile, never fabricated artwork. Enabling the profile with missing/invalid sources fails the build rather than hiding an error.
+
+### Private Local Token Input
+
+Run one option in your own terminal. Secret input stays in the terminal, not the assistant.
+
+Git Bash:
+
+```bash
+# Step 2: Type the token at the hidden prompt.
+read -r -s -p "Font Awesome package token: " FONTAWESOME_PACKAGE_TOKEN
+export FONTAWESOME_PACKAGE_TOKEN
+# Step 3: Install, then remove the token from the shell environment.
+npm run setup:fontawesome:pro --workspace=@featherk/demos
+setup_status=$?
+unset FONTAWESOME_PACKAGE_TOKEN
+# Step 4: Start only after successful installation.
+if [[ $setup_status -eq 0 ]]; then
+  npm run dev:pro --workspace=@featherk/demos
+fi
+```
+
+PowerShell:
+
+```powershell
+# Step 2: Type the token at the secure prompt.
+$env:FONTAWESOME_PACKAGE_TOKEN = [System.Net.NetworkCredential]::new(
+  "", (Read-Host "Font Awesome package token" -AsSecureString)
+).Password
+# Step 3: Keep credentials present only for installation.
+try {
+  npm run setup:fontawesome:pro --workspace=@featherk/demos
+  if ($LASTEXITCODE -ne 0) { throw "Licensed source installation failed." }
+} finally {
+  Remove-Item Env:FONTAWESOME_PACKAGE_TOKEN -ErrorAction SilentlyContinue
+}
+# Step 4: Start only after successful installation.
+npm run dev:pro --workspace=@featherk/demos
+```
+
+Do not continue after an install error. `401`/`403` can indicate invalid/revoked credentials or insufficient entitlement. Inspect status codes without printing token/config contents. Missing releases/exports need a source/approval review, not an unpinned upgrade.
+
+## Consuming Applications
+
+Consumers need their own covered access or an enterprise agreement that actually covers them. The public FeatherK package grants no Pro rights.
+
+Two supported Vite layouts are:
+
+- **Application development dependencies:** configure environment-referenced authentication in the app and install exact Pro packages. Normal dependency installation then requires licensed access.
+- **Isolated optional source project:** install sources separately and pass `sourceRoot` to the Vite plugin. Keep application output within the consumer project.
+
+For non-Vite applications or declaration generation before a standalone type check, follow [CLI and non-Vite setup](FontAwesomeCLI.md). Registry authentication still belongs to the authorized package installation environment; the generator and browser never receive the token.
+
+For Vite, use `featherkFontAwesome({ icons, sourceRoot: "pro" })`. The profile scripts above are repository demo helpers, not scripts automatically installed into consumer applications.
+
+For applications using both Free and Pro, UX/Design approves both selection sets; Dev enables them together in the build manifest. Optional profiles must not silently include paid inputs in public/uncredentialed builds. Follow the [generated-output ignore guidance](FontAwesome.md#generated-output-and-source-checks): exclude generated files from ESLint/Prettier/Git while retaining TypeScript checks.
+
+## CI and Deployment
+
+FeatherK and `feather-k-<demo-name>` repositories use GitHub Actions. TeamCity applies only to enterprise apps using that platform.
+
+Use a dedicated trusted Actions job with a protected Environment and approval/branch rules. Supply the token only to source installation, not public publishing or client compilation. After checkout and Node/root dependency setup:
+
+```yaml
+- name: Install licensed demo sources
+  env:
+    FONTAWESOME_PACKAGE_TOKEN: ${{ secrets.FONTAWESOME_PACKAGE_TOKEN }}
+    NPM_CONFIG_CACHE: ${{ runner.temp }}/fontawesome-pro-cache
+  run: npm run setup:fontawesome:pro --workspace=@featherk/demos
+- name: Build licensed demo application
+  run: npm run build:pro --workspace=@featherk/demos
+```
+
+Configure the protected Environment separately; this fragment grants no license rights. Restrict paid caches/archives/artifacts, and never execute untrusted PR code with the token, including via `pull_request_target`. Normal public FeatherK publishing must not receive Pro credentials or use the licensed profile.
+
+In TeamCity, limit `env.FONTAWESOME_PACKAGE_TOKEN` Password parameters to trusted acquisition steps/agents. Install locked sources, remove credentials from subsequent steps, then run the app's Vite or explicit generator build. Tokens do not expand Creator seats.
+
+Enterprise Pages must enforce authentication on deployed URLs/static assets; repository privacy alone is insufficient. Rendered SVGs remain extractable by authorized viewers. Preserve notices and distribute an application, not a standalone paid-icon catalog. Actual license terms govern permitted deployment.
+
+## Validation Boundary
+
+Public `@featherk/icons` artifacts contain tooling and owned icons only: no paid dependencies/artwork, source caches, credentials, or generated paid-icon collections. Private distribution alone does not establish entitlement.
+
+Isolated-source resolution uses synthetic tests. Free generation and Pro-unavailable UI can be checked without secrets. Real paid exports, license notices, and enabled Pro rendering remain unverified until an authorized installation succeeds. Pro+ collections requiring Kits remain outside this no-Kit implementation.
+
+References: [package authentication](https://docs.fontawesome.com/web/setup/packages), [Pro license](https://fontawesome.com/license), and [Font Awesome account](https://fontawesome.com/account).

package/package.json

@@ -1,15 +1,51 @@
 {
   "name": "@featherk/icons",
-  "version": "0.13.8",
+  "version": "0.14.0",
   "main": "dist/featherk-icons.umd.js",
   "module": "dist/featherk-icons.es.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/featherk-icons.es.js",
+      "require": "./dist/featherk-icons.umd.js"
+    },
+    "./fontawesome": {
+      "types": "./dist/fontawesome/index.d.ts",
+      "import": "./dist/fontawesome/index.mjs",
+      "require": "./dist/fontawesome/index.cjs"
+    },
+    "./fontawesome/build": {
+      "types": "./dist/fontawesome/build.d.ts",
+      "import": "./dist/fontawesome/build.mjs",
+      "require": "./dist/fontawesome/build.cjs"
+    },
+    "./fontawesome/vite": {
+      "types": "./dist/fontawesome/vite.d.ts",
+      "import": "./dist/fontawesome/vite.mjs",
+      "require": "./dist/fontawesome/vite.cjs"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "scripts/fontawesome.mjs"
   ],
+  "bin": {
+    "featherk-fontawesome": "scripts/fontawesome.mjs"
+  },
+  "peerDependencies": {
+    "vite": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "vite build && npm run build:types",
+    "build": "vite build && npm run build:fontawesome && npm run build:types",
+    "build:fontawesome": "vite build --config vite.fontawesome.config.ts",
     "build:types": "vue-tsc --emitDeclarationOnly --declaration --declarationDir dist",
     "test": "vitest --config vitest.config.ts",
     "test:unit": "vitest run --config vitest.config.ts",

package/scripts/fontawesome.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runFontAwesomeCli } from "../dist/fontawesome/cli.mjs";
+
+process.exitCode = await runFontAwesomeCli(process.argv.slice(2));