@aicut/react 0.3.0 → 0.4.1

package/README.md

@@ -160,32 +160,41 @@ import "@aicut/core/styles.css";
 
 function Relight() {
   const apiRef = useRef<LightingEditorApi | null>(null);
+
+  const onGenerate = (): void => {
+    const cfg = apiRef.current?.getConfig();
+    if (cfg) fetch("/relight", { method: "POST", body: JSON.stringify(cfg) });
+  };
+
+  // Library renders ONLY the picker (scene + controls). Host lays out
+  // the Smart mode panel beside it in their own flex/grid.
   return (
-    <LightingEditor
-      apiRef={apiRef}
-      subjectImageUrl="/frames/subject.jpg"
-      smartEnabled
-      smartPanel={
-        <>
-          <textarea placeholder="Describe the mood…" />
-          <button onClick={() => apiRef.current?.requestGenerate()}>
-            Generate
-          </button>
-        </>
-      }
-      onChange={(cfg: LightingConfig) => console.log(cfg)}
-      onGenerate={(cfg) =>
-        fetch("/relight", {
-          method: "POST",
-          body: JSON.stringify(cfg),
-        })
-      }
-    />
+    <div style={{ display: "flex", gap: 16 }}>
+      <LightingEditor
+        apiRef={apiRef}
+        subjectImageUrl="/frames/subject.jpg"
+        onChange={(cfg: LightingConfig) => console.log(cfg)}
+        // Reset / Generate / save-preset / etc. buttons go into the
+        // controls column's footer slot — the only host-supplied
+        // surface the library reserves space for.
+        controlsFooter={
+          <button onClick={() => apiRef.current?.reset()}>Reset</button>
+        }
+      />
+      <aside>
+        <textarea placeholder="Describe the mood…" />
+        <button onClick={onGenerate}>Generate</button>
+      </aside>
+    </div>
   );
 }
 ```
 
-Props: `subjectImageUrl`, `defaultConfig`, `defaultView`, `theme`, `locale`, `smartEnabled`, `smartOpen`, `smartPanel`, `onChange`, `onGenerate`, `onSmartOpenChange`. The host's `smartPanel` is portaled into the editor's slot; the library renders the × close button + a "Smart mode" header pill to re-open it.
+Props: `subjectImageUrl`, `defaultConfig`, `defaultView`, `theme`, `locale`, `controlsFooter`, `onChange`.
+
+Imperative API (`apiRef.current`): `setConfig`, `getConfig`, `setSubjectImage`, `setView`, `getView`, `reset`.
+
+The library is intentionally focused on the picker — Smart mode UI, Generate buttons, close handling, layout all live in host code.
 
 ## Standalone `<Timeline>`
 

package/dist/lighting.cjs

@@ -32,12 +32,13 @@ module.exports = __toCommonJS(lighting_exports);
 
 // src/LightingEditor.tsx
 var import_react = require("react");
+var import_react_dom = require("react-dom");
 var import_lighting = require("@aicut/core/lighting");
 var import_jsx_runtime = require("react/jsx-runtime");
 function LightingEditor(props) {
   const hostRef = (0, import_react.useRef)(null);
   const editorRef = (0, import_react.useRef)(null);
-  const [ready, setReady] = (0, import_react.useState)(false);
+  const [footerSlot, setFooterSlot] = (0, import_react.useState)(null);
   const cbRef = (0, import_react.useRef)(props);
   cbRef.current = props;
   (0, import_react.useEffect)(() => {
@@ -53,11 +54,11 @@ function LightingEditor(props) {
       onChange: (cfg) => cbRef.current.onChange?.(cfg)
     });
     editorRef.current = editor;
-    setReady(true);
+    setFooterSlot(editor.controlsFooter);
     return () => {
       editor.destroy();
       editorRef.current = null;
-      setReady(false);
+      setFooterSlot(null);
     };
   }, []);
   (0, import_react.useEffect)(() => {
@@ -80,10 +81,12 @@ function LightingEditor(props) {
         getConfig: () => ed.getConfig(),
         setSubjectImage: (url) => ed.setSubjectImage(url),
         setView: (v) => ed.setView(v),
-        getView: () => ed.getView()
+        getView: () => ed.getView(),
+        reset: () => ed.reset()
       };
     },
-    [ready]
+    // Keyed on footerSlot — same null-lock fix the VideoEditor uses.
+    [footerSlot]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     "div",
@@ -91,7 +94,8 @@ function LightingEditor(props) {
       ref: hostRef,
       className: props.className,
       style: props.style,
-      "data-aicut-lighting-host": ""
+      "data-aicut-lighting-host": "",
+      children: footerSlot && props.controlsFooter != null ? (0, import_react_dom.createPortal)(props.controlsFooter, footerSlot) : null
     }
   );
 }

package/dist/lighting.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/lighting.ts","../src/LightingEditor.tsx"],"sourcesContent":["/**\n * @aicut/react/lighting — separate entry that pulls three.js. Users\n * who never import this path don't pay the three.js bundle cost.\n */\nexport { LightingEditor } from \"./LightingEditor.js\";\nexport type {\n  LightingEditorProps,\n  LightingEditorApi,\n} from \"./LightingEditor.js\";\n\n// Re-export the data + locale exports from the core sub-entry so\n// hosts only need a single import line for everything lighting-related.\nexport {\n  DEFAULT_LIGHTING_CONFIG,\n  PRESET_DIRECTIONS,\n  lightingLocaleEn,\n  lightingLocaleZh,\n  mergeLightingLocale,\n  snapToPreset,\n} from \"@aicut/core/lighting\";\nexport type {\n  KeyPreset,\n  LightingConfig,\n  LightingEditorOptions,\n  LightingLocale,\n  LightingView,\n} from \"@aicut/core/lighting\";\n","import {\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type Ref,\n} from \"react\";\nimport {\n  LightingEditor as CoreLightingEditor,\n  type LightingConfig,\n  type LightingEditorOptions,\n  type LightingView,\n} from \"@aicut/core/lighting\";\nimport type { Theme } from \"@aicut/core\";\n\nexport interface LightingEditorApi {\n  setConfig(partial: Partial<LightingConfig>): void;\n  getConfig(): LightingConfig;\n  setSubjectImage(url: string): void;\n  setView(v: LightingView): void;\n  getView(): LightingView;\n}\n\nexport interface LightingEditorProps {\n  /** Initial subject image (URL or data URI). Reactive. */\n  subjectImageUrl?: string;\n  /** Initial config. */\n  defaultConfig?: Partial<LightingConfig>;\n  /** Initial view. Default `\"perspective\"`. */\n  defaultView?: LightingView;\n  /** Theme — reactive (calls editor.setTheme). */\n  theme?: Theme;\n  /** Locale partial — reactive (calls editor.setLocale). */\n  locale?: LightingEditorOptions[\"locale\"];\n\n  className?: string;\n  style?: CSSProperties;\n  apiRef?: Ref<LightingEditorApi | null>;\n\n  onChange?: (cfg: LightingConfig) => void;\n}\n\n/**\n * React shell for the 3D lighting picker. Renders scene + controls;\n * nothing else. Host code lays out their own surrounding UI (smart\n * mode panel, generate button, etc.) alongside this component in\n * whatever flex/grid the host prefers.\n */\nexport function LightingEditor(props: LightingEditorProps) {\n  const hostRef = useRef<HTMLDivElement | null>(null);\n  const editorRef = useRef<CoreLightingEditor | null>(null);\n  // Triggers a re-render the moment the editor is created, so the\n  // useImperativeHandle factory below can return the real instance\n  // instead of locking at null forever (same trick as VideoEditor).\n  const [ready, setReady] = useState(false);\n\n  const cbRef = useRef(props);\n  cbRef.current = props;\n\n  useEffect(() => {\n    const host = hostRef.current;\n    if (!host) return;\n    const editor = CoreLightingEditor.create({\n      container: host,\n      subjectImageUrl: cbRef.current.subjectImageUrl,\n      config: cbRef.current.defaultConfig,\n      view: cbRef.current.defaultView,\n      theme: cbRef.current.theme,\n      locale: cbRef.current.locale,\n      onChange: (cfg) => cbRef.current.onChange?.(cfg),\n    });\n    editorRef.current = editor;\n    setReady(true);\n    return () => {\n      editor.destroy();\n      editorRef.current = null;\n      setReady(false);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  useEffect(() => {\n    if (props.theme) editorRef.current?.setTheme(props.theme);\n  }, [props.theme]);\n  useEffect(() => {\n    // Always push — `undefined` is the \"reset to English defaults\"\n    // signal. Without this, toggling ZH→EN in the host kept ZH labels.\n    editorRef.current?.setLocale(props.locale ?? {});\n  }, [props.locale]);\n  useEffect(() => {\n    if (props.subjectImageUrl)\n      editorRef.current?.setSubjectImage(props.subjectImageUrl);\n  }, [props.subjectImageUrl]);\n\n  useImperativeHandle<LightingEditorApi | null, LightingEditorApi | null>(\n    props.apiRef,\n    () => {\n      const ed = editorRef.current;\n      if (!ed) return null;\n      return {\n        setConfig: (p) => ed.setConfig(p),\n        getConfig: () => ed.getConfig(),\n        setSubjectImage: (url) => ed.setSubjectImage(url),\n        setView: (v) => ed.setView(v),\n        getView: () => ed.getView(),\n      };\n    },\n    [ready],\n  );\n\n  return (\n    <div\n      ref={hostRef}\n      className={props.className}\n      style={props.style}\n      data-aicut-lighting-host=\"\"\n    />\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAOO;AACP,sBAKO;AAmGH;AA/DG,SAAS,eAAe,OAA4B;AACzD,QAAM,cAAU,qBAA8B,IAAI;AAClD,QAAM,gBAAY,qBAAkC,IAAI;AAIxD,QAAM,CAAC,OAAO,QAAQ,QAAI,uBAAS,KAAK;AAExC,QAAM,YAAQ,qBAAO,KAAK;AAC1B,QAAM,UAAU;AAEhB,8BAAU,MAAM;AACd,UAAM,OAAO,QAAQ;AACrB,QAAI,CAAC,KAAM;AACX,UAAM,SAAS,gBAAAA,eAAmB,OAAO;AAAA,MACvC,WAAW;AAAA,MACX,iBAAiB,MAAM,QAAQ;AAAA,MAC/B,QAAQ,MAAM,QAAQ;AAAA,MACtB,MAAM,MAAM,QAAQ;AAAA,MACpB,OAAO,MAAM,QAAQ;AAAA,MACrB,QAAQ,MAAM,QAAQ;AAAA,MACtB,UAAU,CAAC,QAAQ,MAAM,QAAQ,WAAW,GAAG;AAAA,IACjD,CAAC;AACD,cAAU,UAAU;AACpB,aAAS,IAAI;AACb,WAAO,MAAM;AACX,aAAO,QAAQ;AACf,gBAAU,UAAU;AACpB,eAAS,KAAK;AAAA,IAChB;AAAA,EAEF,GAAG,CAAC,CAAC;AAEL,8BAAU,MAAM;AACd,QAAI,MAAM,MAAO,WAAU,SAAS,SAAS,MAAM,KAAK;AAAA,EAC1D,GAAG,CAAC,MAAM,KAAK,CAAC;AAChB,8BAAU,MAAM;AAGd,cAAU,SAAS,UAAU,MAAM,UAAU,CAAC,CAAC;AAAA,EACjD,GAAG,CAAC,MAAM,MAAM,CAAC;AACjB,8BAAU,MAAM;AACd,QAAI,MAAM;AACR,gBAAU,SAAS,gBAAgB,MAAM,eAAe;AAAA,EAC5D,GAAG,CAAC,MAAM,eAAe,CAAC;AAE1B;AAAA,IACE,MAAM;AAAA,IACN,MAAM;AACJ,YAAM,KAAK,UAAU;AACrB,UAAI,CAAC,GAAI,QAAO;AAChB,aAAO;AAAA,QACL,WAAW,CAAC,MAAM,GAAG,UAAU,CAAC;AAAA,QAChC,WAAW,MAAM,GAAG,UAAU;AAAA,QAC9B,iBAAiB,CAAC,QAAQ,GAAG,gBAAgB,GAAG;AAAA,QAChD,SAAS,CAAC,MAAM,GAAG,QAAQ,CAAC;AAAA,QAC5B,SAAS,MAAM,GAAG,QAAQ;AAAA,MAC5B;AAAA,IACF;AAAA,IACA,CAAC,KAAK;AAAA,EACR;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,KAAK;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,OAAO,MAAM;AAAA,MACb,4BAAyB;AAAA;AAAA,EAC3B;AAEJ;;;AD3GA,IAAAC,mBAOO;","names":["CoreLightingEditor","import_lighting"]}
+{"version":3,"sources":["../src/lighting.ts","../src/LightingEditor.tsx"],"sourcesContent":["/**\n * @aicut/react/lighting — separate entry that pulls three.js. Users\n * who never import this path don't pay the three.js bundle cost.\n */\nexport { LightingEditor } from \"./LightingEditor.js\";\nexport type {\n  LightingEditorProps,\n  LightingEditorApi,\n} from \"./LightingEditor.js\";\n\n// Re-export the data + locale exports from the core sub-entry so\n// hosts only need a single import line for everything lighting-related.\nexport {\n  DEFAULT_LIGHTING_CONFIG,\n  PRESET_DIRECTIONS,\n  lightingLocaleEn,\n  lightingLocaleZh,\n  mergeLightingLocale,\n  snapToPreset,\n} from \"@aicut/core/lighting\";\nexport type {\n  KeyPreset,\n  LightingConfig,\n  LightingEditorOptions,\n  LightingLocale,\n  LightingView,\n} from \"@aicut/core/lighting\";\n","import {\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ReactNode,\n  type Ref,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport {\n  LightingEditor as CoreLightingEditor,\n  type LightingConfig,\n  type LightingEditorOptions,\n  type LightingView,\n} from \"@aicut/core/lighting\";\nimport type { Theme } from \"@aicut/core\";\n\nexport interface LightingEditorApi {\n  setConfig(partial: Partial<LightingConfig>): void;\n  getConfig(): LightingConfig;\n  setSubjectImage(url: string): void;\n  setView(v: LightingView): void;\n  getView(): LightingView;\n  /** Convenience — restores config to safe defaults. */\n  reset(): void;\n}\n\nexport interface LightingEditorProps {\n  /** Initial subject image (URL or data URI). Reactive. */\n  subjectImageUrl?: string;\n  /** Initial config. */\n  defaultConfig?: Partial<LightingConfig>;\n  /** Initial view. Default `\"perspective\"`. */\n  defaultView?: LightingView;\n  /** Theme — reactive (calls editor.setTheme). */\n  theme?: Theme;\n  /** Locale partial — reactive (calls editor.setLocale). */\n  locale?: LightingEditorOptions[\"locale\"];\n\n  /**\n   * Any React node — portaled into the editor's controls footer slot\n   * (where the built-in Reset button used to live). Hosts put their\n   * Reset / Generate / save-preset / etc. buttons here. Empty until\n   * populated; the library renders nothing into the slot.\n   */\n  controlsFooter?: ReactNode;\n\n  className?: string;\n  style?: CSSProperties;\n  apiRef?: Ref<LightingEditorApi | null>;\n\n  onChange?: (cfg: LightingConfig) => void;\n}\n\n/**\n * React shell for the 3D lighting picker. Renders scene + controls;\n * the host owns everything else (smart panel beside, action buttons\n * in the controlsFooter slot, layout, theming the surrounding page).\n */\nexport function LightingEditor(props: LightingEditorProps) {\n  const hostRef = useRef<HTMLDivElement | null>(null);\n  const editorRef = useRef<CoreLightingEditor | null>(null);\n  // Hold the footer slot DOM node in state so the portal mounts after\n  // editor creation. Same lifecycle dance VideoEditor does for its\n  // toolbar slots.\n  const [footerSlot, setFooterSlot] = useState<HTMLElement | null>(null);\n\n  const cbRef = useRef(props);\n  cbRef.current = props;\n\n  useEffect(() => {\n    const host = hostRef.current;\n    if (!host) return;\n    const editor = CoreLightingEditor.create({\n      container: host,\n      subjectImageUrl: cbRef.current.subjectImageUrl,\n      config: cbRef.current.defaultConfig,\n      view: cbRef.current.defaultView,\n      theme: cbRef.current.theme,\n      locale: cbRef.current.locale,\n      onChange: (cfg) => cbRef.current.onChange?.(cfg),\n    });\n    editorRef.current = editor;\n    setFooterSlot(editor.controlsFooter);\n    return () => {\n      editor.destroy();\n      editorRef.current = null;\n      setFooterSlot(null);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  useEffect(() => {\n    if (props.theme) editorRef.current?.setTheme(props.theme);\n  }, [props.theme]);\n  useEffect(() => {\n    editorRef.current?.setLocale(props.locale ?? {});\n  }, [props.locale]);\n  useEffect(() => {\n    if (props.subjectImageUrl)\n      editorRef.current?.setSubjectImage(props.subjectImageUrl);\n  }, [props.subjectImageUrl]);\n\n  useImperativeHandle<LightingEditorApi | null, LightingEditorApi | null>(\n    props.apiRef,\n    () => {\n      const ed = editorRef.current;\n      if (!ed) return null;\n      return {\n        setConfig: (p) => ed.setConfig(p),\n        getConfig: () => ed.getConfig(),\n        setSubjectImage: (url) => ed.setSubjectImage(url),\n        setView: (v) => ed.setView(v),\n        getView: () => ed.getView(),\n        reset: () => ed.reset(),\n      };\n    },\n    // Keyed on footerSlot — same null-lock fix the VideoEditor uses.\n    [footerSlot],\n  );\n\n  return (\n    <div\n      ref={hostRef}\n      className={props.className}\n      style={props.style}\n      data-aicut-lighting-host=\"\"\n    >\n      {footerSlot && props.controlsFooter != null\n        ? createPortal(props.controlsFooter, footerSlot)\n        : null}\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAQO;AACP,uBAA6B;AAC7B,sBAKO;AA4GH;AA/DG,SAAS,eAAe,OAA4B;AACzD,QAAM,cAAU,qBAA8B,IAAI;AAClD,QAAM,gBAAY,qBAAkC,IAAI;AAIxD,QAAM,CAAC,YAAY,aAAa,QAAI,uBAA6B,IAAI;AAErE,QAAM,YAAQ,qBAAO,KAAK;AAC1B,QAAM,UAAU;AAEhB,8BAAU,MAAM;AACd,UAAM,OAAO,QAAQ;AACrB,QAAI,CAAC,KAAM;AACX,UAAM,SAAS,gBAAAA,eAAmB,OAAO;AAAA,MACvC,WAAW;AAAA,MACX,iBAAiB,MAAM,QAAQ;AAAA,MAC/B,QAAQ,MAAM,QAAQ;AAAA,MACtB,MAAM,MAAM,QAAQ;AAAA,MACpB,OAAO,MAAM,QAAQ;AAAA,MACrB,QAAQ,MAAM,QAAQ;AAAA,MACtB,UAAU,CAAC,QAAQ,MAAM,QAAQ,WAAW,GAAG;AAAA,IACjD,CAAC;AACD,cAAU,UAAU;AACpB,kBAAc,OAAO,cAAc;AACnC,WAAO,MAAM;AACX,aAAO,QAAQ;AACf,gBAAU,UAAU;AACpB,oBAAc,IAAI;AAAA,IACpB;AAAA,EAEF,GAAG,CAAC,CAAC;AAEL,8BAAU,MAAM;AACd,QAAI,MAAM,MAAO,WAAU,SAAS,SAAS,MAAM,KAAK;AAAA,EAC1D,GAAG,CAAC,MAAM,KAAK,CAAC;AAChB,8BAAU,MAAM;AACd,cAAU,SAAS,UAAU,MAAM,UAAU,CAAC,CAAC;AAAA,EACjD,GAAG,CAAC,MAAM,MAAM,CAAC;AACjB,8BAAU,MAAM;AACd,QAAI,MAAM;AACR,gBAAU,SAAS,gBAAgB,MAAM,eAAe;AAAA,EAC5D,GAAG,CAAC,MAAM,eAAe,CAAC;AAE1B;AAAA,IACE,MAAM;AAAA,IACN,MAAM;AACJ,YAAM,KAAK,UAAU;AACrB,UAAI,CAAC,GAAI,QAAO;AAChB,aAAO;AAAA,QACL,WAAW,CAAC,MAAM,GAAG,UAAU,CAAC;AAAA,QAChC,WAAW,MAAM,GAAG,UAAU;AAAA,QAC9B,iBAAiB,CAAC,QAAQ,GAAG,gBAAgB,GAAG;AAAA,QAChD,SAAS,CAAC,MAAM,GAAG,QAAQ,CAAC;AAAA,QAC5B,SAAS,MAAM,GAAG,QAAQ;AAAA,QAC1B,OAAO,MAAM,GAAG,MAAM;AAAA,MACxB;AAAA,IACF;AAAA;AAAA,IAEA,CAAC,UAAU;AAAA,EACb;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,KAAK;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,OAAO,MAAM;AAAA,MACb,4BAAyB;AAAA,MAExB,wBAAc,MAAM,kBAAkB,WACnC,+BAAa,MAAM,gBAAgB,UAAU,IAC7C;AAAA;AAAA,EACN;AAEJ;;;AD1HA,IAAAC,mBAOO;","names":["CoreLightingEditor","import_lighting"]}

package/dist/lighting.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { CSSProperties, Ref } from 'react';
+import { ReactNode, CSSProperties, Ref } from 'react';
 import { LightingConfig, LightingView, LightingEditorOptions } from '@aicut/core/lighting';
 export { DEFAULT_LIGHTING_CONFIG, KeyPreset, LightingConfig, LightingEditorOptions, LightingLocale, LightingView, PRESET_DIRECTIONS, lightingLocaleEn, lightingLocaleZh, mergeLightingLocale, snapToPreset } from '@aicut/core/lighting';
 import { Theme } from '@aicut/core';
@@ -10,6 +10,8 @@ interface LightingEditorApi {
     setSubjectImage(url: string): void;
     setView(v: LightingView): void;
     getView(): LightingView;
+    /** Convenience — restores config to safe defaults. */
+    reset(): void;
 }
 interface LightingEditorProps {
     /** Initial subject image (URL or data URI). Reactive. */
@@ -22,6 +24,13 @@ interface LightingEditorProps {
     theme?: Theme;
     /** Locale partial — reactive (calls editor.setLocale). */
     locale?: LightingEditorOptions["locale"];
+    /**
+     * Any React node — portaled into the editor's controls footer slot
+     * (where the built-in Reset button used to live). Hosts put their
+     * Reset / Generate / save-preset / etc. buttons here. Empty until
+     * populated; the library renders nothing into the slot.
+     */
+    controlsFooter?: ReactNode;
     className?: string;
     style?: CSSProperties;
     apiRef?: Ref<LightingEditorApi | null>;
@@ -29,9 +38,8 @@ interface LightingEditorProps {
 }
 /**
  * React shell for the 3D lighting picker. Renders scene + controls;
- * nothing else. Host code lays out their own surrounding UI (smart
- * mode panel, generate button, etc.) alongside this component in
- * whatever flex/grid the host prefers.
+ * the host owns everything else (smart panel beside, action buttons
+ * in the controlsFooter slot, layout, theming the surrounding page).
  */
 declare function LightingEditor(props: LightingEditorProps): react.JSX.Element;
 

package/dist/lighting.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { CSSProperties, Ref } from 'react';
+import { ReactNode, CSSProperties, Ref } from 'react';
 import { LightingConfig, LightingView, LightingEditorOptions } from '@aicut/core/lighting';
 export { DEFAULT_LIGHTING_CONFIG, KeyPreset, LightingConfig, LightingEditorOptions, LightingLocale, LightingView, PRESET_DIRECTIONS, lightingLocaleEn, lightingLocaleZh, mergeLightingLocale, snapToPreset } from '@aicut/core/lighting';
 import { Theme } from '@aicut/core';
@@ -10,6 +10,8 @@ interface LightingEditorApi {
     setSubjectImage(url: string): void;
     setView(v: LightingView): void;
     getView(): LightingView;
+    /** Convenience — restores config to safe defaults. */
+    reset(): void;
 }
 interface LightingEditorProps {
     /** Initial subject image (URL or data URI). Reactive. */
@@ -22,6 +24,13 @@ interface LightingEditorProps {
     theme?: Theme;
     /** Locale partial — reactive (calls editor.setLocale). */
     locale?: LightingEditorOptions["locale"];
+    /**
+     * Any React node — portaled into the editor's controls footer slot
+     * (where the built-in Reset button used to live). Hosts put their
+     * Reset / Generate / save-preset / etc. buttons here. Empty until
+     * populated; the library renders nothing into the slot.
+     */
+    controlsFooter?: ReactNode;
     className?: string;
     style?: CSSProperties;
     apiRef?: Ref<LightingEditorApi | null>;
@@ -29,9 +38,8 @@ interface LightingEditorProps {
 }
 /**
  * React shell for the 3D lighting picker. Renders scene + controls;
- * nothing else. Host code lays out their own surrounding UI (smart
- * mode panel, generate button, etc.) alongside this component in
- * whatever flex/grid the host prefers.
+ * the host owns everything else (smart panel beside, action buttons
+ * in the controlsFooter slot, layout, theming the surrounding page).
  */
 declare function LightingEditor(props: LightingEditorProps): react.JSX.Element;
 

package/dist/lighting.js

@@ -5,6 +5,7 @@ import {
   useRef,
   useState
 } from "react";
+import { createPortal } from "react-dom";
 import {
   LightingEditor as CoreLightingEditor
 } from "@aicut/core/lighting";
@@ -12,7 +13,7 @@ import { jsx } from "react/jsx-runtime";
 function LightingEditor(props) {
   const hostRef = useRef(null);
   const editorRef = useRef(null);
-  const [ready, setReady] = useState(false);
+  const [footerSlot, setFooterSlot] = useState(null);
   const cbRef = useRef(props);
   cbRef.current = props;
   useEffect(() => {
@@ -28,11 +29,11 @@ function LightingEditor(props) {
       onChange: (cfg) => cbRef.current.onChange?.(cfg)
     });
     editorRef.current = editor;
-    setReady(true);
+    setFooterSlot(editor.controlsFooter);
     return () => {
       editor.destroy();
       editorRef.current = null;
-      setReady(false);
+      setFooterSlot(null);
     };
   }, []);
   useEffect(() => {
@@ -55,10 +56,12 @@ function LightingEditor(props) {
         getConfig: () => ed.getConfig(),
         setSubjectImage: (url) => ed.setSubjectImage(url),
         setView: (v) => ed.setView(v),
-        getView: () => ed.getView()
+        getView: () => ed.getView(),
+        reset: () => ed.reset()
       };
     },
-    [ready]
+    // Keyed on footerSlot — same null-lock fix the VideoEditor uses.
+    [footerSlot]
   );
   return /* @__PURE__ */ jsx(
     "div",
@@ -66,7 +69,8 @@ function LightingEditor(props) {
       ref: hostRef,
       className: props.className,
       style: props.style,
-      "data-aicut-lighting-host": ""
+      "data-aicut-lighting-host": "",
+      children: footerSlot && props.controlsFooter != null ? createPortal(props.controlsFooter, footerSlot) : null
     }
   );
 }

package/dist/lighting.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/LightingEditor.tsx","../src/lighting.ts"],"sourcesContent":["import {\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type Ref,\n} from \"react\";\nimport {\n  LightingEditor as CoreLightingEditor,\n  type LightingConfig,\n  type LightingEditorOptions,\n  type LightingView,\n} from \"@aicut/core/lighting\";\nimport type { Theme } from \"@aicut/core\";\n\nexport interface LightingEditorApi {\n  setConfig(partial: Partial<LightingConfig>): void;\n  getConfig(): LightingConfig;\n  setSubjectImage(url: string): void;\n  setView(v: LightingView): void;\n  getView(): LightingView;\n}\n\nexport interface LightingEditorProps {\n  /** Initial subject image (URL or data URI). Reactive. */\n  subjectImageUrl?: string;\n  /** Initial config. */\n  defaultConfig?: Partial<LightingConfig>;\n  /** Initial view. Default `\"perspective\"`. */\n  defaultView?: LightingView;\n  /** Theme — reactive (calls editor.setTheme). */\n  theme?: Theme;\n  /** Locale partial — reactive (calls editor.setLocale). */\n  locale?: LightingEditorOptions[\"locale\"];\n\n  className?: string;\n  style?: CSSProperties;\n  apiRef?: Ref<LightingEditorApi | null>;\n\n  onChange?: (cfg: LightingConfig) => void;\n}\n\n/**\n * React shell for the 3D lighting picker. Renders scene + controls;\n * nothing else. Host code lays out their own surrounding UI (smart\n * mode panel, generate button, etc.) alongside this component in\n * whatever flex/grid the host prefers.\n */\nexport function LightingEditor(props: LightingEditorProps) {\n  const hostRef = useRef<HTMLDivElement | null>(null);\n  const editorRef = useRef<CoreLightingEditor | null>(null);\n  // Triggers a re-render the moment the editor is created, so the\n  // useImperativeHandle factory below can return the real instance\n  // instead of locking at null forever (same trick as VideoEditor).\n  const [ready, setReady] = useState(false);\n\n  const cbRef = useRef(props);\n  cbRef.current = props;\n\n  useEffect(() => {\n    const host = hostRef.current;\n    if (!host) return;\n    const editor = CoreLightingEditor.create({\n      container: host,\n      subjectImageUrl: cbRef.current.subjectImageUrl,\n      config: cbRef.current.defaultConfig,\n      view: cbRef.current.defaultView,\n      theme: cbRef.current.theme,\n      locale: cbRef.current.locale,\n      onChange: (cfg) => cbRef.current.onChange?.(cfg),\n    });\n    editorRef.current = editor;\n    setReady(true);\n    return () => {\n      editor.destroy();\n      editorRef.current = null;\n      setReady(false);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  useEffect(() => {\n    if (props.theme) editorRef.current?.setTheme(props.theme);\n  }, [props.theme]);\n  useEffect(() => {\n    // Always push — `undefined` is the \"reset to English defaults\"\n    // signal. Without this, toggling ZH→EN in the host kept ZH labels.\n    editorRef.current?.setLocale(props.locale ?? {});\n  }, [props.locale]);\n  useEffect(() => {\n    if (props.subjectImageUrl)\n      editorRef.current?.setSubjectImage(props.subjectImageUrl);\n  }, [props.subjectImageUrl]);\n\n  useImperativeHandle<LightingEditorApi | null, LightingEditorApi | null>(\n    props.apiRef,\n    () => {\n      const ed = editorRef.current;\n      if (!ed) return null;\n      return {\n        setConfig: (p) => ed.setConfig(p),\n        getConfig: () => ed.getConfig(),\n        setSubjectImage: (url) => ed.setSubjectImage(url),\n        setView: (v) => ed.setView(v),\n        getView: () => ed.getView(),\n      };\n    },\n    [ready],\n  );\n\n  return (\n    <div\n      ref={hostRef}\n      className={props.className}\n      style={props.style}\n      data-aicut-lighting-host=\"\"\n    />\n  );\n}\n","/**\n * @aicut/react/lighting — separate entry that pulls three.js. Users\n * who never import this path don't pay the three.js bundle cost.\n */\nexport { LightingEditor } from \"./LightingEditor.js\";\nexport type {\n  LightingEditorProps,\n  LightingEditorApi,\n} from \"./LightingEditor.js\";\n\n// Re-export the data + locale exports from the core sub-entry so\n// hosts only need a single import line for everything lighting-related.\nexport {\n  DEFAULT_LIGHTING_CONFIG,\n  PRESET_DIRECTIONS,\n  lightingLocaleEn,\n  lightingLocaleZh,\n  mergeLightingLocale,\n  snapToPreset,\n} from \"@aicut/core/lighting\";\nexport type {\n  KeyPreset,\n  LightingConfig,\n  LightingEditorOptions,\n  LightingLocale,\n  LightingView,\n} from \"@aicut/core/lighting\";\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP;AAAA,EACE,kBAAkB;AAAA,OAIb;AAmGH;AA/DG,SAAS,eAAe,OAA4B;AACzD,QAAM,UAAU,OAA8B,IAAI;AAClD,QAAM,YAAY,OAAkC,IAAI;AAIxD,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAS,KAAK;AAExC,QAAM,QAAQ,OAAO,KAAK;AAC1B,QAAM,UAAU;AAEhB,YAAU,MAAM;AACd,UAAM,OAAO,QAAQ;AACrB,QAAI,CAAC,KAAM;AACX,UAAM,SAAS,mBAAmB,OAAO;AAAA,MACvC,WAAW;AAAA,MACX,iBAAiB,MAAM,QAAQ;AAAA,MAC/B,QAAQ,MAAM,QAAQ;AAAA,MACtB,MAAM,MAAM,QAAQ;AAAA,MACpB,OAAO,MAAM,QAAQ;AAAA,MACrB,QAAQ,MAAM,QAAQ;AAAA,MACtB,UAAU,CAAC,QAAQ,MAAM,QAAQ,WAAW,GAAG;AAAA,IACjD,CAAC;AACD,cAAU,UAAU;AACpB,aAAS,IAAI;AACb,WAAO,MAAM;AACX,aAAO,QAAQ;AACf,gBAAU,UAAU;AACpB,eAAS,KAAK;AAAA,IAChB;AAAA,EAEF,GAAG,CAAC,CAAC;AAEL,YAAU,MAAM;AACd,QAAI,MAAM,MAAO,WAAU,SAAS,SAAS,MAAM,KAAK;AAAA,EAC1D,GAAG,CAAC,MAAM,KAAK,CAAC;AAChB,YAAU,MAAM;AAGd,cAAU,SAAS,UAAU,MAAM,UAAU,CAAC,CAAC;AAAA,EACjD,GAAG,CAAC,MAAM,MAAM,CAAC;AACjB,YAAU,MAAM;AACd,QAAI,MAAM;AACR,gBAAU,SAAS,gBAAgB,MAAM,eAAe;AAAA,EAC5D,GAAG,CAAC,MAAM,eAAe,CAAC;AAE1B;AAAA,IACE,MAAM;AAAA,IACN,MAAM;AACJ,YAAM,KAAK,UAAU;AACrB,UAAI,CAAC,GAAI,QAAO;AAChB,aAAO;AAAA,QACL,WAAW,CAAC,MAAM,GAAG,UAAU,CAAC;AAAA,QAChC,WAAW,MAAM,GAAG,UAAU;AAAA,QAC9B,iBAAiB,CAAC,QAAQ,GAAG,gBAAgB,GAAG;AAAA,QAChD,SAAS,CAAC,MAAM,GAAG,QAAQ,CAAC;AAAA,QAC5B,SAAS,MAAM,GAAG,QAAQ;AAAA,MAC5B;AAAA,IACF;AAAA,IACA,CAAC,KAAK;AAAA,EACR;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,KAAK;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,OAAO,MAAM;AAAA,MACb,4BAAyB;AAAA;AAAA,EAC3B;AAEJ;;;AC3GA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}
+{"version":3,"sources":["../src/LightingEditor.tsx","../src/lighting.ts"],"sourcesContent":["import {\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ReactNode,\n  type Ref,\n} from \"react\";\nimport { createPortal } from \"react-dom\";\nimport {\n  LightingEditor as CoreLightingEditor,\n  type LightingConfig,\n  type LightingEditorOptions,\n  type LightingView,\n} from \"@aicut/core/lighting\";\nimport type { Theme } from \"@aicut/core\";\n\nexport interface LightingEditorApi {\n  setConfig(partial: Partial<LightingConfig>): void;\n  getConfig(): LightingConfig;\n  setSubjectImage(url: string): void;\n  setView(v: LightingView): void;\n  getView(): LightingView;\n  /** Convenience — restores config to safe defaults. */\n  reset(): void;\n}\n\nexport interface LightingEditorProps {\n  /** Initial subject image (URL or data URI). Reactive. */\n  subjectImageUrl?: string;\n  /** Initial config. */\n  defaultConfig?: Partial<LightingConfig>;\n  /** Initial view. Default `\"perspective\"`. */\n  defaultView?: LightingView;\n  /** Theme — reactive (calls editor.setTheme). */\n  theme?: Theme;\n  /** Locale partial — reactive (calls editor.setLocale). */\n  locale?: LightingEditorOptions[\"locale\"];\n\n  /**\n   * Any React node — portaled into the editor's controls footer slot\n   * (where the built-in Reset button used to live). Hosts put their\n   * Reset / Generate / save-preset / etc. buttons here. Empty until\n   * populated; the library renders nothing into the slot.\n   */\n  controlsFooter?: ReactNode;\n\n  className?: string;\n  style?: CSSProperties;\n  apiRef?: Ref<LightingEditorApi | null>;\n\n  onChange?: (cfg: LightingConfig) => void;\n}\n\n/**\n * React shell for the 3D lighting picker. Renders scene + controls;\n * the host owns everything else (smart panel beside, action buttons\n * in the controlsFooter slot, layout, theming the surrounding page).\n */\nexport function LightingEditor(props: LightingEditorProps) {\n  const hostRef = useRef<HTMLDivElement | null>(null);\n  const editorRef = useRef<CoreLightingEditor | null>(null);\n  // Hold the footer slot DOM node in state so the portal mounts after\n  // editor creation. Same lifecycle dance VideoEditor does for its\n  // toolbar slots.\n  const [footerSlot, setFooterSlot] = useState<HTMLElement | null>(null);\n\n  const cbRef = useRef(props);\n  cbRef.current = props;\n\n  useEffect(() => {\n    const host = hostRef.current;\n    if (!host) return;\n    const editor = CoreLightingEditor.create({\n      container: host,\n      subjectImageUrl: cbRef.current.subjectImageUrl,\n      config: cbRef.current.defaultConfig,\n      view: cbRef.current.defaultView,\n      theme: cbRef.current.theme,\n      locale: cbRef.current.locale,\n      onChange: (cfg) => cbRef.current.onChange?.(cfg),\n    });\n    editorRef.current = editor;\n    setFooterSlot(editor.controlsFooter);\n    return () => {\n      editor.destroy();\n      editorRef.current = null;\n      setFooterSlot(null);\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  useEffect(() => {\n    if (props.theme) editorRef.current?.setTheme(props.theme);\n  }, [props.theme]);\n  useEffect(() => {\n    editorRef.current?.setLocale(props.locale ?? {});\n  }, [props.locale]);\n  useEffect(() => {\n    if (props.subjectImageUrl)\n      editorRef.current?.setSubjectImage(props.subjectImageUrl);\n  }, [props.subjectImageUrl]);\n\n  useImperativeHandle<LightingEditorApi | null, LightingEditorApi | null>(\n    props.apiRef,\n    () => {\n      const ed = editorRef.current;\n      if (!ed) return null;\n      return {\n        setConfig: (p) => ed.setConfig(p),\n        getConfig: () => ed.getConfig(),\n        setSubjectImage: (url) => ed.setSubjectImage(url),\n        setView: (v) => ed.setView(v),\n        getView: () => ed.getView(),\n        reset: () => ed.reset(),\n      };\n    },\n    // Keyed on footerSlot — same null-lock fix the VideoEditor uses.\n    [footerSlot],\n  );\n\n  return (\n    <div\n      ref={hostRef}\n      className={props.className}\n      style={props.style}\n      data-aicut-lighting-host=\"\"\n    >\n      {footerSlot && props.controlsFooter != null\n        ? createPortal(props.controlsFooter, footerSlot)\n        : null}\n    </div>\n  );\n}\n","/**\n * @aicut/react/lighting — separate entry that pulls three.js. Users\n * who never import this path don't pay the three.js bundle cost.\n */\nexport { LightingEditor } from \"./LightingEditor.js\";\nexport type {\n  LightingEditorProps,\n  LightingEditorApi,\n} from \"./LightingEditor.js\";\n\n// Re-export the data + locale exports from the core sub-entry so\n// hosts only need a single import line for everything lighting-related.\nexport {\n  DEFAULT_LIGHTING_CONFIG,\n  PRESET_DIRECTIONS,\n  lightingLocaleEn,\n  lightingLocaleZh,\n  mergeLightingLocale,\n  snapToPreset,\n} from \"@aicut/core/lighting\";\nexport type {\n  KeyPreset,\n  LightingConfig,\n  LightingEditorOptions,\n  LightingLocale,\n  LightingView,\n} from \"@aicut/core/lighting\";\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AACP,SAAS,oBAAoB;AAC7B;AAAA,EACE,kBAAkB;AAAA,OAIb;AA4GH;AA/DG,SAAS,eAAe,OAA4B;AACzD,QAAM,UAAU,OAA8B,IAAI;AAClD,QAAM,YAAY,OAAkC,IAAI;AAIxD,QAAM,CAAC,YAAY,aAAa,IAAI,SAA6B,IAAI;AAErE,QAAM,QAAQ,OAAO,KAAK;AAC1B,QAAM,UAAU;AAEhB,YAAU,MAAM;AACd,UAAM,OAAO,QAAQ;AACrB,QAAI,CAAC,KAAM;AACX,UAAM,SAAS,mBAAmB,OAAO;AAAA,MACvC,WAAW;AAAA,MACX,iBAAiB,MAAM,QAAQ;AAAA,MAC/B,QAAQ,MAAM,QAAQ;AAAA,MACtB,MAAM,MAAM,QAAQ;AAAA,MACpB,OAAO,MAAM,QAAQ;AAAA,MACrB,QAAQ,MAAM,QAAQ;AAAA,MACtB,UAAU,CAAC,QAAQ,MAAM,QAAQ,WAAW,GAAG;AAAA,IACjD,CAAC;AACD,cAAU,UAAU;AACpB,kBAAc,OAAO,cAAc;AACnC,WAAO,MAAM;AACX,aAAO,QAAQ;AACf,gBAAU,UAAU;AACpB,oBAAc,IAAI;AAAA,IACpB;AAAA,EAEF,GAAG,CAAC,CAAC;AAEL,YAAU,MAAM;AACd,QAAI,MAAM,MAAO,WAAU,SAAS,SAAS,MAAM,KAAK;AAAA,EAC1D,GAAG,CAAC,MAAM,KAAK,CAAC;AAChB,YAAU,MAAM;AACd,cAAU,SAAS,UAAU,MAAM,UAAU,CAAC,CAAC;AAAA,EACjD,GAAG,CAAC,MAAM,MAAM,CAAC;AACjB,YAAU,MAAM;AACd,QAAI,MAAM;AACR,gBAAU,SAAS,gBAAgB,MAAM,eAAe;AAAA,EAC5D,GAAG,CAAC,MAAM,eAAe,CAAC;AAE1B;AAAA,IACE,MAAM;AAAA,IACN,MAAM;AACJ,YAAM,KAAK,UAAU;AACrB,UAAI,CAAC,GAAI,QAAO;AAChB,aAAO;AAAA,QACL,WAAW,CAAC,MAAM,GAAG,UAAU,CAAC;AAAA,QAChC,WAAW,MAAM,GAAG,UAAU;AAAA,QAC9B,iBAAiB,CAAC,QAAQ,GAAG,gBAAgB,GAAG;AAAA,QAChD,SAAS,CAAC,MAAM,GAAG,QAAQ,CAAC;AAAA,QAC5B,SAAS,MAAM,GAAG,QAAQ;AAAA,QAC1B,OAAO,MAAM,GAAG,MAAM;AAAA,MACxB;AAAA,IACF;AAAA;AAAA,IAEA,CAAC,UAAU;AAAA,EACb;AAEA,SACE;AAAA,IAAC;AAAA;AAAA,MACC,KAAK;AAAA,MACL,WAAW,MAAM;AAAA,MACjB,OAAO,MAAM;AAAA,MACb,4BAAyB;AAAA,MAExB,wBAAc,MAAM,kBAAkB,OACnC,aAAa,MAAM,gBAAgB,UAAU,IAC7C;AAAA;AAAA,EACN;AAEJ;;;AC1HA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicut/react",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "React wrapper for the AiCut video editor + lighting picker — thin declarative shells over @aicut/core.",
   "license": "MIT",
   "author": "ziqiang <ziqiangytu@gmail.com>",
@@ -59,7 +59,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@aicut/core": "0.3.0"
+    "@aicut/core": "0.4.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",