@aicut/core 0.1.1 → 0.2.0

package/dist/lighting/index.d.cts

@@ -0,0 +1,193 @@
+import { b as Theme, L as Locale } from '../types-C95koNwJ.cjs';
+
+/**
+ * Lighting-editor-specific string keys. Kept in a SEPARATE interface
+ * from the video editor's `Locale` so the timeline-only consumer's
+ * type doesn't grow unused fields, but exported so a single host
+ * locale object can spread both shapes together.
+ */
+interface LightingLocale {
+    lightingGlobalTitle: string;
+    lightingSmartMode: string;
+    lightingBrightness: string;
+    lightingColor: string;
+    lightingKeyTitle: string;
+    lightingRim: string;
+    lightingViewPerspective: string;
+    lightingViewFront: string;
+    lightingResetParams: string;
+    /** Aria label / tooltip for the × button that closes the Smart panel. */
+    lightingSmartClose: string;
+    /** Tooltip / label for the controls-header Smart Mode toggle. */
+    lightingSmartToggle: string;
+    lightingDirLeft: string;
+    lightingDirRight: string;
+    lightingDirTop: string;
+    lightingDirBottom: string;
+    lightingDirFront: string;
+    lightingDirBack: string;
+}
+declare const lightingLocaleEn: LightingLocale;
+declare const lightingLocaleZh: LightingLocale;
+declare function mergeLightingLocale(partial: Partial<LightingLocale> | undefined): LightingLocale;
+
+/** One of the six canonical key-light directions plus a sentinel for free-drag. */
+type KeyPreset = "left" | "right" | "top" | "bottom" | "front" | "back" | "custom";
+/** Snapshot of every adjustable lighting parameter — what `onChange` emits. */
+interface LightingConfig {
+    /** 0–1 multiplier. Snapped to 5 UI levels (0 / 0.25 / 0.5 / 0.75 / 1). */
+    brightness: number;
+    /** Hex RGB string, e.g. "#ffffff". */
+    color: string;
+    /**
+     * Unit vector from the subject toward the light. `(0,0,1)` = light in
+     * front of the subject, `(0,1,0)` = light directly overhead, etc.
+     * Always renormalised on write.
+     */
+    keyDirection: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Which canonical direction the dot is closest to, or `"custom"`. */
+    keyPreset: KeyPreset;
+    /** Rim / contour light toggle. */
+    rim: boolean;
+}
+type LightingView = "perspective" | "front";
+interface LightingEditorOptions {
+    /** Host element. Will be wiped on init. */
+    container: HTMLElement;
+    /**
+     * Image URL or data URI shown on the in-sphere plane (the "subject"
+     * being lit). Can be swapped at runtime via `setSubjectImage`.
+     */
+    subjectImageUrl?: string;
+    /** Initial config — merges over the safe defaults below. */
+    config?: Partial<LightingConfig>;
+    /** Initial camera view. Default `"perspective"`. */
+    view?: LightingView;
+    /**
+     * Whether the Smart Mode feature is wired in at all. When false the
+     * slot column never renders and the controls header hides the
+     * Smart Mode toggle — the layout becomes a clean 2-column
+     * (scene + controls). Default `true`.
+     */
+    smartEnabled?: boolean;
+    /**
+     * When `smartEnabled` is true, whether the Smart Mode slot panel
+     * starts open. Hosts toggle later via `api.setSmartOpen(bool)` or
+     * by clicking the library-rendered × button. Default `true`.
+     */
+    smartOpen?: boolean;
+    /** Theme tokens — same shape as the video Editor's theme. */
+    theme?: Theme;
+    /** Locale overrides on top of English defaults (`localeEn` + `lightingLocaleEn`). */
+    locale?: Partial<Locale & LightingLocale>;
+    /** Fires on any config mutation (drag, slider, preset click, toggle). */
+    onChange?: (cfg: LightingConfig) => void;
+    /**
+     * Surface event for the host's own "Generate" button — the library
+     * never wires this. Use `api.requestGenerate()` from your UI.
+     */
+    onGenerate?: (cfg: LightingConfig) => void;
+    /** Fires when the user toggles the Smart Mode panel via × / toggle. */
+    onSmartOpenChange?: (open: boolean) => void;
+}
+/** Safe, conservative defaults for first mount. */
+declare const DEFAULT_LIGHTING_CONFIG: LightingConfig;
+
+/**
+ * Top-level lighting picker. Mirrors `Editor`'s lifecycle — `static
+ * create(opts)`, wipes the container, owns DOM + WebGL, exposes
+ * `destroy()` and reactive `setTheme` / `setLocale`. Separate from
+ * the video Editor; the two can coexist in the same host page.
+ *
+ * Layout (left → right):
+ *   [scene 240px]  [controls 220px]  [smartSlot (drawer)]
+ * The smart slot is host-supplied. Library renders a × close button
+ * + a "Smart mode" toggle in the controls header when the slot is
+ * available; `smartEnabled: false` removes the slot entirely.
+ */
+declare class LightingEditor {
+    private root;
+    private opts;
+    private config;
+    private view;
+    private locale;
+    private smartEnabled;
+    private smartOpen;
+    private scene;
+    private controls;
+    private sceneViewport;
+    private viewToggleEl;
+    private body;
+    private smartWrapper;
+    private smartCloseBtn;
+    private smartToggleEl;
+    private smartToggleThumb;
+    /** Host slot the React/Vue wrapper portals/teleports into. Stable
+     *  reference across smartOpen toggles — only the wrapper around it
+     *  collapses/expands. Always present even when `smartEnabled: false`
+     *  so portals don't blow up; just detached from the visible tree. */
+    readonly smartSlot: HTMLDivElement;
+    private resizeObs;
+    private destroyed;
+    static create(opts: LightingEditorOptions): LightingEditor;
+    constructor(opts: LightingEditorOptions);
+    getConfig(): LightingConfig;
+    setConfig(partial: Partial<LightingConfig>, _reason?: "external" | "reset"): void;
+    setSubjectImage(url: string): void;
+    setView(v: LightingView): void;
+    getView(): LightingView;
+    /** Enable/disable the entire Smart Mode feature at runtime. */
+    setSmartEnabled(enabled: boolean): void;
+    isSmartEnabled(): boolean;
+    /** Open/close the smart slot drawer when enabled. No-op when disabled. */
+    setSmartOpen(open: boolean): void;
+    isSmartOpen(): boolean;
+    setTheme(theme: Theme): void;
+    setLocale(locale: Partial<Locale & LightingLocale>): void;
+    requestGenerate(): void;
+    destroy(): void;
+    private applyMutation;
+    private buildViewToggle;
+    private syncViewToggle;
+    /**
+     * Build the smart slot column wrapper: × close button + the actual
+     * host slot. Wrapper handles the drawer animation; slot reference
+     * stays stable so portals don't have to relocate.
+     */
+    private buildSmartWrapper;
+    /** Pill-style toggle that lives in the controls header. Re-opens
+     *  the smart drawer when the host has closed it via ×. */
+    private buildSmartToggle;
+    /** Re-translate smart-related labels after a locale swap. */
+    private syncSmartLocale;
+    /** Mirror smart state to data-* attrs + toggle thumb position.
+     *  Drives the CSS that collapses the column when closed. */
+    private syncSmartState;
+}
+
+/**
+ * Canonical key-light direction unit vectors. Coordinate space matches
+ * three.js's defaults — +X right, +Y up, +Z toward the camera. So
+ * `front: (0, 0, 1)` means "light positioned between the camera and
+ * the subject," which is the most flattering portrait default.
+ */
+declare const PRESET_DIRECTIONS: Record<Exclude<KeyPreset, "custom">, {
+    x: number;
+    y: number;
+    z: number;
+}>;
+/**
+ * Decide which preset (if any) a given unit-vector direction snaps to.
+ * Returns `"custom"` when no preset is within `PRESET_SNAP_RADIANS`.
+ */
+declare function snapToPreset(d: {
+    x: number;
+    y: number;
+    z: number;
+}): KeyPreset;
+
+export { DEFAULT_LIGHTING_CONFIG, type KeyPreset, type LightingConfig, LightingEditor, type LightingEditorOptions, type LightingLocale, type LightingView, PRESET_DIRECTIONS, lightingLocaleEn, lightingLocaleZh, mergeLightingLocale, snapToPreset };

package/dist/lighting/index.d.ts

@@ -0,0 +1,193 @@
+import { b as Theme, L as Locale } from '../types-C95koNwJ.js';
+
+/**
+ * Lighting-editor-specific string keys. Kept in a SEPARATE interface
+ * from the video editor's `Locale` so the timeline-only consumer's
+ * type doesn't grow unused fields, but exported so a single host
+ * locale object can spread both shapes together.
+ */
+interface LightingLocale {
+    lightingGlobalTitle: string;
+    lightingSmartMode: string;
+    lightingBrightness: string;
+    lightingColor: string;
+    lightingKeyTitle: string;
+    lightingRim: string;
+    lightingViewPerspective: string;
+    lightingViewFront: string;
+    lightingResetParams: string;
+    /** Aria label / tooltip for the × button that closes the Smart panel. */
+    lightingSmartClose: string;
+    /** Tooltip / label for the controls-header Smart Mode toggle. */
+    lightingSmartToggle: string;
+    lightingDirLeft: string;
+    lightingDirRight: string;
+    lightingDirTop: string;
+    lightingDirBottom: string;
+    lightingDirFront: string;
+    lightingDirBack: string;
+}
+declare const lightingLocaleEn: LightingLocale;
+declare const lightingLocaleZh: LightingLocale;
+declare function mergeLightingLocale(partial: Partial<LightingLocale> | undefined): LightingLocale;
+
+/** One of the six canonical key-light directions plus a sentinel for free-drag. */
+type KeyPreset = "left" | "right" | "top" | "bottom" | "front" | "back" | "custom";
+/** Snapshot of every adjustable lighting parameter — what `onChange` emits. */
+interface LightingConfig {
+    /** 0–1 multiplier. Snapped to 5 UI levels (0 / 0.25 / 0.5 / 0.75 / 1). */
+    brightness: number;
+    /** Hex RGB string, e.g. "#ffffff". */
+    color: string;
+    /**
+     * Unit vector from the subject toward the light. `(0,0,1)` = light in
+     * front of the subject, `(0,1,0)` = light directly overhead, etc.
+     * Always renormalised on write.
+     */
+    keyDirection: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** Which canonical direction the dot is closest to, or `"custom"`. */
+    keyPreset: KeyPreset;
+    /** Rim / contour light toggle. */
+    rim: boolean;
+}
+type LightingView = "perspective" | "front";
+interface LightingEditorOptions {
+    /** Host element. Will be wiped on init. */
+    container: HTMLElement;
+    /**
+     * Image URL or data URI shown on the in-sphere plane (the "subject"
+     * being lit). Can be swapped at runtime via `setSubjectImage`.
+     */
+    subjectImageUrl?: string;
+    /** Initial config — merges over the safe defaults below. */
+    config?: Partial<LightingConfig>;
+    /** Initial camera view. Default `"perspective"`. */
+    view?: LightingView;
+    /**
+     * Whether the Smart Mode feature is wired in at all. When false the
+     * slot column never renders and the controls header hides the
+     * Smart Mode toggle — the layout becomes a clean 2-column
+     * (scene + controls). Default `true`.
+     */
+    smartEnabled?: boolean;
+    /**
+     * When `smartEnabled` is true, whether the Smart Mode slot panel
+     * starts open. Hosts toggle later via `api.setSmartOpen(bool)` or
+     * by clicking the library-rendered × button. Default `true`.
+     */
+    smartOpen?: boolean;
+    /** Theme tokens — same shape as the video Editor's theme. */
+    theme?: Theme;
+    /** Locale overrides on top of English defaults (`localeEn` + `lightingLocaleEn`). */
+    locale?: Partial<Locale & LightingLocale>;
+    /** Fires on any config mutation (drag, slider, preset click, toggle). */
+    onChange?: (cfg: LightingConfig) => void;
+    /**
+     * Surface event for the host's own "Generate" button — the library
+     * never wires this. Use `api.requestGenerate()` from your UI.
+     */
+    onGenerate?: (cfg: LightingConfig) => void;
+    /** Fires when the user toggles the Smart Mode panel via × / toggle. */
+    onSmartOpenChange?: (open: boolean) => void;
+}
+/** Safe, conservative defaults for first mount. */
+declare const DEFAULT_LIGHTING_CONFIG: LightingConfig;
+
+/**
+ * Top-level lighting picker. Mirrors `Editor`'s lifecycle — `static
+ * create(opts)`, wipes the container, owns DOM + WebGL, exposes
+ * `destroy()` and reactive `setTheme` / `setLocale`. Separate from
+ * the video Editor; the two can coexist in the same host page.
+ *
+ * Layout (left → right):
+ *   [scene 240px]  [controls 220px]  [smartSlot (drawer)]
+ * The smart slot is host-supplied. Library renders a × close button
+ * + a "Smart mode" toggle in the controls header when the slot is
+ * available; `smartEnabled: false` removes the slot entirely.
+ */
+declare class LightingEditor {
+    private root;
+    private opts;
+    private config;
+    private view;
+    private locale;
+    private smartEnabled;
+    private smartOpen;
+    private scene;
+    private controls;
+    private sceneViewport;
+    private viewToggleEl;
+    private body;
+    private smartWrapper;
+    private smartCloseBtn;
+    private smartToggleEl;
+    private smartToggleThumb;
+    /** Host slot the React/Vue wrapper portals/teleports into. Stable
+     *  reference across smartOpen toggles — only the wrapper around it
+     *  collapses/expands. Always present even when `smartEnabled: false`
+     *  so portals don't blow up; just detached from the visible tree. */
+    readonly smartSlot: HTMLDivElement;
+    private resizeObs;
+    private destroyed;
+    static create(opts: LightingEditorOptions): LightingEditor;
+    constructor(opts: LightingEditorOptions);
+    getConfig(): LightingConfig;
+    setConfig(partial: Partial<LightingConfig>, _reason?: "external" | "reset"): void;
+    setSubjectImage(url: string): void;
+    setView(v: LightingView): void;
+    getView(): LightingView;
+    /** Enable/disable the entire Smart Mode feature at runtime. */
+    setSmartEnabled(enabled: boolean): void;
+    isSmartEnabled(): boolean;
+    /** Open/close the smart slot drawer when enabled. No-op when disabled. */
+    setSmartOpen(open: boolean): void;
+    isSmartOpen(): boolean;
+    setTheme(theme: Theme): void;
+    setLocale(locale: Partial<Locale & LightingLocale>): void;
+    requestGenerate(): void;
+    destroy(): void;
+    private applyMutation;
+    private buildViewToggle;
+    private syncViewToggle;
+    /**
+     * Build the smart slot column wrapper: × close button + the actual
+     * host slot. Wrapper handles the drawer animation; slot reference
+     * stays stable so portals don't have to relocate.
+     */
+    private buildSmartWrapper;
+    /** Pill-style toggle that lives in the controls header. Re-opens
+     *  the smart drawer when the host has closed it via ×. */
+    private buildSmartToggle;
+    /** Re-translate smart-related labels after a locale swap. */
+    private syncSmartLocale;
+    /** Mirror smart state to data-* attrs + toggle thumb position.
+     *  Drives the CSS that collapses the column when closed. */
+    private syncSmartState;
+}
+
+/**
+ * Canonical key-light direction unit vectors. Coordinate space matches
+ * three.js's defaults — +X right, +Y up, +Z toward the camera. So
+ * `front: (0, 0, 1)` means "light positioned between the camera and
+ * the subject," which is the most flattering portrait default.
+ */
+declare const PRESET_DIRECTIONS: Record<Exclude<KeyPreset, "custom">, {
+    x: number;
+    y: number;
+    z: number;
+}>;
+/**
+ * Decide which preset (if any) a given unit-vector direction snaps to.
+ * Returns `"custom"` when no preset is within `PRESET_SNAP_RADIANS`.
+ */
+declare function snapToPreset(d: {
+    x: number;
+    y: number;
+    z: number;
+}): KeyPreset;
+
+export { DEFAULT_LIGHTING_CONFIG, type KeyPreset, type LightingConfig, LightingEditor, type LightingEditorOptions, type LightingLocale, type LightingView, PRESET_DIRECTIONS, lightingLocaleEn, lightingLocaleZh, mergeLightingLocale, snapToPreset };