@vicin/sigil 1.0.0

package/dist/core/mixin.js

@@ -0,0 +1,209 @@
+import { checkInheritance, decorateCtor, generateRandomLabel, getConstructor, isSigilCtor, isSigilInstance, markSigil, markSigilBase, verifyLabel, } from './helpers';
+import { OPTIONS } from './options';
+import { __LABEL__, __TYPE__, __TYPE_LINEAGE__, __TYPE_SET__ } from './symbols';
+/**
+ * Mixin factory that augments an existing class with Sigil runtime metadata and
+ * helpers. The returned class:
+ * - registers a stable symbol for the provided `label` (via `WithSigil`)
+ * - exposes static helpers such as `SigilLabel`, `SigilType`, `isOfType`, and `isOfTypeStrict`
+ * - exposes instance helpers such as `getSigilLabel`, `getSigilType`, etc.
+ *
+ * Notes:
+ * - Uses `Symbol.for(label)` internally so symbols are stable across bundles/realms
+ *   that share the global symbol registry.
+ * - Throws if `Base` is already a sigil constructor.
+ *
+ * @param Base - The base constructor to extend.
+ * @param label - Optional identity label to attach to the resulting class (e.g. '@scope/pkg.ClassName').
+ *                If not passed a random label is generated instead.
+ * @param opts - Options object to override any global options if needed.
+ * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
+ * @throws Error if `Base` is already sigilized.
+ */
+export function Sigilify(Base, label, opts) {
+    // if siglified throw
+    if (isSigilCtor(Base))
+        throw new Error(`[Sigil Error] 'Sigilify(${label})' already siglified.`);
+    // generate random label if not passed and verify it
+    let l;
+    if (label) {
+        verifyLabel(label, opts);
+        l = label;
+    }
+    else
+        l = generateRandomLabel();
+    // extend actual class
+    class Sigilified extends Base {
+        /**
+         * Class-level human-readable label constant for this sigil constructor.
+         */
+        static get SigilLabel() {
+            return this[__LABEL__];
+        }
+        /**
+         * Class-level unique runtime symbol used as the type identifier.
+         *
+         * This symbol is created with `Symbol.for(label)` during decoration so it is
+         * stable across realms that share the same global symbol registry.
+         */
+        static get SigilType() {
+            return this[__TYPE__];
+        }
+        /**
+         * Copy of the linearized sigil type symbol chain for the current constructor.
+         *
+         * Useful for debugging and performing strict lineage comparisons.
+         *
+         * @returns An array of symbols representing parent → child type symbols.
+         */
+        static get SigilTypeLineage() {
+            return [...(this[__TYPE_LINEAGE__] ?? [])];
+        }
+        /**
+         * Copy of the sigil type symbol set for the current constructor.
+         *
+         * Useful for quick membership checks (O(1) lookups) and debugging.
+         *
+         * @returns A Readonly Set of symbols that represent the type lineage.
+         */
+        static get SigilTypeSet() {
+            const set = new Set();
+            for (const s of this[__TYPE_SET__])
+                set.add(s);
+            return set;
+        }
+        constructor(...args) {
+            super(...args);
+            // Correct prototype chain when necessary (defensive for transpiled code / edge cases)
+            if (Object.getPrototypeOf(this) !== new.target.prototype)
+                Object.setPrototypeOf(this, new.target.prototype);
+            // Resolve constructor; defensive null-check helps catch weird runtime cases.
+            const ctor = getConstructor(this);
+            if (!ctor) {
+                if (opts?.devMarker ?? OPTIONS.devMarker)
+                    throw new Error(`[Sigil Error] 'Sigilify(${label})' instance without constructor`);
+                return;
+            }
+            // Perform dev-only inheritance validation to ensure labels are unique across the chain.
+            checkInheritance(ctor);
+        }
+        /**
+         * Runtime predicate indicating whether `obj` is an instance produced by a sigil class.
+         *
+         * @param obj - The value to test.
+         * @returns `true` if `obj` is a sigil instance.
+         */
+        static isSigilified(obj) {
+            return isSigilInstance(obj);
+        }
+        /**
+         * Check whether `other` is (or inherits from) the type represented by the calling constructor.
+         *
+         * Implementation detail:
+         * - Uses the other instance's `__TYPE_SET__` for O(1) membership test.
+         * - O(1) and reliable as long as `OPTIONS.skipLabelInheritanceCheck` is `false`.
+         *
+         * This replaces `instanceof` so that checks remain valid across bundles/realms
+         * and when subclassing.
+         *
+         * @typeParam T - The calling constructor type (narrowing the returned instance type).
+         * @param this - The constructor performing the check.
+         * @param other - The object to test.
+         * @returns `true` if `other` is an instance of this type or a subtype.
+         */
+        static isOfType(other) {
+            if (!isSigilInstance(other))
+                return false;
+            const otherCtor = getConstructor(other);
+            if (!otherCtor)
+                return false;
+            const otherSet = otherCtor[__TYPE_SET__];
+            return !!otherSet && otherSet.has(this.SigilType);
+        }
+        /**
+         * Strict lineage check: compares the type symbol lineage arrays element-by-element.
+         *
+         * Implementation detail:
+         * - Works in O(n) time where n is the depth of the lineage.
+         * - Reliable when `OPTIONS.skipLabelInheritanceCheck` is `false`.
+         *
+         * @typeParam T - The calling constructor type.
+         * @param this - The constructor performing the check.
+         * @param other - The object to test.
+         * @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
+         */
+        static isOfTypeStrict(other) {
+            if (!isSigilInstance(other))
+                return false;
+            const otherCtor = getConstructor(other);
+            if (!otherCtor)
+                return false;
+            const otherLineage = otherCtor[__TYPE_LINEAGE__];
+            const thisLineage = this[__TYPE_LINEAGE__];
+            return (!!otherLineage && thisLineage.every((s, i) => s === otherLineage[i]));
+        }
+        /**
+         * Returns the human-readable sigil label of this instance's constructor.
+         *
+         * @returns The label string (e.g. '@scope/pkg.ClassName') or '@Sigil.unknown' in DEV when constructor is missing.
+         */
+        getSigilLabel() {
+            const ctor = getConstructor(this);
+            if (!ctor) {
+                if (opts?.devMarker ?? OPTIONS.devMarker)
+                    throw new Error(`[Sigil Error] 'Sigilify(${label})' instance without constructor`);
+                return '@Sigil.unknown';
+            }
+            return ctor.SigilLabel;
+        }
+        /**
+         * Returns the runtime sigil type symbol of this instance's constructor.
+         *
+         * @returns The symbol that identifies this type at runtime.
+         */
+        getSigilType() {
+            const ctor = getConstructor(this);
+            if (!ctor) {
+                if (opts?.devMarker ?? OPTIONS.devMarker)
+                    throw new Error(`[Sigil Error] 'Sigilify(${label})' instance without constructor`);
+                return Symbol.for('@Sigil.unknown');
+            }
+            return ctor.SigilType;
+        }
+        /**
+         * Returns a copy of the sigil type symbol lineage for this instance's constructor.
+         *
+         * @returns readonly array of symbols representing the type lineage.
+         */
+        getSigilTypeLineage() {
+            const ctor = getConstructor(this);
+            if (!ctor) {
+                if (opts?.devMarker ?? OPTIONS.devMarker)
+                    throw new Error(`[Sigil Error] 'Sigilify(${label})' instance without constructor`);
+                return [Symbol.for('@Sigil.unknown')];
+            }
+            return ctor.SigilTypeLineage;
+        }
+        /**
+         * Returns a readonly copy of the sigil type symbol set for this instance's constructor.
+         *
+         * @returns A Readonly Set of symbols representing the type lineage for O(1) membership tests.
+         */
+        getSigilTypeSet() {
+            const ctor = getConstructor(this);
+            if (!ctor) {
+                if (opts?.devMarker ?? OPTIONS.devMarker)
+                    throw new Error(`[Sigil Error] 'Sigilify(${label})' instance without constructor`);
+                return new Set([Symbol.for('@Sigil.unknown')]);
+            }
+            return ctor.SigilTypeSet;
+        }
+    }
+    // Attach sigil metadata to constructor (registers label, sets symbols, marks decorated)
+    decorateCtor(Sigilified, l);
+    // Mark the returned constructor as sigil (runtime flag) and as a base.
+    markSigil(Sigilified);
+    markSigilBase(Sigilified);
+    return Sigilified;
+}
+//# sourceMappingURL=mixin.js.map

package/dist/core/mixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixin.js","sourceRoot":"","sources":["../../src/core/mixin.ts"],"names":[],"mappings":"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"}

package/dist/core/options.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Configuration options for the Sigil library.
+ *
+ * These options control runtime validation, inheritance checks, label autofill behavior,
+ * and whether duplicate labels are permitted globally.
+ *
+ * Note: these options are read by runtime code during class decoration and inheritance
+ * checks. Some behaviors (like `skipLabelInheritanceCheck`) are meant primarily for
+ * development/test scenarios and may weaken type/identity guarantees when changed.
+ */
+export interface SigilOptions {
+    /**
+     * Validation rule applied to sigil labels before registration.
+     *
+     * - A function receives the label and must return `true` if valid.
+     * - A `RegExp` must match the label.
+     * - `null` disables validation entirely.
+     *
+     * Defaults to `null`.
+     */
+    labelValidation?: ((label: string) => boolean) | RegExp | null;
+    /**
+     * Skips the runtime check that prevents subclasses from inheriting
+     * the same sigil label as their ancestors.
+     *
+     * When `false` (default), extending a sigil class without
+     * using `WithSigil(newLabel)` decorator will throw an error if the label
+     * is reused and `OPTIONS.autofillLabels` is set to `false`.
+     *
+     * Set this to `true` only if you intentionally want subclasses to inherit labels
+     * from their ancestors (this weakens the uniqueness guarantees).
+     */
+    skipLabelInheritanceCheck?: boolean;
+    /**
+     * When enabled, non-decorated subclasses that would otherwise inherit an ancestor's label
+     * will be assigned an autogenerated random label (so that explicit labels stay unique).
+     */
+    autofillLabels?: boolean;
+    /**
+     * Marker used internally to control dev only checks to optimize performace while preserving
+     * consistency for things like inheritance checks.
+     * defaults to 'process.env.NODE_ENV !== "production'.
+     */
+    devMarker?: boolean;
+}
+/**
+ * Default runtime options used by the Sigil library.
+ *
+ * These values may be mutated by calling `updateOptions` at app startup.
+ *
+ * @internal
+ */
+export declare const OPTIONS: Required<SigilOptions>;
+/**
+ * Update runtime options for the Sigil library.
+ * Call this early during application startup if you want non-default behavior.
+ *
+ * Example:
+ * ```ts
+ * updateOptions({ autofillLabels: true, labelValidation: /^@[\w-]+\/[\w-]+\.[A-Za-z0-9]+$/ });
+ * ```
+ *
+ * @param opts - Partial options to merge into the global `OPTIONS` object.
+ */
+export declare const updateOptions: (opts: SigilOptions) => void;
+/**
+ * Label validation regex. Labels must follow the pattern
+ * `@scope/package.ClassName` where `ClassName` begins with an uppercase
+ * letter. This avoids collisions across packages and helps debugging.
+ *
+ * It's advised to use this regex in 'SigilOptions.labelValidation'.
+ */
+export declare const DEFAULT_LABEL_REGEX: RegExp;
+//# sourceMappingURL=options.d.ts.map

package/dist/core/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/core/options.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IAE/D;;;;;;;;;;OAUG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAEpC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAC,YAAY,CAK1C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,YAAY,KAAG,IAElD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAA8C,CAAC"}

package/dist/core/options.js

@@ -0,0 +1,39 @@
+/** Dev check */
+const DEV = process.env.NODE_ENV !== 'production';
+/**
+ * Default runtime options used by the Sigil library.
+ *
+ * These values may be mutated by calling `updateOptions` at app startup.
+ *
+ * @internal
+ */
+export const OPTIONS = {
+    labelValidation: null,
+    skipLabelInheritanceCheck: false,
+    autofillLabels: false,
+    devMarker: DEV,
+};
+/**
+ * Update runtime options for the Sigil library.
+ * Call this early during application startup if you want non-default behavior.
+ *
+ * Example:
+ * ```ts
+ * updateOptions({ autofillLabels: true, labelValidation: /^@[\w-]+\/[\w-]+\.[A-Za-z0-9]+$/ });
+ * ```
+ *
+ * @param opts - Partial options to merge into the global `OPTIONS` object.
+ */
+export const updateOptions = (opts) => {
+    for (const [k, v] of Object.entries(opts))
+        OPTIONS[k] = v;
+};
+/**
+ * Label validation regex. Labels must follow the pattern
+ * `@scope/package.ClassName` where `ClassName` begins with an uppercase
+ * letter. This avoids collisions across packages and helps debugging.
+ *
+ * It's advised to use this regex in 'SigilOptions.labelValidation'.
+ */
+export const DEFAULT_LABEL_REGEX = /^@[\w-]+(?:\/[\w-]+)*\.[A-Z][A-Za-z0-9]*$/;
+//# sourceMappingURL=options.js.map

package/dist/core/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/core/options.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;AAmDlD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAA2B;IAC7C,eAAe,EAAE,IAAI;IACrB,yBAAyB,EAAE,KAAK;IAChC,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE,GAAG;CACf,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAkB,EAAQ,EAAE;IACxD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAAG,OAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACrE,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,2CAA2C,CAAC"}

package/dist/core/registry.d.ts

@@ -0,0 +1,104 @@
+import { type SigilOptions } from './options';
+import type { ISigil } from './types';
+/** --------------------------------
+ *  Registry class
+ * -------------------------------- */
+/**
+ * Small wrapper around a shared registry Set that provides safe operations
+ * and hot-reload-friendly behavior.
+ *
+ * Responsibilities:
+ * - Query the current registry (may be `null` to indicate disabled checks).
+ * - Register / unregister labels in a controlled manner.
+ * - Query class constructors using there 'SigilLabel'.
+ * - Support hot-reload tolerant registration (avoid throwing in DEV).
+ * - Replace / merge registries when a new Map is provided by the consumer.
+ *
+ * This class intentionally keeps a minimal API so consumers can use a single
+ * shared instance (`REGISTRY`) or instantiate their own if needed.
+ */
+declare class Registry {
+    /** Internal pointer to the active registry (may be null to indicate checks disabled). */
+    private _registry;
+    /**
+     * Return a readonly view (array) of the current registry entries.
+     *
+     * @returns An array containing all registered labels, or an empty array when registry is disabled.
+     */
+    listLabels(): string[];
+    /**
+     * Determine whether the registry currently contains `label`.
+     *
+     * @param label - The label to test.
+     * @returns `true` if present; `false` otherwise or when registry is disabled.
+     */
+    has(label: string): boolean;
+    /**
+     * Get class constructor using its label.
+     *
+     * @param label - Label appended to Sigil class.
+     * @returns Reference to Sigil class constructor.
+     */
+    get(label: string): ISigil | undefined;
+    /**
+     * Register a label and class constructor in the active registry.
+     *
+     * Behavior:
+     * - If the registry is disabled (`null`), this is a no-op.
+     * - If the label already exists then:
+     *     - In DEV builds: prints a console warning (HMR friendly) and returns early.
+     *     - In non-DEV builds: throws an Error to prevent duplicate registration.
+     *
+     * @param label - Label string to register (e.g. '@scope/pkg.ClassName').
+     * @param Class - Constructor of the class being registered.
+     * @param opts - Optional per-call overrides.
+     */
+    register(label: string, Class: ISigil, opts?: Pick<SigilOptions, 'devMarker'>): void;
+    /**
+     * Unregister a previously registered class.
+     *
+     * @param label - The label to remove from the registry.
+     * @returns `true` if the label was present and removed; `false` otherwise (or when registry is disabled).
+     */
+    unregister(label: string): boolean;
+    /**
+     * Clear the registry completely.
+     *
+     * Useful for test teardown, or when explicitly resetting state during development.
+     * No-op when the registry is disabled.
+     */
+    clear(): void;
+    /**
+     * Replace the active registry with `newRegistry`.
+     *
+     * When replacing, any existing entries are merged into `newRegistry` so that
+     * registrations are not lost automatically. This design choice preserves
+     * previously registered labels while allowing callers to supply a custom Set
+     * instance (for example, a Set shared between worker threads or an external
+     * synchronization mechanism).
+     *
+     * Important notes:
+     * - Replacing the registry transfers existing entries into `newRegistry` when both are non-null.
+     * - The global default Set stored on `globalThis` is *not* updated by this method; responsibility
+     *   for further management of the `newRegistry` (such as re-exposing it on `globalThis`) lies with the caller.
+     * - If you want to *disable* registry checks, call `replaceRegistry(null)`.
+     *
+     * @param newRegistry - New Set<string> instance to use as the active registry, or `null` to disable checks.
+     */
+    replaceRegistry(newRegistry: Map<string, ISigil> | null): void;
+    /**
+     * Get the size (number of entries) of the active registry.
+     *
+     * @returns The number of registered labels, or 0 when registry is disabled.
+     */
+    get size(): number;
+}
+/**
+ * Convenience singleton instance for consumers that prefer a single shared API.
+ *
+ * Use `REGISTRY` to register/unregister labels, inspect the registry, and (optionally)
+ * replace the active Set by calling `REGISTRY.replaceRegistry(...)`.
+ */
+export declare const REGISTRY: Registry;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAwCtC;;sCAEsC;AAEtC;;;;;;;;;;;;;GAaG;AACH,cAAM,QAAQ;IACZ,yFAAyF;IACzF,OAAO,CAAC,SAAS,CAAmD;IAEpE;;;;OAIG;IACH,UAAU,IAAI,MAAM,EAAE;IAItB;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAI3B;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKtC;;;;;;;;;;;;OAYG;IACH,QAAQ,CACN,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GACrC,IAAI;IAiBP;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAKlC;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI;IAO9D;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,UAAiB,CAAC"}

package/dist/core/registry.js

@@ -0,0 +1,174 @@
+import { OPTIONS } from './options';
+/** --------------------------------
+ *  Default registry
+ * -------------------------------- */
+/**
+ * Global registry key used on `globalThis` to store a map of Sigil labels and reference to there classes.
+ *
+ * We use `Symbol.for` so the same key survives across bundles that share the
+ * global symbol registry (useful for HMR/dev workflows).
+ *
+ * @internal
+ * @constant {symbol}
+ */
+const __SIGIL_REGISTRY__ = Symbol.for('@Sigil.__SIGIL_REGISTRY__');
+/**
+ * Lazily initialize and return the global label registry Map.
+ *
+ * The registry is stored on `globalThis` so it survives module reloads during HMR.
+ * If registry checks are intentionally disabled, users can replace the active registry
+ * with `null` via `REGISTRY.replaceRegistry(null)`.
+ *
+ * @returns A Map<string, ISigil> representing the active registry (created if missing).
+ */
+const getGlobalRegistry = () => {
+    if (!(__SIGIL_REGISTRY__ in globalThis)) {
+        globalThis[__SIGIL_REGISTRY__] = new Map();
+    }
+    return globalThis[__SIGIL_REGISTRY__];
+};
+/**
+ * Update global map stored.
+ */
+const updateGlobalRegistry = (map) => {
+    globalThis[__SIGIL_REGISTRY__] = map;
+};
+/** --------------------------------
+ *  Registry class
+ * -------------------------------- */
+/**
+ * Small wrapper around a shared registry Set that provides safe operations
+ * and hot-reload-friendly behavior.
+ *
+ * Responsibilities:
+ * - Query the current registry (may be `null` to indicate disabled checks).
+ * - Register / unregister labels in a controlled manner.
+ * - Query class constructors using there 'SigilLabel'.
+ * - Support hot-reload tolerant registration (avoid throwing in DEV).
+ * - Replace / merge registries when a new Map is provided by the consumer.
+ *
+ * This class intentionally keeps a minimal API so consumers can use a single
+ * shared instance (`REGISTRY`) or instantiate their own if needed.
+ */
+class Registry {
+    /** Internal pointer to the active registry (may be null to indicate checks disabled). */
+    _registry = getGlobalRegistry();
+    /**
+     * Return a readonly view (array) of the current registry entries.
+     *
+     * @returns An array containing all registered labels, or an empty array when registry is disabled.
+     */
+    listLabels() {
+        return this._registry ? Array.from(this._registry.keys()) : [];
+    }
+    /**
+     * Determine whether the registry currently contains `label`.
+     *
+     * @param label - The label to test.
+     * @returns `true` if present; `false` otherwise or when registry is disabled.
+     */
+    has(label) {
+        return !!this._registry && this._registry.has(label);
+    }
+    /**
+     * Get class constructor using its label.
+     *
+     * @param label - Label appended to Sigil class.
+     * @returns Reference to Sigil class constructor.
+     */
+    get(label) {
+        if (!this._registry)
+            return;
+        return this._registry.get(label);
+    }
+    /**
+     * Register a label and class constructor in the active registry.
+     *
+     * Behavior:
+     * - If the registry is disabled (`null`), this is a no-op.
+     * - If the label already exists then:
+     *     - In DEV builds: prints a console warning (HMR friendly) and returns early.
+     *     - In non-DEV builds: throws an Error to prevent duplicate registration.
+     *
+     * @param label - Label string to register (e.g. '@scope/pkg.ClassName').
+     * @param Class - Constructor of the class being registered.
+     * @param opts - Optional per-call overrides.
+     */
+    register(label, Class, opts) {
+        if (!this._registry)
+            return;
+        if (this._registry.has(label)) {
+            if (opts?.devMarker ?? OPTIONS.devMarker)
+                // The console is intentional
+                // eslint-disable-next-line no-console
+                console.warn(`[Sigil] Duplicate label "${label}" may be due to HMR — ignore if you are sure that it's defined once.`);
+            else
+                throw new Error(`[Sigil Error] Duplicate label '${label}' detected. Labels must be unique.`);
+        }
+        else
+            this._registry.set(label, Class);
+    }
+    /**
+     * Unregister a previously registered class.
+     *
+     * @param label - The label to remove from the registry.
+     * @returns `true` if the label was present and removed; `false` otherwise (or when registry is disabled).
+     */
+    unregister(label) {
+        if (!this._registry)
+            return false;
+        return this._registry.delete(label);
+    }
+    /**
+     * Clear the registry completely.
+     *
+     * Useful for test teardown, or when explicitly resetting state during development.
+     * No-op when the registry is disabled.
+     */
+    clear() {
+        if (!this._registry)
+            return;
+        this._registry.clear();
+    }
+    /**
+     * Replace the active registry with `newRegistry`.
+     *
+     * When replacing, any existing entries are merged into `newRegistry` so that
+     * registrations are not lost automatically. This design choice preserves
+     * previously registered labels while allowing callers to supply a custom Set
+     * instance (for example, a Set shared between worker threads or an external
+     * synchronization mechanism).
+     *
+     * Important notes:
+     * - Replacing the registry transfers existing entries into `newRegistry` when both are non-null.
+     * - The global default Set stored on `globalThis` is *not* updated by this method; responsibility
+     *   for further management of the `newRegistry` (such as re-exposing it on `globalThis`) lies with the caller.
+     * - If you want to *disable* registry checks, call `replaceRegistry(null)`.
+     *
+     * @param newRegistry - New Set<string> instance to use as the active registry, or `null` to disable checks.
+     */
+    replaceRegistry(newRegistry) {
+        const old = this._registry;
+        if (old && newRegistry)
+            for (const [l, c] of old)
+                newRegistry.set(l, c);
+        updateGlobalRegistry(newRegistry);
+        this._registry = newRegistry;
+    }
+    /**
+     * Get the size (number of entries) of the active registry.
+     *
+     * @returns The number of registered labels, or 0 when registry is disabled.
+     */
+    get size() {
+        return this._registry ? this._registry.size : 0;
+    }
+}
+/**
+ * Convenience singleton instance for consumers that prefer a single shared API.
+ *
+ * Use `REGISTRY` to register/unregister labels, inspect the registry, and (optionally)
+ * replace the active Set by calling `REGISTRY.replaceRegistry(...)`.
+ */
+export const REGISTRY = new Registry();
+//# sourceMappingURL=registry.js.map

package/dist/core/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"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"}