@kokoa/clotho-editor 0.1.4 → 0.3.0

package/README.md

@@ -11,7 +11,10 @@ npm install @kokoa/clotho @kokoa/clotho-editor react react-dom
 ```
 
 ```tsx
-import { StudioMount, createLocalStorageRepository } from "@kokoa/clotho-editor";
+import {
+  StudioMount,
+  createLocalStorageRepository,
+} from "@kokoa/clotho-editor";
 import "@kokoa/clotho/styles.css";
 import "@kokoa/clotho-editor/styles.css";
 
@@ -59,6 +62,55 @@ const repository: AnimationRepository = {
 
 저장 버튼의 동작 자체를 바꾸려면 repository의 `create`와 `save`를 구현합니다. 예제 목록은 repository의 `list`와 `load`에서 제공하므로 editor package 안에 application별 API 경로를 넣을 필요가 없습니다.
 
+## Plugin host
+
+application 전용 도구는 `plugins`로 추가할 수 있습니다. plugin은 toolbar, 왼쪽 panel, inspector와 command palette에 기능을 붙일 수 있지만, 문서를 읽거나 바꾸려면 host가 권한을 명시적으로 허용해야 합니다. 저장소, selection, undo/redo와 같은 편집기의 기본 기능은 plugin으로 분리하지 않습니다.
+
+```tsx
+import { StudioMount, type EditorPluginDefinition } from "@kokoa/clotho-editor";
+
+const reviewPlugin: EditorPluginDefinition = {
+  manifest: {
+    id: "com.example.review",
+    version: "1.0.0",
+    capabilities: ["editor"],
+    editor: { toolbarItems: ["review"] },
+  },
+  toolbarItems: {
+    review: ({ container, document }) => {
+      const button = document.createElement("button");
+      button.textContent = "검토 요청";
+      container.append(button);
+    },
+  },
+};
+
+<StudioMount
+  plugins={[reviewPlugin]}
+  resolvePluginPermissions={(manifest) =>
+    manifest.id === "com.example.review" ? { ui: true, documentRead: true } : {}
+  }
+/>;
+```
+
+Clotho compiler plugin이 새로운 JSON 입력 형식을 처리해야 한다면 `importDocument`에서 compiler pipeline을 연결합니다. 이 경계 덕분에 Editor는 application의 plugin registry나 backend에 의존하지 않습니다.
+
+```tsx
+import { createPluginRegistry, runPluginPipeline } from "@kokoa/clotho/plugins";
+
+const registry = createPluginRegistry(compilerPlugins);
+
+<StudioMount
+  importDocument={(input) => {
+    const result = runPluginPipeline(input, { registry });
+    if (!result.ok) throw result.error;
+    return result.document;
+  }}
+/>;
+```
+
+현재 plugin API는 신뢰할 수 있는 application code를 위한 실험적 API입니다. 외부에서 받은 plugin은 별도 Worker나 격리 환경에서 실행한 뒤 JSON 결과만 Editor로 전달해야 합니다.
+
 ## 주요 기능
 
 - Clotho v1 JSON 문서 작성과 검증

package/dist/{chunk-GMGB7NIL.js → chunk-N47HF4VB.js}

@@ -1,4 +1,4 @@
-import { animationDocumentSchema, computeSnapshot, encodeImageAsset, inlineAssetFromDataUri } from '@kokoa/clotho';
+import { animationDocumentSchema, computeSnapshot, compileDataBindings, encodeImageAsset, inlineAssetFromDataUri, compileLayouts } from '@kokoa/clotho';
 
 // src/export-json.ts
 function animationDocumentToJson(def) {
@@ -292,7 +292,10 @@ function toggleSelectionFor(sel, id) {
 }
 function getCurrentSnapshot() {
   if (!state.def) return /* @__PURE__ */ new Map();
-  return computeSnapshot(state.def, state.currentTime);
+  return computeSnapshot(
+    compileDataBindings(state.def).document,
+    state.currentTime
+  );
 }
 
 // src/legacy/state/history.ts
@@ -707,6 +710,180 @@ function updateDuration(ms) {
   );
   if (state.currentTime > ms) state.currentTime = ms;
 }
+
+// src/legacy/state/camera.ts
+var EMPTY = { tracks: [], focus: [], strokeScaling: "scale" };
+function getCamera() {
+  return state.def?.camera ?? EMPTY;
+}
+function hasCamera() {
+  const camera = state.def?.camera;
+  return camera !== void 0 && (camera.tracks.length > 0 || camera.focus.length > 0 || camera.strokeScaling !== "scale");
+}
+function cameraControlAt(time) {
+  const camera = state.def?.camera;
+  if (!camera || camera.tracks.length === 0 && camera.focus.length === 0) {
+    return { kind: "none" };
+  }
+  let index = -1;
+  camera.focus.forEach((entry, i) => {
+    if (entry.time <= time) index = i;
+  });
+  return index >= 0 ? { kind: "focus", index } : { kind: "tracks" };
+}
+function ensure(def) {
+  def.camera ??= { tracks: [], focus: [], strokeScaling: "scale" };
+  return def.camera;
+}
+function setCameraStrokeScaling(value) {
+  mutateDef(
+    (def) => {
+      ensure(def).strokeScaling = value;
+    },
+    `\uCE74\uBA54\uB77C \uC120 \uB450\uAED8: ${value}`,
+    "camera"
+  );
+}
+function setCameraKeyframe(property, time, value, ease) {
+  mutateDef(
+    (def) => {
+      const camera = ensure(def);
+      let track = camera.tracks.find((t) => t.property === property);
+      if (!track) {
+        track = { property, keyframes: [] };
+        camera.tracks.push(track);
+        camera.tracks.sort(
+          (a, b) => ORDER.indexOf(a.property) - ORDER.indexOf(b.property)
+        );
+      }
+      const existing = track.keyframes.findIndex((kf) => kf.time === time);
+      const next = { time, value, ...ease ? { ease } : {} };
+      if (existing >= 0) track.keyframes[existing] = next;
+      else track.keyframes.push(next);
+      track.keyframes.sort((a, b) => a.time - b.time);
+    },
+    `\uCE74\uBA54\uB77C keyframe: ${property} @ ${time}ms`,
+    "camera"
+  );
+}
+var ORDER = ["zoom", "x", "y"];
+function moveCameraKeyframe(property, from, to) {
+  if (from === to) return;
+  mutateDef(
+    (def) => {
+      const track = def.camera?.tracks.find((t) => t.property === property);
+      const kf = track?.keyframes.find((k) => k.time === from);
+      if (!track || !kf) return;
+      track.keyframes = track.keyframes.filter(
+        (k) => k.time !== from && k.time !== to
+      );
+      track.keyframes.push({ ...kf, time: to });
+      track.keyframes.sort((a, b) => a.time - b.time);
+    },
+    `\uCE74\uBA54\uB77C keyframe \uC774\uB3D9: ${property} ${from}\u2192${to}ms`,
+    "camera"
+  );
+}
+function removeCameraKeyframe(property, time) {
+  mutateDef(
+    (def) => {
+      const camera = def.camera;
+      const track = camera?.tracks.find((t) => t.property === property);
+      if (!camera || !track) return;
+      track.keyframes = track.keyframes.filter((kf) => kf.time !== time);
+      if (track.keyframes.length === 0) {
+        camera.tracks = camera.tracks.filter((t) => t.property !== property);
+      }
+    },
+    `\uCE74\uBA54\uB77C keyframe \uC0AD\uC81C: ${property} @ ${time}ms`,
+    "camera"
+  );
+}
+function removeCameraTrack(property) {
+  mutateDef(
+    (def) => {
+      if (def.camera) {
+        def.camera.tracks = def.camera.tracks.filter(
+          (t) => t.property !== property
+        );
+      }
+    },
+    `\uCE74\uBA54\uB77C track \uC0AD\uC81C: ${property}`,
+    "camera"
+  );
+}
+function addCameraFocus(focus) {
+  mutateDef(
+    (def) => {
+      const camera = ensure(def);
+      camera.focus.push(focus);
+      camera.focus.sort((a, b) => a.time - b.time);
+    },
+    `\uCE74\uBA54\uB77C focus \uCD94\uAC00 @ ${focus.time}ms`,
+    "camera"
+  );
+  const index = getCamera().focus.findIndex(
+    (f) => f.time === focus.time && f.elementIds.join() === focus.elementIds.join()
+  );
+  state.selection = {
+    kind: "camera",
+    focusIndex: index < 0 ? void 0 : index
+  };
+  emit();
+}
+function updateCameraFocus(index, patch) {
+  const before = getCamera().focus[index];
+  if (!before) return;
+  const after = { ...before, ...patch };
+  mutateDef(
+    (def) => {
+      const camera = def.camera;
+      if (!camera?.focus[index]) return;
+      camera.focus[index] = after;
+      camera.focus.sort((a, b) => a.time - b.time);
+    },
+    `\uCE74\uBA54\uB77C focus \uC218\uC815: ${Object.keys(patch).join(", ")}`,
+    "camera"
+  );
+  if (state.selection.kind === "camera") {
+    const moved = getCamera().focus.findIndex(
+      (f) => f.time === after.time && f.elementIds.join() === after.elementIds.join() && f.duration === after.duration
+    );
+    state.selection = {
+      kind: "camera",
+      focusIndex: moved < 0 ? void 0 : moved
+    };
+    emit();
+  }
+}
+function deleteCameraFocus(index) {
+  mutateDef(
+    (def) => {
+      if (def.camera) {
+        def.camera.focus = def.camera.focus.filter((_, i) => i !== index);
+      }
+    },
+    `\uCE74\uBA54\uB77C focus \uC0AD\uC81C #${index + 1}`,
+    "camera"
+  );
+  if (state.selection.kind === "camera") {
+    state.selection = { kind: "camera" };
+    emit();
+  }
+}
+function clearCamera() {
+  mutateDef(
+    (def) => {
+      delete def.camera;
+    },
+    "\uCE74\uBA54\uB77C \uC81C\uAC70",
+    "camera"
+  );
+  if (state.selection.kind === "camera") {
+    state.selection = { kind: "none" };
+    emit();
+  }
+}
 function updateMeta(patch) {
   const keys = Object.keys(patch).join(", ");
   mutateDef(
@@ -726,6 +903,24 @@ function updateLocales(locales) {
     "meta"
   );
 }
+function updateData(data) {
+  mutateDef(
+    (def) => {
+      def.data = data;
+    },
+    "\uC0D8\uD50C \uB370\uC774\uD130 \uBCC0\uACBD",
+    "meta"
+  );
+}
+function updateResponsive(responsive) {
+  mutateDef(
+    (def) => {
+      def.responsive = responsive;
+    },
+    "Responsive Stage \uBCC0\uACBD",
+    "canvas"
+  );
+}
 function updateCanvas(patch) {
   const keys = Object.keys(patch).join(", ");
   mutateDef(
@@ -830,6 +1025,125 @@ function registerDataUriAsset(dataUri) {
   );
   return id;
 }
+function uniqueLayoutId(def) {
+  const used = new Set(def.layouts.map((layout) => layout.id));
+  let index = 1;
+  while (used.has(`layout-${index}`)) index += 1;
+  return `layout-${index}`;
+}
+function createLayout(elementIds, mode) {
+  if (elementIds.length === 0) return;
+  mutateDef(
+    (def) => {
+      const selected = def.elements.filter(
+        (element) => elementIds.includes(element.id)
+      );
+      if (selected.length === 0) return;
+      const measured = compileLayouts({ ...def, layouts: [] }).boxes;
+      const boxes = selected.flatMap((element) => {
+        const box = measured[element.id];
+        return box ? [box] : [];
+      });
+      const x = boxes.length > 0 ? Math.min(...boxes.map((box) => box.x)) : 0;
+      const y = boxes.length > 0 ? Math.min(...boxes.map((box) => box.y)) : 0;
+      def.layouts = def.layouts.filter(
+        (layout) => !layout.elementIds.some((id) => elementIds.includes(id))
+      );
+      def.layouts.push({
+        id: uniqueLayoutId(def),
+        mode,
+        elementIds: selected.map((element) => element.id),
+        x,
+        y,
+        gap: 16,
+        align: "start",
+        constraints: []
+      });
+      def.elements = compileLayouts(def).document.elements;
+    },
+    `${mode} layout \uC0DD\uC131`,
+    "layout"
+  );
+}
+function detachFromLayout(elementIds) {
+  const ids = new Set(elementIds);
+  mutateDef(
+    (def) => {
+      def.layouts = def.layouts.flatMap((layout) => {
+        const remaining = layout.elementIds.filter((id) => !ids.has(id));
+        return remaining.length === 0 ? [] : [{ ...layout, elementIds: remaining }];
+      });
+    },
+    "layout\uC5D0\uC11C \uBD84\uB9AC",
+    "layout"
+  );
+}
+function layoutIdsFor(elementIds) {
+  if (!state.def) return [];
+  const ids = new Set(elementIds);
+  return state.def.layouts.filter((layout) => layout.elementIds.some((id) => ids.has(id))).map((layout) => layout.id);
+}
+function findLayoutCollisions(def) {
+  const { boxes } = compileLayouts(def);
+  const collisions = [];
+  for (const layout of def.layouts) {
+    for (let firstIndex = 0; firstIndex < layout.elementIds.length; firstIndex += 1) {
+      for (let secondIndex = firstIndex + 1; secondIndex < layout.elementIds.length; secondIndex += 1) {
+        const firstId = layout.elementIds[firstIndex];
+        const secondId = layout.elementIds[secondIndex];
+        const first = boxes[firstId];
+        const second = boxes[secondId];
+        if (!first || !second) continue;
+        const overlaps = first.x < second.x + second.width && first.x + first.width > second.x && first.y < second.y + second.height && first.y + first.height > second.y;
+        if (overlaps) collisions.push({ firstId, secondId });
+      }
+    }
+  }
+  return collisions;
+}
+
+// src/legacy/state/checkpoints.ts
+function addCheckpoint(checkpoint) {
+  mutateDef(
+    (def) => {
+      def.checkpoints.push(checkpoint);
+      def.checkpoints.sort((a, b) => a.time - b.time);
+    },
+    `Checkpoint \uCD94\uAC00: ${checkpoint.id}`,
+    "checkpoint"
+  );
+}
+function updateCheckpoint(id, patch) {
+  mutateDef(
+    (def) => {
+      const index = def.checkpoints.findIndex(
+        (checkpoint) => checkpoint.id === id
+      );
+      if (index < 0) return;
+      def.checkpoints[index] = {
+        ...def.checkpoints[index],
+        ...patch
+      };
+      def.checkpoints.sort((a, b) => a.time - b.time);
+    },
+    `Checkpoint \uC218\uC815: ${id}`,
+    "checkpoint"
+  );
+}
+function deleteCheckpoint(id) {
+  mutateDef(
+    (def) => {
+      def.checkpoints = def.checkpoints.filter(
+        (checkpoint) => checkpoint.id !== id
+      );
+    },
+    `Checkpoint \uC0AD\uC81C: ${id}`,
+    "checkpoint"
+  );
+}
+function uniqueCheckpointId() {
+  return `checkpoint-${Date.now().toString(36)}`;
+}
 
 // src/legacy/studio-groups.ts
 function isGroup(el) {
@@ -974,21 +1288,6 @@ function groupElements(ids) {
   const valid = ids.filter((id) => def.elements.some((e) => e.id === id));
   if (valid.length < 2) return null;
   const newId = uniqueElementId("group");
-  (() => {
-    let minX = Infinity, minY = Infinity;
-    for (const id of valid) {
-      const el = def.elements.find((e) => e.id === id);
-      if (!el) continue;
-      const b = elementBbox(el);
-      if (!b) continue;
-      if (b.x < minX) minX = b.x;
-      if (b.y < minY) minY = b.y;
-    }
-    return {
-      x: Number.isFinite(minX) ? minX : 0,
-      y: Number.isFinite(minY) ? minY : 0
-    };
-  })();
   const group = {
     type: "group",
     id: newId,
@@ -996,6 +1295,7 @@ function groupElements(ids) {
     rotation: 0,
     appearances: [],
     tracks: [],
+    bindings: [],
     // Children keep their absolute coordinates, so the group's own transform starts at
     // the identity. Setting x/y here would shift every member on the next render.
     x: 0,
@@ -1033,6 +1333,122 @@ function placeholderImageUrl() {
   return placeholderUrl;
 }
 
-export { addAppearance, addChapter, addEffect, addElement, animationDocumentFileName, animationDocumentToJson, apiBaseUrl, beginTransient, canRedo, canUndo, childIdsOf, configureAnimationRepository, configureApi, configureHost, createAnimation, deleteAnimation, deleteChapter, deleteEffect, deleteElement, downloadAnimationJson, duplicateAnimation, endTransient, findContainingGroup, garbageCollectAnimationAssets, getCurrentSnapshot, getCurrentTime, getDef, getHistory, getSelectedElementIds, getSelection, groupBbox, groupElements, importAnimation, isDirty, isDraft, isElementSelected, isGroup, jumpBack, jumpForward, listAnimations, loadAnimation, markClean, moveElementToEnd, moveElementToFront, moveGroupBy, placeholderImageUrl, promoteDraftToSaved, redo, registerDataUriAsset, registerExternalAsset, registerInlineAsset, removeAppearance, removeTrack, removeTrackKeyframe, reorderElement, resetHistory, saveAnimation, setCurrentTime, setDef, setDraft, setElementValueAtTime, setSelection, setTrackKeyframe, subscribe, toggleSelectionFor, undo, ungroupElement, uniqueChapterId, uniqueEffectId, uniqueElementId, updateAppearance, updateCanvas, updateChapter, updateDuration, updateEffect, updateElementBase, updateLocales, updateMeta, updateSettings };
-//# sourceMappingURL=chunk-GMGB7NIL.js.map
-//# sourceMappingURL=chunk-GMGB7NIL.js.map
+// src/plugin-host.ts
+var SLOT_KEYS = {
+  toolbar: "toolbarItems",
+  panel: "panels",
+  inspector: "inspectors"
+};
+function viewsFor(plugin, slot) {
+  if (slot === "toolbar") return plugin.toolbarItems ?? {};
+  if (slot === "panel") return plugin.panels ?? {};
+  return plugin.inspectors ?? {};
+}
+function validateEditorPlugin(plugin) {
+  const issues = [];
+  const { id, capabilities, editor } = plugin.manifest;
+  if (!capabilities.includes("editor")) {
+    issues.push({ pluginId: id, message: "editor capability\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4." });
+  }
+  for (const slot of ["toolbar", "panel", "inspector"]) {
+    const declared = new Set(editor?.[SLOT_KEYS[slot]] ?? []);
+    const implemented = new Set(Object.keys(viewsFor(plugin, slot)));
+    for (const viewId of declared) {
+      if (!implemented.has(viewId)) {
+        issues.push({
+          pluginId: id,
+          message: `${slot} ${viewId} \uAD6C\uD604\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.`
+        });
+      }
+    }
+    for (const viewId of implemented) {
+      if (!declared.has(viewId)) {
+        issues.push({
+          pluginId: id,
+          message: `${slot} ${viewId}\uAC00 manifest\uC5D0 \uC5C6\uC2B5\uB2C8\uB2E4.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function permissionError(pluginId, permission) {
+  return new Error(
+    `Editor plugin ${pluginId}\uC5D0\uB294 ${permission} \uAD8C\uD55C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.`
+  );
+}
+function createEditorPluginContext(pluginId, permissions, state2) {
+  return Object.freeze({
+    pluginId,
+    getDocument() {
+      if (!permissions.documentRead)
+        throw permissionError(pluginId, "documentRead");
+      const document2 = state2.getDocument();
+      if (!document2) throw new Error("\uC5F4\uB9B0 \uC560\uB2C8\uBA54\uC774\uC158\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+      return structuredClone(document2);
+    },
+    replaceDocument(document2) {
+      if (!permissions.documentWrite)
+        throw permissionError(pluginId, "documentWrite");
+      state2.replaceDocument(structuredClone(document2));
+    },
+    getSelection() {
+      if (!permissions.documentRead)
+        throw permissionError(pluginId, "documentRead");
+      return structuredClone(state2.getSelection());
+    },
+    setSelection(selection) {
+      if (!permissions.documentWrite)
+        throw permissionError(pluginId, "documentWrite");
+      state2.setSelection(structuredClone(selection));
+    }
+  });
+}
+function mountEditorPlugins(root, plugins, resolvePermissions, state2) {
+  const cleanups = [];
+  const commands = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    const { id } = plugin.manifest;
+    if (seen.has(id))
+      throw new Error(`Editor plugin ${id}\uAC00 \uC911\uBCF5 \uB4F1\uB85D\uB418\uC5C8\uC2B5\uB2C8\uB2E4.`);
+    seen.add(id);
+    const issues = validateEditorPlugin(plugin);
+    if (issues.length > 0)
+      throw new Error(issues.map((issue) => issue.message).join(" "));
+    const permissions = resolvePermissions(plugin.manifest);
+    if (!permissions.ui) continue;
+    const context = createEditorPluginContext(id, permissions, state2);
+    commands.push(...plugin.commands ?? []);
+    for (const slot of ["toolbar", "panel", "inspector"]) {
+      const target = root.querySelector(
+        `[data-editor-plugin-slot="${slot}"]`
+      );
+      if (!target) continue;
+      for (const viewId of plugin.manifest.editor?.[SLOT_KEYS[slot]] ?? []) {
+        const view = viewsFor(plugin, slot)[viewId];
+        if (!view) continue;
+        const container = document.createElement(
+          slot === "toolbar" ? "span" : "section"
+        );
+        container.dataset.editorPlugin = id;
+        container.dataset.editorPluginView = viewId;
+        container.setAttribute("aria-label", view.label);
+        target.append(container);
+        const cleanup = view.mount(container, context);
+        if (cleanup) cleanups.push(cleanup);
+      }
+    }
+  }
+  return {
+    commands,
+    dispose() {
+      cleanups.reverse().forEach((cleanup) => cleanup());
+      root.querySelectorAll("[data-editor-plugin]").forEach((element) => element.remove());
+    }
+  };
+}
+
+export { addAppearance, addCameraFocus, addChapter, addCheckpoint, addEffect, addElement, animationDocumentFileName, animationDocumentToJson, apiBaseUrl, beginTransient, cameraControlAt, canRedo, canUndo, childIdsOf, clearCamera, configureAnimationRepository, configureApi, configureHost, createAnimation, createEditorPluginContext, createLayout, deleteAnimation, deleteCameraFocus, deleteChapter, deleteCheckpoint, deleteEffect, deleteElement, detachFromLayout, downloadAnimationJson, duplicateAnimation, endTransient, findContainingGroup, findLayoutCollisions, garbageCollectAnimationAssets, getCamera, getCurrentSnapshot, getCurrentTime, getDef, getHistory, getSelectedElementIds, getSelection, groupBbox, groupElements, hasCamera, importAnimation, isDirty, isDraft, isElementSelected, isGroup, jumpBack, jumpForward, layoutIdsFor, listAnimations, loadAnimation, markClean, mountEditorPlugins, moveCameraKeyframe, moveElementToEnd, moveElementToFront, moveGroupBy, placeholderImageUrl, promoteDraftToSaved, redo, registerDataUriAsset, registerExternalAsset, registerInlineAsset, removeAppearance, removeCameraKeyframe, removeCameraTrack, removeTrack, removeTrackKeyframe, reorderElement, resetHistory, saveAnimation, setCameraKeyframe, setCameraStrokeScaling, setCurrentTime, setDef, setDraft, setElementValueAtTime, setSelection, setTrackKeyframe, subscribe, toggleSelectionFor, undo, ungroupElement, uniqueChapterId, uniqueCheckpointId, uniqueEffectId, uniqueElementId, updateAppearance, updateCameraFocus, updateCanvas, updateChapter, updateCheckpoint, updateData, updateDuration, updateEffect, updateElementBase, updateLocales, updateMeta, updateResponsive, updateSettings, validateEditorPlugin };
+//# sourceMappingURL=chunk-N47HF4VB.js.map
+//# sourceMappingURL=chunk-N47HF4VB.js.map