@kritzel/engine 0.4.31

package/dist/types/classes/managers/cursor.manager.d.ts

@@ -0,0 +1,66 @@
+import { KritzelCore } from '../core/core.class';
+/**
+ * Manages cursor state and updates across the application.
+ * Handles cursor changes based on handle hovers, tool states, and interactions.
+ */
+export declare class KritzelCursorManager {
+    private readonly _core;
+    private _targetElement;
+    private _shadowRoot;
+    /**
+     * Creates a new KritzelCursorManager instance.
+     * @param core - The KritzelCore instance that provides access to the store and other core functionality.
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Sets the target element where cursor styles will be applied.
+     * Resets any cursor styles on the previous target element before setting the new one.
+     * Also sets the `--kritzel-global-pointer-cursor` CSS variable for child components to use.
+     * @param element - The HTML element to apply cursor styles to, or null to clear the target.
+     */
+    setTargetElement(element: HTMLElement | null): void;
+    /**
+     * Gets the current cursor target element.
+     * @returns The HTML element where cursor styles are applied, or null if not set.
+     */
+    getTargetElement(): HTMLElement | null;
+    /**
+     * Sets the shadow root used for element detection in hover state calculations.
+     * Required for `elementsFromPoint()` to work within the shadow DOM.
+     * @param shadowRoot - The ShadowRoot instance of the component.
+     */
+    setShadowRoot(shadowRoot: ShadowRoot): void;
+    /**
+     * Resets cursor to default state by setting both icon and iconActive to 'default'.
+     * Should be called when all pointers are released to return to the standard cursor.
+     */
+    resetToDefault(): void;
+    /**
+     * Detects handle hover states using elementsFromPoint() to work with overlapped elements.
+     * This approach finds all elements at the pointer position instead of relying on pointerenter/pointerleave,
+     * which allows proper detection even when elements overlap.
+     *
+     * Updates the cursor state based on which handle type is being hovered:
+     * - Resize handle overlays: Sets a rotated vertical move cursor based on handle position and selection rotation.
+     * - Rotation handle overlays: Sets a hand cursor that changes to grab when active.
+     * - Line handle overlays: Sets a hand cursor that changes to grab when active.
+     * - No handle: Resets to default cursor.
+     *
+     * @param ev - The PointerEvent containing the cursor position (clientX, clientY).
+     */
+    updateHoverState(ev: PointerEvent): void;
+    /**
+     * Applies the current cursor state to the target element.
+     * Reads the cursor configuration from the store state and uses KritzelCursorHelper
+     * to generate the appropriate cursor value. Uses the active icon when pointer is down,
+     * otherwise uses the default icon.
+     * Should be called in the render loop to keep the cursor in sync with state.
+     */
+    applyCursor(): void;
+    /**
+     * Cleans up cursor state when the component is disconnected.
+     * Removes cursor styles and CSS custom properties from the target element,
+     * then clears all internal references to allow garbage collection.
+     */
+    cleanup(): void;
+}

package/dist/types/classes/managers/license.manager.d.ts

@@ -0,0 +1,147 @@
+import { KritzelCore } from '../core/core.class';
+/**
+ * Manages license validation state for the Kritzel editor.
+ *
+ * The manager is owned per {@link KritzelCore} instance (like the theme and
+ * localization managers) so that multiple editors on the same page validate
+ * independently.
+ *
+ * A license key is an offline Ed25519 signed token of the form
+ * `KRTZL1.<base64url(payload)>.<base64url(signature)>`. The library verifies it
+ * against the embedded {@link KRITZEL_LICENSE_PUBLIC_KEY}; only the owner can
+ * mint tokens, with the matching private key (see scripts/license/).
+ *
+ * Responsibilities:
+ * - Cheaply reject absent/malformed/expired keys synchronously so the watermark
+ *   never flashes off for an obviously invalid key.
+ * - Verify the signature asynchronously via WebCrypto, then drive a rerender if
+ *   the licensed state changed so the watermark is re-asserted on the reactive
+ *   render path.
+ * - Periodically re-check on a randomized interval so the check is harder to
+ *   stub out programmatically than a fixed `setInterval`. Re-checks reuse the
+ *   cached verified token and only re-evaluate expiry, so crypto is not re-run
+ *   on an unchanged key every tick.
+ *
+ * Failure semantics (fail open):
+ * - No key provided -> unlicensed (free tier, watermark shown). The normal
+ *   default, not an error.
+ * - Key present but cleanly invalid (malformed, bad signature, expired) ->
+ *   unlicensed.
+ * - Key present but validation throws an *unexpected* internal error, or the
+ *   runtime lacks Ed25519 support in WebCrypto -> fail open and treat as
+ *   licensed so a library defect or old browser never breaks a paying
+ *   customer's app.
+ */
+export declare class KritzelLicenseManager {
+    private readonly _core;
+    /** The most recently provided license key, re-checked on each periodic tick. */
+    private _licenseKey?;
+    /** Cached result of the latest validation. */
+    private _isLicensed;
+    /**
+     * The token whose signature most recently verified successfully. Lets the
+     * periodic re-check skip crypto and only re-evaluate expiry while the key is
+     * unchanged.
+     */
+    private _verifiedToken?;
+    /**
+     * Monotonic id incremented on every {@link validate} call. An in-flight async
+     * verification only commits its result if its id still matches, so a stale
+     * verification resolving after a newer call can never clobber fresh state.
+     */
+    private _validationId;
+    /** Cached imported public key, lazily created on first signature check. */
+    private _publicKeyPromise?;
+    /** Handle for the self-rescheduling re-validation timer. */
+    private _timer;
+    /**
+     * Creates a new KritzelLicenseManager instance.
+     * @param core - The KritzelCore instance this manager belongs to
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Whether the editor is currently considered licensed (watermark hidden).
+     */
+    get isLicensed(): boolean;
+    /**
+     * Validates the given license key.
+     *
+     * Runs a synchronous structural pre-check first: an absent, malformed, or
+     * already-expired key resolves the state immediately (no async work). A
+     * structurally valid key then has its signature verified asynchronously; the
+     * licensed state is committed (and a rerender triggered) only if it changed.
+     *
+     * The return value reflects the state known *synchronously* at call time. The
+     * authoritative result for a structurally valid key arrives shortly after via
+     * the async verification and the reactive rerender.
+     *
+     * @param key - The license key to validate, or undefined to clear the license
+     * @returns The licensed state known synchronously at call time
+     */
+    validate(key?: string): boolean;
+    /**
+     * Starts periodic re-validation on a randomized interval between
+     * {@link MIN_REVALIDATION_DELAY_MS} and {@link MAX_REVALIDATION_DELAY_MS}.
+     *
+     * Uses a self-rescheduling `setTimeout` (a fresh random delay each cycle)
+     * rather than a fixed `setInterval`, making the check fractionally harder to
+     * predict and no-op programmatically. Any existing timer is cleared first so
+     * the method is idempotent.
+     */
+    startPeriodicValidation(): void;
+    /**
+     * Stops periodic re-validation and releases the timer.
+     */
+    stopPeriodicValidation(): void;
+    /**
+     * Cleanup hook called when the editor is torn down.
+     */
+    destroy(): void;
+    /**
+     * Commits a new licensed state, triggering a rerender only when it changed.
+     * The {@link validationId} guard is checked by async callers; synchronous
+     * callers pass the current id.
+     */
+    private commit;
+    /**
+     * Schedules the next re-validation tick at a randomized delay.
+     */
+    private scheduleNextValidation;
+    /**
+     * Returns a random delay within the configured re-validation window.
+     */
+    private getRandomRevalidationDelay;
+    /**
+     * Synchronous structural pre-check of a license key: verifies the format
+     * prefix, three-part structure, JSON payload, and (if present) that the token
+     * has not expired. Does not verify the signature.
+     *
+     * @returns `rejected` for absent/malformed/expired keys, or `pass` with the
+     *   parsed segments and claims for a structurally valid, unexpired token.
+     */
+    private preCheck;
+    /** Returns the normalized current hostname, or null when unavailable/invalid. */
+    private getCurrentHostname;
+    /** Normalizes and validates the allowed domains claim. */
+    private normalizeAllowedDomains;
+    /** Normalizes a domain and rejects malformed hostnames. */
+    private normalizeDomain;
+    /**
+     * Verifies the Ed25519 signature of the token against the embedded public
+     * key. Resolves true/false for a definitive valid/invalid signature.
+     *
+     * Rejects (rather than resolving false) on unexpected crypto failures or when
+     * the runtime lacks Ed25519 support, so the caller fails open.
+     */
+    private verifySignature;
+    /**
+     * Imports and caches the embedded Ed25519 public key for signature checks.
+     */
+    private getPublicKey;
+    /** Decodes a base64url string to its UTF-8 text. */
+    private base64UrlToString;
+    /** Decodes a base64url string to raw bytes. */
+    private base64UrlToBytes;
+    /** Encodes a string to its UTF-8 bytes. */
+    private utf8Bytes;
+}

package/dist/types/classes/managers/localization.manager.d.ts

@@ -0,0 +1,145 @@
+import { KritzelCore } from '../core/core.class';
+import { KritzelLocale, KritzelTermKey, KritzelTermVars, LocaleCode } from '../../interfaces/localization.interface';
+/**
+ * Manages localization state and term resolution across the Kritzel editor.
+ *
+ * The manager is owned per {@link KritzelCore} instance (like the theme manager)
+ * so that multiple editors on the same page can use different languages in
+ * isolation.
+ *
+ * Term resolution follows a deterministic fallback chain for each key:
+ * 1. active locale's custom terms
+ * 2. active locale's built-in terms
+ * 3. fallback locale's custom terms
+ * 4. fallback locale's built-in terms
+ * 5. the key itself (last resort)
+ *
+ * Persistence of the selected locale is handled by the KritzelSettings
+ * component; this manager only reads the stored value.
+ */
+export declare class KritzelLocalizationManager {
+    private readonly _core;
+    private readonly _storageKey;
+    /** Built-in locale definitions, keyed by locale code. */
+    private readonly _builtinLocales;
+    /** Consumer-registered locale definitions, keyed by locale code. */
+    private readonly _customLocales;
+    private _currentLocale;
+    private _fallbackLocale;
+    /** Whether the consumer explicitly configured a locale catalog (even an empty one) via `configureLocales`. */
+    private _explicitLocales;
+    /**
+     * Creates a new KritzelLocalizationManager instance.
+     * Seeds the built-in locales and initializes the current locale from the
+     * settings object in localStorage (or the default locale).
+     *
+     * @param core - The KritzelCore instance this manager belongs to
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Gets the currently active locale code.
+     */
+    get currentLocale(): LocaleCode;
+    /**
+     * Gets the fallback locale code used when a term is missing from the active locale.
+     */
+    get fallbackLocale(): LocaleCode;
+    /**
+     * Sets the fallback locale code used when a term is missing from the active locale.
+     *
+     * @param code - The fallback locale code
+     */
+    setFallbackLocale(code: LocaleCode): void;
+    /**
+     * Registers consumer-provided locale definitions. Definitions are merged by
+     * code; registering the same code again replaces the previous definition.
+     * A registered locale may provide a partial set of terms — missing terms are
+     * resolved through the fallback chain.
+     *
+     * @param locales - The locale definitions to register
+     */
+    registerLocales(locales: KritzelLocale[]): void;
+    /**
+     * Declaratively configures the full locale catalog, replacing any previously
+     * configured or registered custom locales. Unlike {@link registerLocales},
+     * this determines which locales are considered "available" (e.g. for a
+     * settings selector): passing `undefined` restores the built-in set
+     * (en/de/fr); passing an array (even empty) makes that array's codes the
+     * exclusive available set, falling back to `en` only if the array is empty.
+     * Built-in term fallback for missing keys is unaffected either way.
+     *
+     * @param locales - The full locale catalog, or `undefined` to use built-ins
+     */
+    configureLocales(locales?: KritzelLocale[]): void;
+    /**
+     * Resolves the locale code that should actually be activated, falling back
+     * to the first available locale when the requested one isn't available.
+     *
+     * @param requested - The locale code the consumer asked to activate
+     */
+    resolveActiveLocale(requested: LocaleCode): LocaleCode;
+    /**
+     * Sets the active locale and triggers a re-render so UI strings update.
+     *
+     * @param code - The locale code to activate
+     */
+    setLocale(code: LocaleCode): void;
+    /**
+     * Gets the list of available locale codes. When a locale catalog was
+     * explicitly configured via {@link configureLocales}, only those codes are
+     * returned (or `[DEFAULT_LOCALE]` if the catalog is empty); otherwise the
+     * built-in and registered codes are combined.
+     */
+    getAvailableLocales(): LocaleCode[];
+    /**
+     * Gets the available locales as `{ code, label }` pairs for use in a selector.
+     * A registered locale's label takes precedence over the built-in label; the
+     * code is used as the label when none is provided.
+     */
+    getAvailableLocaleOptions(): {
+        code: LocaleCode;
+        label: string;
+    }[];
+    /**
+     * Gets the display label for a locale code, falling back to the code itself.
+     *
+     * @param code - The locale code
+     */
+    getLocaleLabel(code: LocaleCode): string;
+    /**
+     * Resolves a term key to its translated string for the active locale and
+     * interpolates any `{placeholder}` tokens.
+     *
+     * @param key - The term key to resolve
+     * @param vars - Optional values for `{placeholder}` interpolation
+     * @returns The translated, interpolated string (or the key if unresolved)
+     *
+     * @example
+     * manager.translate('menu.copy'); // 'Copy'
+     * manager.translate('share.expires', { date: '5/1' }); // 'Expires 5/1'
+     */
+    translate(key: KritzelTermKey, vars?: KritzelTermVars): string;
+    /**
+     * Resolves every known term key for the active locale into a flat map.
+     *
+     * The key set is the union of all keys defined across the built-in and
+     * registered locales, so consumer-added keys are included. Each value is
+     * resolved through the same fallback chain as {@link translate} (without
+     * interpolation, since these are shared, variable-free UI labels).
+     *
+     * @returns A map of every term key to its resolved string for the active locale
+     */
+    getAllTerms(): Partial<Record<KritzelTermKey, string>>;
+    /**
+     * Reads the stored locale from the settings object in localStorage using this
+     * instance's namespaced key.
+     *
+     * @returns The stored locale code if valid, or the default locale
+     */
+    getStoredLocale(): LocaleCode;
+    /**
+     * Cleans up the localization manager state.
+     * Provided for lifecycle parity with other managers.
+     */
+    cleanup(): void;
+}

package/dist/types/classes/managers/theme.manager.d.ts

@@ -0,0 +1,112 @@
+import { KritzelTheme, ThemeName } from '../../interfaces/theme.interface';
+import { KritzelCore } from '../core/core.class';
+/**
+ * Manages theme state and application across the Kritzel editor.
+ * Reads the persisted theme from the settings object in localStorage but does not write to it.
+ * Persistence is handled exclusively by the KritzelSettings component.
+ *
+ * The theme manager is responsible for:
+ * - Reading the stored theme preference from the settings object
+ * - Applying CSS custom properties to target elements
+ * - Switching between light and dark themes at runtime
+ */
+export declare class KritzelThemeManager {
+    private readonly _core;
+    private _currentTheme;
+    private _targetElement;
+    private readonly _storageKey;
+    private _themeRegistry;
+    /**
+     * Creates a new KritzelThemeManager instance.
+     * Initializes the current theme from the settings object in localStorage or uses the default theme.
+     *
+     * @param core - The KritzelCore instance this manager belongs to
+     */
+    constructor(core: KritzelCore);
+    /**
+     * Gets the current active theme name.
+     *
+     * @returns The name of the currently active theme ('light' or 'dark')
+     */
+    get currentTheme(): ThemeName;
+    /**
+     * Sets the target element where theme CSS variables will be applied.
+     * If an element is provided, the current theme is immediately applied to it.
+     *
+     * @param element - The HTML element to apply theme styles to, or null to clear
+     */
+    setTargetElement(element: HTMLElement | null): void;
+    /**
+     * Gets the current target element where theme CSS variables are applied.
+     *
+     * @returns The current target HTML element, or null if none is set
+     */
+    getTargetElement(): HTMLElement | null;
+    /**
+     * Gets the theme configuration object by its name.
+     * Falls back to the first registered theme if the requested name is not found.
+     *
+     * @param themeName - The name of the theme to retrieve
+     * @returns The KritzelTheme object containing all theme CSS variable values
+     */
+    getThemeByName(themeName: ThemeName): KritzelTheme;
+    /**
+     * Registers the provided themes to this theme manager instance.
+     *
+     * @param themes - The complete list of themes to make available
+     */
+    registerThemes(themes: KritzelTheme[]): void;
+    /**
+     * Pre-emptively applies the stored theme's CSS variables to the closest editor or document.
+     * This prevents a "Flash of Unstyled Content" (FOUC) while Stencil web components are hydrating.
+     *
+     * @param element - The HTML element to apply the theme to
+     */
+    injectThemeEarly(element?: HTMLElement): void;
+    /**
+     * Gets all registered themes.
+     *
+     * @returns An array of all registered theme objects
+     */
+    getAllThemes(): KritzelTheme[];
+    /**
+     * Gets the stored theme name from the settings object in localStorage using this instance's namespaced key.
+     *
+     * @returns The stored theme name if valid, or 'light' as the default
+     */
+    getStoredTheme(): ThemeName;
+    /**
+     * Gets the stored theme from the default (non-namespaced) settings object in localStorage.
+     * Used by static utility helpers that don't have access to a core instance.
+     *
+     * @returns The stored theme name if valid, or 'light' as the default
+     */
+    static getStoredTheme(): ThemeName;
+    /**
+     * Sets the current theme and applies it to the target element.
+     * Does not persist the theme — persistence is handled by the KritzelSettings component.
+     *
+     * @param themeName - The theme name to set ('light' or 'dark')
+     */
+    setTheme(themeName: ThemeName): void;
+    /**
+     * Checks if the current theme is the dark theme.
+     *
+     * @returns True if the current theme is 'dark', false otherwise
+     */
+    isDarkTheme(): boolean;
+    /**
+     * Applies a theme to the target element by setting CSS custom properties.
+     * Uses the ThemeHelper utility to automatically derive CSS variable names
+     * from the theme interface structure and apply them to the element's style.
+     * Does nothing if no target element is set.
+     *
+     * @param themeName - The name of the theme to apply ('light' or 'dark')
+     */
+    applyTheme(themeName: ThemeName): void;
+    /**
+     * Cleans up the theme manager state by clearing the target element reference.
+     * Should be called when the manager is no longer needed to prevent memory leaks.
+     */
+    cleanup(): void;
+}