@usenavii/core 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { b as AvatarOptions, c as AvatarSpec, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, a as AntennaStyleId, A as AccessoryId, B as BackgroundId, T as TopperId, O as OutfitId } from './types-BfsKZ8zK.cjs';
-export { P as Palette } from './types-BfsKZ8zK.cjs';
+import { b as AvatarOptions, c as AvatarSpec, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, a as AntennaStyleId, A as AccessoryId, B as BackgroundId, T as TopperId, O as OutfitId, P as Palette } from './types-CF0rfKly.cjs';
+export { S as StyleHint } from './types-CF0rfKly.cjs';
 
 /**
  * Seed → stable PRNG stream.
@@ -156,6 +156,154 @@ interface BuildSpec {
  */
 declare function build(spec?: BuildSpec, options?: AvatarOptions): string;
 
+/**
+ * Pack type definitions.
+ *
+ * A Pack is a themed bundle of palettes + (eventually) parts that opt-in
+ * extends the deterministic selection pool. Packs are referenced by id in
+ * `AvatarOptions.packs` — when enabled, their content joins the base pool
+ * for that render call.
+ *
+ * Identity rule: every variant a pack ships must have a NAMESPACED id of the
+ * form `<packId>/<localId>` (e.g. `office/suit-body`) to guarantee no
+ * collisions with base variants or other packs.
+ *
+ * Determinism: same `seed` + same enabled `packs` (order-insensitive, by id
+ * set) produce byte-identical output. Enabling a new pack will shift seeds
+ * that previously rendered against the base pool — by design (that's the
+ * "unlock" value).
+ */
+
+/**
+ * Part subset constraints. When a pack with `picks` is enabled, the named
+ * part type is restricted to the listed ids — `selectAvatar` will only pick
+ * from this subset (intersected with other enabled packs' picks). This is
+ * how a pack can make avatars feel themed even without shipping new SVG art:
+ * Office restricts to clean bodies + simple features + no antenna, Halloween
+ * picks creepy bodies + fang mouths + dark toppers, etc.
+ *
+ * Empty/undefined arrays = "no opinion, fall back to base pool".
+ */
+interface PackPicks {
+    body?: readonly BodyShapeId[];
+    eyes?: readonly EyeStyleId[];
+    mouth?: readonly MouthStyleId[];
+    antenna?: readonly AntennaStyleId[];
+    accessory?: readonly AccessoryId[];
+    topper?: readonly TopperId[];
+    background?: readonly BackgroundId[];
+    /**
+     * Constrain the outfit slot. Unlike base avatars (where outfit is always
+     * 'none' from seed selection), a pack can force outfits like ties, scarves,
+     * collars — gives the pack a wardrobe signature.
+     */
+    outfit?: readonly OutfitId[];
+}
+interface Pack {
+    /** Stable identifier. Used as namespace prefix for variant ids. */
+    id: string;
+    /** Display name shown in plugin UI. */
+    name: string;
+    /** One-line description for marketing copy. */
+    description: string;
+    /** Optional emoji glyph for compact UI badges. */
+    emoji?: string;
+    /**
+     * ISO-8601 date string. If set and Date.now() < this date, plugin/UI
+     * should treat the pack as "Coming soon" and refuse activation even for
+     * Pro users. Core itself does not enforce — host code does.
+     */
+    unlockDate?: string;
+    /**
+     * Palettes contributed by this pack. Each palette id should already be
+     * unique (e.g. prefixed with the pack id like `office:navy`) to avoid
+     * collision with the 22 base palettes.
+     */
+    palettes?: Palette[];
+    /**
+     * Constrain selection pools for each part type. Used to give packs a
+     * cohesive visual identity (e.g. Office allows no antenna, Halloween
+     * forces fang mouths). When multiple packs are enabled, their picks are
+     * INTERSECTED — only ids present in every enabled pack's pick list
+     * survive. If the intersection is empty, fall back to the union to avoid
+     * blank renders.
+     */
+    picks?: PackPicks;
+    /**
+     * Render style flags — pack-level directives that bypass the seeded 3D look.
+     *
+     * - `flat`: solid body fill, no gradient, no sheen, no ground shadow.
+     *   Editorial / corporate look. Used by Office.
+     * - `bgColor`: opaque full-bleed background of this color. Replaces the
+     *   seeded background id entirely. e.g. `#FFFFFF` for ID-badge plate.
+     * - `paletteExclusive`: when true, AvatarSpec selection only draws palettes
+     *   from THIS pack's `palettes` list (intersected with base if no pack
+     *   palettes exist). Prevents pack-themed avatars from accidentally using
+     *   off-theme base colors.
+     */
+    flat?: boolean;
+    bgColor?: string;
+    paletteExclusive?: boolean;
+    /**
+     * Multiplier on face-feature stroke width (eyes, mouth, glasses lines).
+     * Default = 1. Higher values = bolder face lines, useful for editorial
+     * packs (Office uses ~1.4).
+     */
+    featureStroke?: number;
+    /**
+     * Apply an outer-glow halo behind the body silhouette. Used by Neon to
+     * give bright bodies a soft cyberpunk light bleed on the dark plate.
+     */
+    glow?: boolean;
+    /**
+     * Style-hint to part-subset mapping. When `AvatarOptions.style` is set to
+     * one of `masc`/`femme`/`neutral`, the corresponding sub-pools are
+     * INTERSECTED with the pack's normal picks. The seed still drives the
+     * actual pick — the hint only narrows the candidate pool.
+     *
+     * Packs that don't define a given style key (or omit this field entirely)
+     * fall through to the normal picks for that part.
+     */
+    styleHints?: {
+        masc?: StylePartSubset;
+        femme?: StylePartSubset;
+        neutral?: StylePartSubset;
+    };
+}
+/** Read-only registry shape — host code passes one to select/render. */
+type PackRegistry = Record<string, Pack>;
+/**
+ * Subset of parts a pack restricts when a specific style hint is requested.
+ * Outfit / accessory / topper are the most expressive of style presentation;
+ * eyes / mouth are optional overrides for packs whose look depends on facial
+ * expression (e.g. pastel/kawaii). Bodies stay seed-driven.
+ */
+interface StylePartSubset {
+    eyes?: readonly EyeStyleId[];
+    mouth?: readonly MouthStyleId[];
+    outfit?: readonly OutfitId[];
+    accessory?: readonly AccessoryId[];
+    topper?: readonly TopperId[];
+}
+
+/**
+ * Built-in pack registry.
+ *
+ * Each pack is its own file so future SVG part data + palette tweaks can be
+ * authored in isolation. Adding a new pack = drop a file here + import +
+ * export it from this module.
+ *
+ * Packs ship empty for Day 1 of the pack infrastructure work — palettes +
+ * parts are added in follow-up commits. The registry exists so the wiring
+ * (selectAvatar, plugin tabs, license gating) can be tested end-to-end
+ * before any premium art lands.
+ */
+
+declare const BUILT_IN_PACKS: Pack[];
+declare const PACK_REGISTRY: PackRegistry;
+/** Resolve a list of pack ids to Pack objects, skipping unknown ids. */
+declare function resolvePacks(ids: readonly string[] | undefined): Pack[];
+
 /**
  * Render a deterministic mascot avatar from a seed.
  *
@@ -237,4 +385,4 @@ declare const Navii: {
     readonly build: typeof build;
 };
 
-export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, random, renderAvatar, renderAvatarInner, renderGroup, seed, selectAvatar };
+export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BUILT_IN_PACKS, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, PACK_REGISTRY, type Pack, type PackRegistry, Palette, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, selectAvatar };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { b as AvatarOptions, c as AvatarSpec, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, a as AntennaStyleId, A as AccessoryId, B as BackgroundId, T as TopperId, O as OutfitId } from './types-BfsKZ8zK.js';
-export { P as Palette } from './types-BfsKZ8zK.js';
+import { b as AvatarOptions, c as AvatarSpec, d as BodyShapeId, E as EyeStyleId, M as MouthStyleId, a as AntennaStyleId, A as AccessoryId, B as BackgroundId, T as TopperId, O as OutfitId, P as Palette } from './types-CF0rfKly.js';
+export { S as StyleHint } from './types-CF0rfKly.js';
 
 /**
  * Seed → stable PRNG stream.
@@ -156,6 +156,154 @@ interface BuildSpec {
  */
 declare function build(spec?: BuildSpec, options?: AvatarOptions): string;
 
+/**
+ * Pack type definitions.
+ *
+ * A Pack is a themed bundle of palettes + (eventually) parts that opt-in
+ * extends the deterministic selection pool. Packs are referenced by id in
+ * `AvatarOptions.packs` — when enabled, their content joins the base pool
+ * for that render call.
+ *
+ * Identity rule: every variant a pack ships must have a NAMESPACED id of the
+ * form `<packId>/<localId>` (e.g. `office/suit-body`) to guarantee no
+ * collisions with base variants or other packs.
+ *
+ * Determinism: same `seed` + same enabled `packs` (order-insensitive, by id
+ * set) produce byte-identical output. Enabling a new pack will shift seeds
+ * that previously rendered against the base pool — by design (that's the
+ * "unlock" value).
+ */
+
+/**
+ * Part subset constraints. When a pack with `picks` is enabled, the named
+ * part type is restricted to the listed ids — `selectAvatar` will only pick
+ * from this subset (intersected with other enabled packs' picks). This is
+ * how a pack can make avatars feel themed even without shipping new SVG art:
+ * Office restricts to clean bodies + simple features + no antenna, Halloween
+ * picks creepy bodies + fang mouths + dark toppers, etc.
+ *
+ * Empty/undefined arrays = "no opinion, fall back to base pool".
+ */
+interface PackPicks {
+    body?: readonly BodyShapeId[];
+    eyes?: readonly EyeStyleId[];
+    mouth?: readonly MouthStyleId[];
+    antenna?: readonly AntennaStyleId[];
+    accessory?: readonly AccessoryId[];
+    topper?: readonly TopperId[];
+    background?: readonly BackgroundId[];
+    /**
+     * Constrain the outfit slot. Unlike base avatars (where outfit is always
+     * 'none' from seed selection), a pack can force outfits like ties, scarves,
+     * collars — gives the pack a wardrobe signature.
+     */
+    outfit?: readonly OutfitId[];
+}
+interface Pack {
+    /** Stable identifier. Used as namespace prefix for variant ids. */
+    id: string;
+    /** Display name shown in plugin UI. */
+    name: string;
+    /** One-line description for marketing copy. */
+    description: string;
+    /** Optional emoji glyph for compact UI badges. */
+    emoji?: string;
+    /**
+     * ISO-8601 date string. If set and Date.now() < this date, plugin/UI
+     * should treat the pack as "Coming soon" and refuse activation even for
+     * Pro users. Core itself does not enforce — host code does.
+     */
+    unlockDate?: string;
+    /**
+     * Palettes contributed by this pack. Each palette id should already be
+     * unique (e.g. prefixed with the pack id like `office:navy`) to avoid
+     * collision with the 22 base palettes.
+     */
+    palettes?: Palette[];
+    /**
+     * Constrain selection pools for each part type. Used to give packs a
+     * cohesive visual identity (e.g. Office allows no antenna, Halloween
+     * forces fang mouths). When multiple packs are enabled, their picks are
+     * INTERSECTED — only ids present in every enabled pack's pick list
+     * survive. If the intersection is empty, fall back to the union to avoid
+     * blank renders.
+     */
+    picks?: PackPicks;
+    /**
+     * Render style flags — pack-level directives that bypass the seeded 3D look.
+     *
+     * - `flat`: solid body fill, no gradient, no sheen, no ground shadow.
+     *   Editorial / corporate look. Used by Office.
+     * - `bgColor`: opaque full-bleed background of this color. Replaces the
+     *   seeded background id entirely. e.g. `#FFFFFF` for ID-badge plate.
+     * - `paletteExclusive`: when true, AvatarSpec selection only draws palettes
+     *   from THIS pack's `palettes` list (intersected with base if no pack
+     *   palettes exist). Prevents pack-themed avatars from accidentally using
+     *   off-theme base colors.
+     */
+    flat?: boolean;
+    bgColor?: string;
+    paletteExclusive?: boolean;
+    /**
+     * Multiplier on face-feature stroke width (eyes, mouth, glasses lines).
+     * Default = 1. Higher values = bolder face lines, useful for editorial
+     * packs (Office uses ~1.4).
+     */
+    featureStroke?: number;
+    /**
+     * Apply an outer-glow halo behind the body silhouette. Used by Neon to
+     * give bright bodies a soft cyberpunk light bleed on the dark plate.
+     */
+    glow?: boolean;
+    /**
+     * Style-hint to part-subset mapping. When `AvatarOptions.style` is set to
+     * one of `masc`/`femme`/`neutral`, the corresponding sub-pools are
+     * INTERSECTED with the pack's normal picks. The seed still drives the
+     * actual pick — the hint only narrows the candidate pool.
+     *
+     * Packs that don't define a given style key (or omit this field entirely)
+     * fall through to the normal picks for that part.
+     */
+    styleHints?: {
+        masc?: StylePartSubset;
+        femme?: StylePartSubset;
+        neutral?: StylePartSubset;
+    };
+}
+/** Read-only registry shape — host code passes one to select/render. */
+type PackRegistry = Record<string, Pack>;
+/**
+ * Subset of parts a pack restricts when a specific style hint is requested.
+ * Outfit / accessory / topper are the most expressive of style presentation;
+ * eyes / mouth are optional overrides for packs whose look depends on facial
+ * expression (e.g. pastel/kawaii). Bodies stay seed-driven.
+ */
+interface StylePartSubset {
+    eyes?: readonly EyeStyleId[];
+    mouth?: readonly MouthStyleId[];
+    outfit?: readonly OutfitId[];
+    accessory?: readonly AccessoryId[];
+    topper?: readonly TopperId[];
+}
+
+/**
+ * Built-in pack registry.
+ *
+ * Each pack is its own file so future SVG part data + palette tweaks can be
+ * authored in isolation. Adding a new pack = drop a file here + import +
+ * export it from this module.
+ *
+ * Packs ship empty for Day 1 of the pack infrastructure work — palettes +
+ * parts are added in follow-up commits. The registry exists so the wiring
+ * (selectAvatar, plugin tabs, license gating) can be tested end-to-end
+ * before any premium art lands.
+ */
+
+declare const BUILT_IN_PACKS: Pack[];
+declare const PACK_REGISTRY: PackRegistry;
+/** Resolve a list of pack ids to Pack objects, skipping unknown ids. */
+declare function resolvePacks(ids: readonly string[] | undefined): Pack[];
+
 /**
  * Render a deterministic mascot avatar from a seed.
  *
@@ -237,4 +385,4 @@ declare const Navii: {
     readonly build: typeof build;
 };
 
-export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, random, renderAvatar, renderAvatarInner, renderGroup, seed, selectAvatar };
+export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BUILT_IN_PACKS, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, PACK_REGISTRY, type Pack, type PackRegistry, Palette, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, selectAvatar };