icons — one pipeline, two faces, one component

// vite.config.ts — the library face (this site's own wiring, condensed)
import { sveltekit } from '@sveltejs/kit/vite';
import { jixoai } from '@jixoai/ui-vite-plugin';
import { md } from '@jixoai/ui-vite-plugin/icons/md';
import { ph } from '@jixoai/ui-vite-plugin/icons/ph';
import { rx } from '@jixoai/ui-vite-plugin/icons/rx';

export default {
  plugins: [
    sveltekit(),
    ...jixoai({
      icons: {
        library: {
          includeDefaults: true,            // the 38 built-ins (default)
          channels: [md(), ph(), rx()],     // the shipped channels — one import each
          icons: {                          // add + override — every source form
            brand: 'lucide:zap',            // a lucide ref — resolved at BUILD time
            logo: { file: 'assets/logo.svg' }, // a .svg file — the plugin owns the I/O
            spark: '<svg xmlns="…">…</svg>',   // an inline literal — RAW safety-checked
            home: 'md:home',                // a channel ref — outlined/400/FILL-0 Material
            glyph: { font: 'brand.woff2', code: 0xE002 }, // a font glyph, extracted
          },
          maxChunkBytes: 20480,             // RAW module bytes per chunk (default)
          chunking: 'auto',                 // 'single' = one chunk, no splitting
          inlineFirstChunk: true,           // chunk 0 inline → sync getIcon (default)
          optimize: true,                   // svgo pass (default)
          write: false,                     // the repo's gen:icons script is the writer
        },
      },
    }),
  ],
};

/* the artifact it generates (default config → the plugin-free tier):
   import { getIcon, loadIcon, preloadIcons, ICON_NAMES, type IconName }
     from '$lib/icon-set.gen'; */

// registering the shipped channels: one import each, frozen defaults
import { md } from '@jixoai/ui-vite-plugin/icons/md';
import { ph } from '@jixoai/ui-vite-plugin/icons/ph';
import { rx } from '@jixoai/ui-vite-plugin/icons/rx';

library: { channels: [md(), ph(), rx()] }   // lucide: needs NO entry

// or the knobs (one weight = ONE peer package)
import { md } from '@jixoai/ui-vite-plugin/icons/md';
library: { channels: [md({ weight: 400, style: 'rounded', fill: true })] }

// referencing a prefix you have NOT enabled is a named startup error
// listing the enabled set — "fa:home" fails, teaching the fix

// vite.config.ts — your own channel, from the consumer's own assets
import { jixoai } from '@jixoai/ui-vite-plugin';
import { defineIconChannel, resolvePeerFile } from '@jixoai/ui-vite-plugin/icons/channel';

const myco = defineIconChannel({
  id: 'myco',                      // /^[a-z][a-z0-9-]*$/, unique among registered
  prefix: 'myco',                  // /^[a-z][a-z0-9]*$/ — becomes the myco: namespace
  peerPackage: 'my-icons',         // optional peer — named in install-hint errors
  resolveFile: (ref) => resolvePeerFile('my-icons', `svgs/${ref}.svg`),
  defaultsNote: 'my-icons svgs/ (outlined)',
});

export default {
  plugins: [/* … */ jixoai({ icons: { library: { channels: [myco] } } })],
};

// that single registration buys, for the myco: prefix:
//   - config refs — icons: { logo: 'myco:logo' }
//   - source scanning — a static myco-prefixed name attribute in any
//     .svelte/.ts/.js/.html file packs with ZERO library.icons entry
//   - template union — IconName gains a myco-backtick template member
//   - the enabled-prefix + uniqueness laws, exactly like a shipped one
// the channel LOCATES (node resolution to the ABSOLUTE svg path); the
// adapter READS through the plugin's provider context — mime law +
// watchFile HMR — and every icon crosses the shared RAW safety → svgo
// → extract pipeline. A custom channel inherits the built-ins'
// guarantees by construction; it can never smuggle unvetted bytes.

// examples/hmos-icons/src/lib/icons/hmos.ts — the entire integration
import { fileURLToPath } from 'node:url';
import { defineIconChannel } from '@jixoai/ui-vite-plugin/icons/channel';

export const hmos = () =>
  defineIconChannel({
    id: 'hmos',
    prefix: 'hmos',
    // the absolute-path contract: one ref, one absolute svg path
    resolveFile: (ref) => fileURLToPath(new URL(`../../../icons/${ref}.svg`, import.meta.url)),
  });

<!-- with channels: [md()] registered — write prefixed names
     directly, NO library.icons declaration needed -->
<Icon name="md:copy_all" />            <!-- scanned → packs under the canonical -->
<Icon name="md:copy_all as copy2" />   <!-- the as form: alias + canonical, ONE payload -->
<Icon name="copy2" />                  <!-- the alias resolves the SAME icon -->
<Icon name="lucide:check" />           <!-- lucide scans too — default-registered -->
<Icon name={`md:${iconKey}`} />        <!-- dynamic: NOT scanned — the runtime lane -->

// the artifact the compiler generates (sources are NEVER rewritten)
export const ALIASES: Readonly<Record<string, string>> = {
  copy2: 'md:copy_all',   // one table row per alias — never a second payload
};
// a scanned lucide:X whose X is ALREADY packed dedupes the same way —
// through a SEPARATE compiler-generated table:
export const EQUIVALENCES: Readonly<Record<string, string>> = {
  'lucide:check': 'check', // the built-in's artwork — ONE payload, chained lookups
};
// canonicalOf chains ALIASES then EQUIVALENCES: getIcon('md:copy_all'),
// getIcon('copy2'), the full literal, getIcon('lucide:check') and an
// aliased equivalence all resolve their ONE packed payload

// a font FILE is an icon source — the outline is EXTRACTED at build
// time (opentype.js + the same contain-fit math as the slot face) and
// the artifact stays pure SVG: no font bytes reach the browser
icons: {
  brand:  { font: 'brand.woff2', code: 0xE002 },  // codepoint (cmap)
  logo:   { font: 'brand.woff2', liga: 'md-logo' }, // ligature, best-effort
  legacy: { font: 'old/icon.ttf',  code: 0x41 },    // ttf/otf directly
}
// woff2 decompresses through the same loadSource lane (wawoff2);
// woff1 stays the hard error. A codepoint missing from cmap, a blank
// outline, or an unresolvable ligature fails BY NAME (the miss lists
// the font's resolvable ligatures when the parser exposes them).
// The gen:icons script twin is svg-only: font sources are a
// named vite-plugin-only lane there.

[jixoai/icon-set] virtual:jixoai-icons/chunk/* imported but no icons library is configured — wire jixoai({ icons: { library } }) in your vite plugins (see the icon-set item docs)

chunk 0 (inline) ── getIcon(name) answers synchronously
                      SSR paints the glyph in the server HTML,
                      hydration matches — ZERO wiring owed

chunks 1+ (lazy) ── loadIcon(name) dynamic-imports
                      virtual:jixoai-icons/chunk/K (cached promise);
                      pending renders the FIXED reserved box:
                      <span data-jx-icon-pending aria-hidden="true"
                        style="display:inline-block;width:16px;height:16px">
                      pending AND rejected render the IDENTICAL span, so
                      hydration never rewrites the box; a failed chunk
                      warns once per chunk per session — the box stays.

preloadIcons(['folderOpen', 'fileVideo'])  // warm lazy chunks ahead of a mount

// vite.config.ts — this site's own wiring: BOTH faces, one plugin call
import { jixoai } from '@jixoai/ui-vite-plugin';
import { lucideIconProvider } from '@jixoai/ui-vite-plugin/icons';

export default {
  plugins: [
    sveltekit(),
    ...jixoai({
      icons: {
        provider: lucideIconProvider(),    // the SLOT face — --jx-icon-* vocabulary
        safety: { mode: 'warn' },          // shared by both faces
        library: { includeDefaults: true }, // the LIBRARY face — <Icon name>
      },
    }),
  ],
};

/* app.css — the slot face's ONLY injection path: a virtual CSS module
   @import 'virtual:jixoai-icons'; */