@pixel-point/toolcraft 0.0.8 → 0.0.11

package/templates/runtime/schema/define-toolcraft.ts

@@ -3,6 +3,7 @@ import {
   getToolcraftCanvasAspectRatioPreset,
   getToolcraftCanvasAspectRatioPresetBySize,
 } from "./canvas-aspect-ratio-presets";
+import { toolcraftTimelinePanelExtendedTarget } from "./runtime-targets";
 import type {
   ToolcraftAssemblyCapability,
   ToolcraftAssemblyCommand,
@@ -33,6 +34,7 @@ const defaultCanvasSize = {
 
 type ResolvedCanvas = ResolvedToolcraftAppSchema["canvas"];
 type ResolvedExport = ResolvedToolcraftAppSchema["export"];
+type ResolvedMedia = ResolvedToolcraftAppSchema["media"];
 type ResolvedToolbar = Required<ToolcraftToolbarSchema>;
 type PanelContract = {
   capabilities?: readonly string[];
@@ -47,6 +49,9 @@ const canvasSizeControlTargets = {
 } as const;
 const canvasAspectRatioTarget = "canvas.aspectRatio";
 const canvasRenderScaleTarget = "canvas.renderScale";
+const defaultTimelineDurationSeconds = 8;
+const minTimelineDurationSeconds = 1;
+const maxTimelineDurationSeconds = 60;
 const defaultCanvasRenderScale = {
   defaultValue: 2,
   enabled: false,
@@ -57,33 +62,6 @@ const defaultCanvasRenderScale = {
 const maxAutoInlineControlLabelLength = 18;
 const settingsTransferTarget = "runtime.settingsTransfer";
 const runtimeSetupSectionTitle = "Setup";
-const settingsTransferHeavyControlTypes = new Set([
-  "channelMixer",
-  "code",
-  "collectionActions",
-  "colorOpacity",
-  "curves",
-  "fileDrop",
-  "fontPicker",
-  "gradient",
-  "imagePicker",
-  "palette",
-  "rangeSlider",
-  "vector",
-]);
-
-export type ToolcraftSettingsTransferEligibilityReason =
-  | "control-count"
-  | "score"
-  | "section-count";
-
-export type ToolcraftSettingsTransferEligibility = {
-  controlCount: number;
-  eligible: boolean;
-  reasons: ToolcraftSettingsTransferEligibilityReason[];
-  score: number;
-  sectionCount: number;
-};
 
 type ToolcraftControlActionSchema = NonNullable<
   ToolcraftControlSchema["actions"]
@@ -193,7 +171,7 @@ function resolveCanvasSizing(
   }
 
   if (canvas.upload) {
-    return { mode: "intrinsic-media" };
+    return { mode: "editable-output" };
   }
 
   return { mode: "intrinsic-media" };
@@ -257,6 +235,12 @@ function resolveExport(
   };
 }
 
+function resolveMedia(mediaSchema: ToolcraftAppSchema["media"]): ResolvedMedia {
+  return {
+    defaultAssets: mediaSchema?.defaultAssets ?? [],
+  };
+}
+
 function getPanelDragMode(
   contract: { capabilities?: readonly string[] },
 ): ToolcraftAssemblyPanelContract["dragMode"] {
@@ -283,7 +267,12 @@ function createPanelAssemblyContract({
       ])
     : [];
   const panelCommands = enabled
-    ? unique<ToolcraftAssemblyCommand>(["panels.setOffset", "panels.resetOffset", ...commands])
+    ? unique<ToolcraftAssemblyCommand>([
+        "panels.setOffset",
+        "panels.setHidden",
+        "panels.resetOffset",
+        ...commands,
+      ])
     : [];
 
   return {
@@ -332,7 +321,7 @@ function createToolcraftAssembly({
 
     if (canvas.upload) {
       capabilities.push("canvas.upload");
-      commands.push("media.delete", "media.import", "media.reorder");
+      commands.push("media.delete", "media.import", "media.reorder", "media.transform");
     }
   }
 
@@ -479,7 +468,12 @@ function createToolcraftAssembly({
                 ? (["canvas.panBy", "canvas.setOffset", "canvas.setViewport"] as const)
                 : []),
               ...(canvas.upload
-                ? (["media.delete", "media.import", "media.reorder"] as const)
+                ? ([
+                    "media.delete",
+                    "media.import",
+                    "media.reorder",
+                    "media.transform",
+                  ] as const)
                 : []),
             ])
           : [],
@@ -496,15 +490,6 @@ function createToolcraftAssembly({
   };
 }
 
-function hasControlTarget(
-  panels: ToolcraftAppSchema["panels"],
-  target: string,
-): boolean {
-  return (panels.controls?.sections ?? []).some((section) =>
-    Object.values(section.controls).some((control) => control.target === target),
-  );
-}
-
 function getControlDefaultSectionLayout(
   control: ToolcraftControlSchema,
 ): "grouped" | "standalone" {
@@ -524,6 +509,10 @@ function getControlSectionLayout(
   control: ToolcraftControlSchema,
   entries: readonly [string, ToolcraftControlSchema][],
 ): "grouped" | "standalone" {
+  if (isControlGatedBySameSectionControl(control, entries)) {
+    return "grouped";
+  }
+
   if (
     (control.type === "color" || control.type === "colorOpacity") &&
     entries.some(
@@ -539,6 +528,24 @@ function getControlSectionLayout(
   return getControlDefaultSectionLayout(control);
 }
 
+function isControlGatedBySameSectionControl(
+  control: ToolcraftControlSchema,
+  entries: readonly [string, ToolcraftControlSchema][],
+): boolean {
+  const gateTargets = [control.visibleWhen?.target, control.disabledWhen?.target].filter(
+    (target): target is string => Boolean(target),
+  );
+
+  if (gateTargets.length === 0) {
+    return false;
+  }
+
+  return entries.some(([, entryControl]) =>
+    gateTargets.includes(entryControl.target) &&
+    getControlDefaultSectionLayout(entryControl) === "grouped",
+  );
+}
+
 function createControlsRecord(
   entries: readonly [string, ToolcraftControlSchema][],
 ): Record<string, ToolcraftControlSchema> {
@@ -615,116 +622,12 @@ function isPanelActionsControl(control: ToolcraftControlSchema): boolean {
   return control.type === "panelActions";
 }
 
-function isSettingsTransferControl(control: ToolcraftControlSchema): boolean {
-  return control.type === "settingsTransfer";
-}
-
-function isRuntimeOnlyActionControl(control: ToolcraftControlSchema): boolean {
-  return isPanelActionsControl(control) || isSettingsTransferControl(control);
-}
-
-function isSettingsTransferEligibilityControl(control: ToolcraftControlSchema): boolean {
-  return (
-    !isRuntimeOnlyActionControl(control) &&
-    control.target !== canvasAspectRatioTarget &&
-    control.target !== canvasSizeControlTargets.width &&
-    control.target !== canvasSizeControlTargets.height
-  );
-}
-
-function getSettingsTransferComplexityScore({
-  panels,
-}: {
-  panels: ToolcraftAppSchema["panels"];
-}): {
-  controlCount: number;
-  score: number;
-  sectionCount: number;
-} {
-  const sections = panels.controls?.sections ?? [];
-  let controlCount = 0;
-  let score = 0;
-
-  for (const section of sections) {
-    for (const control of Object.values(section.controls)) {
-      if (!isSettingsTransferEligibilityControl(control)) {
-        continue;
-      }
-
-      controlCount += 1;
-      score += settingsTransferHeavyControlTypes.has(control.type) ? 3 : 1;
-    }
-  }
-
-  const sectionCount = sections.filter((section) =>
-    Object.values(section.controls).some((control) =>
-      isSettingsTransferEligibilityControl(control),
-    ),
-  ).length;
-
-  score += Math.max(0, sectionCount - 4);
-
-  if (
-    panels.timeline === true ||
-    (typeof panels.timeline === "object" && panels.timeline.enabled !== false)
-  ) {
-    score += 2;
-  }
-
-  if (panels.layers) {
-    score += 2;
-  }
-
-  return { controlCount, score, sectionCount };
-}
-
-export function getToolcraftSettingsTransferEligibility({
-  panels,
-}: {
-  panels: ToolcraftAppSchema["panels"];
-}): ToolcraftSettingsTransferEligibility {
-  const { controlCount, score, sectionCount } = getSettingsTransferComplexityScore({
-    panels,
-  });
-  const reasons: ToolcraftSettingsTransferEligibilityReason[] = [];
-
-  if (controlCount >= 12) {
-    reasons.push("control-count");
-  }
-
-  if (sectionCount >= 5) {
-    reasons.push("section-count");
-  }
-
-  if (score >= 18) {
-    reasons.push("score");
-  }
-
-  return {
-    controlCount,
-    eligible: reasons.length > 0,
-    reasons,
-    score,
-    sectionCount,
-  };
-}
-
-function shouldAutoEnableSettingsTransfer({
-  panels,
-}: {
-  panels: ToolcraftAppSchema["panels"];
-}): boolean {
-  return getToolcraftSettingsTransferEligibility({ panels }).eligible;
-}
-
 function resolveSettingsTransfer({
   controls,
-  panels,
   persistence,
   settingsTransfer,
 }: {
   controls: ToolcraftControlsPanelSchema | undefined;
-  panels: ToolcraftAppSchema["panels"];
   persistence: ResolvedToolcraftAppSchema["persistence"];
   settingsTransfer: ToolcraftSettingsTransferSchema | undefined;
 }): ResolvedToolcraftSettingsTransferSchema {
@@ -737,9 +640,7 @@ function resolveSettingsTransfer({
 
   return {
     appId,
-    enabled:
-      Boolean(controls) &&
-      (mode === "auto" ? shouldAutoEnableSettingsTransfer({ panels }) : mode),
+    enabled: Boolean(controls),
     fileName: getSettingsTransferFileName({ appId, settingsTransfer }),
     mode,
   };
@@ -747,11 +648,7 @@ function resolveSettingsTransfer({
 
 function createSettingsTransferSection(
   settingsTransfer: ResolvedToolcraftSettingsTransferSchema,
-): ToolcraftControlSectionSchema | null {
-  if (!settingsTransfer.enabled) {
-    return null;
-  }
-
+): ToolcraftControlSectionSchema {
   return {
     controls: {
       settingsTransfer: {
@@ -808,51 +705,20 @@ function getCanvasAspectRatioDefaultValue(size: ToolcraftCanvasSize): {
   };
 }
 
-function createCanvasSizeSection({
-  aspectRatioControl,
-  renderScaleControl,
-  sizeControlIds,
-  sizeControls,
-}: {
-  aspectRatioControl: ToolcraftControlSchema;
-  renderScaleControl?: ToolcraftControlSchema;
-  sizeControlIds: readonly string[];
-  sizeControls: ToolcraftControlSectionSchema["controls"];
-}): ToolcraftControlSectionSchema {
-  return {
-    controls: {
-      canvasAspectRatio: aspectRatioControl,
-      ...sizeControls,
-      ...(renderScaleControl ? { canvasRenderScale: renderScaleControl } : {}),
-    },
-    layoutGroups: getCanvasSizeLayoutGroups(sizeControlIds),
-    title: runtimeSetupSectionTitle,
-  };
-}
-
-function createCanvasRenderScaleSection(
-  renderScaleControl: ToolcraftControlSchema,
-): ToolcraftControlSectionSchema {
-  return {
-    controls: {
-      canvasRenderScale: renderScaleControl,
-    },
-    title: runtimeSetupSectionTitle,
-  };
-}
-
 function mergeCanvasSizeControlsIntoSettingsTransferSection({
   aspectRatioControl,
   renderScaleControl,
   settingsTransferSection,
   sizeControlIds,
   sizeControls,
+  timelineExtendedControl,
 }: {
   aspectRatioControl: ToolcraftControlSchema;
   renderScaleControl?: ToolcraftControlSchema;
   settingsTransferSection: ToolcraftControlSectionSchema;
   sizeControlIds: readonly string[];
   sizeControls: ToolcraftControlSectionSchema["controls"];
+  timelineExtendedControl?: ToolcraftControlSchema;
 }): ToolcraftControlSectionSchema {
   const canvasSizeLayoutGroups = getCanvasSizeLayoutGroups(sizeControlIds) ?? [];
 
@@ -863,6 +729,7 @@ function mergeCanvasSizeControlsIntoSettingsTransferSection({
       canvasAspectRatio: aspectRatioControl,
       ...sizeControls,
       ...(renderScaleControl ? { canvasRenderScale: renderScaleControl } : {}),
+      ...(timelineExtendedControl ? { timelineExtended: timelineExtendedControl } : {}),
     },
     layoutGroups:
       canvasSizeLayoutGroups.length > 0 || settingsTransferSection.layoutGroups?.length
@@ -877,15 +744,34 @@ function mergeCanvasSizeControlsIntoSettingsTransferSection({
 function mergeCanvasRenderScaleIntoSettingsTransferSection({
   renderScaleControl,
   settingsTransferSection,
+  timelineExtendedControl,
 }: {
   renderScaleControl: ToolcraftControlSchema;
   settingsTransferSection: ToolcraftControlSectionSchema;
+  timelineExtendedControl?: ToolcraftControlSchema;
 }): ToolcraftControlSectionSchema {
   return {
     ...settingsTransferSection,
     controls: {
       ...settingsTransferSection.controls,
       canvasRenderScale: renderScaleControl,
+      ...(timelineExtendedControl ? { timelineExtended: timelineExtendedControl } : {}),
+    },
+  };
+}
+
+function mergeTimelineExtendedIntoSettingsTransferSection({
+  settingsTransferSection,
+  timelineExtendedControl,
+}: {
+  settingsTransferSection: ToolcraftControlSectionSchema;
+  timelineExtendedControl: ToolcraftControlSchema;
+}): ToolcraftControlSectionSchema {
+  return {
+    ...settingsTransferSection,
+    controls: {
+      ...settingsTransferSection.controls,
+      timelineExtended: timelineExtendedControl,
     },
   };
 }
@@ -1410,7 +1296,7 @@ function normalizePanels({
   const controls = { ...panels.controls };
   const settingsTransferSection = createSettingsTransferSection(settingsTransfer);
   const renderScaleControl: ToolcraftControlSchema | undefined =
-    canvas.renderScale.enabled && !hasControlTarget(panels, canvasRenderScaleTarget)
+    canvas.renderScale.enabled
       ? {
           defaultValue: canvas.renderScale.defaultValue,
           description:
@@ -1428,27 +1314,41 @@ function normalizePanels({
           step: canvas.renderScale.step,
           target: canvasRenderScaleTarget,
           type: "slider",
-          unit: "x",
           variant: "discrete",
         }
       : undefined;
+  const timelineExtendedControl: ToolcraftControlSchema | undefined =
+    normalizedTimeline?.enabled
+      ? {
+          defaultValue: false,
+          description:
+            "Shows the extended runtime timeline with scrubber, duration, loop, and keyframe controls; compact mode keeps only Play visible.",
+          label: "Timeline",
+          target: toolcraftTimelinePanelExtendedTarget,
+          type: "switch",
+        }
+      : undefined;
 
   if (!canvas.enabled || canvas.sizing.mode !== "editable-output") {
-    const runtimeSetupSection =
-      settingsTransferSection && renderScaleControl
-        ? mergeCanvasRenderScaleIntoSettingsTransferSection({
-            renderScaleControl,
+    const runtimeSetupSection = renderScaleControl
+      ? mergeCanvasRenderScaleIntoSettingsTransferSection({
+          renderScaleControl,
+          settingsTransferSection,
+          timelineExtendedControl,
+        })
+      : timelineExtendedControl
+        ? mergeTimelineExtendedIntoSettingsTransferSection({
             settingsTransferSection,
+            timelineExtendedControl,
           })
-        : (settingsTransferSection ??
-          (renderScaleControl ? createCanvasRenderScaleSection(renderScaleControl) : null));
+        : settingsTransferSection;
 
     return {
       ...normalizedPanels,
       controls: normalizeControlsPanelLayout({
         ...controls,
         sections: [
-          ...(runtimeSetupSection ? [runtimeSetupSection] : []),
+          runtimeSetupSection,
           ...controls.sections,
         ],
       }),
@@ -1460,63 +1360,43 @@ function normalizePanels({
   const aspectRatioControl: ToolcraftControlSchema = {
     defaultValue: getCanvasAspectRatioDefaultValue(canvas.size),
     label: "Aspect ratio",
+    orderRole: "input",
     performanceReason: "Aspect ratio changes output dimensions and renderer workload.",
     performanceRole: "workload",
     target: canvasAspectRatioTarget,
     type: "aspectRatio",
   };
 
-  if (!hasControlTarget(panels, canvasSizeControlTargets.width)) {
-    sizeControls.canvasWidth = {
-      defaultValue: canvas.size.width,
-      label: "Canvas width",
-      performanceReason: "Canvas width changes output dimensions and renderer workload.",
-      performanceRole: "workload",
-      target: canvasSizeControlTargets.width,
-      type: "text",
-    };
-    sizeControlIds.push("canvasWidth");
-  }
-
-  if (!hasControlTarget(panels, canvasSizeControlTargets.height)) {
-    sizeControls.canvasHeight = {
-      defaultValue: canvas.size.height,
-      label: "Canvas height",
-      performanceReason: "Canvas height changes output dimensions and renderer workload.",
-      performanceRole: "workload",
-      target: canvasSizeControlTargets.height,
-      type: "text",
-    };
-    sizeControlIds.push("canvasHeight");
-  }
-
-  if (Object.keys(sizeControls).length === 0 && !renderScaleControl) {
-    return {
-      ...normalizedPanels,
-      controls: normalizeControlsPanelLayout({
-        ...controls,
-        sections: [
-          ...(settingsTransferSection ? [settingsTransferSection] : []),
-          ...controls.sections,
-        ],
-      }),
-    };
-  }
+  sizeControls.canvasWidth = {
+    defaultValue: canvas.size.width,
+    label: "Canvas width",
+    orderRole: "input",
+    performanceReason: "Canvas width changes output dimensions and renderer workload.",
+    performanceRole: "workload",
+    target: canvasSizeControlTargets.width,
+    type: "text",
+  };
+  sizeControlIds.push("canvasWidth");
 
-  const runtimeSettingsSection = settingsTransferSection
-    ? mergeCanvasSizeControlsIntoSettingsTransferSection({
-        aspectRatioControl,
-        renderScaleControl,
-        settingsTransferSection,
-        sizeControlIds,
-        sizeControls,
-      })
-    : createCanvasSizeSection({
-        aspectRatioControl,
-        renderScaleControl,
-        sizeControlIds,
-        sizeControls,
-      });
+  sizeControls.canvasHeight = {
+    defaultValue: canvas.size.height,
+    label: "Canvas height",
+    orderRole: "input",
+    performanceReason: "Canvas height changes output dimensions and renderer workload.",
+    performanceRole: "workload",
+    target: canvasSizeControlTargets.height,
+    type: "text",
+  };
+  sizeControlIds.push("canvasHeight");
+
+  const runtimeSettingsSection = mergeCanvasSizeControlsIntoSettingsTransferSection({
+    aspectRatioControl,
+    renderScaleControl,
+    settingsTransferSection,
+    sizeControlIds,
+    sizeControls,
+    timelineExtendedControl,
+  });
 
   return {
     ...normalizedPanels,
@@ -1536,7 +1416,11 @@ function resolveTimelinePanel(
   timeline: ToolcraftTimelinePanelSchema | undefined,
 ): ResolvedToolcraftTimelinePanelSchema | undefined {
   if (timeline === true) {
-    return { enabled: true, mode: "keyframes" };
+    return {
+      defaultDurationSeconds: defaultTimelineDurationSeconds,
+      enabled: true,
+      mode: "keyframes",
+    };
   }
 
   if (!timeline || timeline.enabled === false) {
@@ -1544,11 +1428,20 @@ function resolveTimelinePanel(
   }
 
   return {
+    defaultDurationSeconds: normalizeTimelineDurationSeconds(timeline.defaultDurationSeconds),
     enabled: true,
     mode: timeline.mode ?? "keyframes",
   };
 }
 
+function normalizeTimelineDurationSeconds(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return defaultTimelineDurationSeconds;
+  }
+
+  return Math.min(maxTimelineDurationSeconds, Math.max(minTimelineDurationSeconds, value));
+}
+
 function hasVisibleRuntimePanel({
   panels,
   toolbar,
@@ -1597,7 +1490,6 @@ export function defineToolcraft(schema: ToolcraftAppSchema): ResolvedToolcraftAp
   const persistence = resolvePersistence(schema.persistence);
   const settingsTransfer = resolveSettingsTransfer({
     controls: schema.panels.controls,
-    panels: schema.panels,
     persistence,
     settingsTransfer: schema.settingsTransfer,
   });
@@ -1622,6 +1514,7 @@ export function defineToolcraft(schema: ToolcraftAppSchema): ResolvedToolcraftAp
     zoom: schema.toolbar?.zoom ?? canvasEnabled,
   };
   const exportSchema = resolveExport(schema.export);
+  const media = resolveMedia(schema.media);
 
   assertPanelPersistenceContract({ panels, persistence, toolbar });
 
@@ -1633,6 +1526,7 @@ export function defineToolcraft(schema: ToolcraftAppSchema): ResolvedToolcraftAp
     }),
     canvas,
     export: exportSchema,
+    media,
     panels,
     persistence,
     settingsTransfer,

package/templates/runtime/schema/runtime-targets.ts

@@ -1,8 +1,14 @@
+export const toolcraftTimelinePanelVisibleTarget = "panels.timeline.visible";
+export const toolcraftTimelinePanelExtendedTarget = "panels.timeline.extended";
+
 export const toolcraftRuntimeOwnedTargets = [
   "canvas.aspectRatio",
   "canvas.renderScale",
   "canvas.size.width",
   "canvas.size.height",
+  "runtime.settingsTransfer",
+  toolcraftTimelinePanelExtendedTarget,
+  toolcraftTimelinePanelVisibleTarget,
 ] as const;
 
 export const toolcraftReservedTargets = [
@@ -33,6 +39,21 @@ export function isToolcraftCanvasAspectRatioTarget(target: string): boolean {
   return target === "canvas.aspectRatio";
 }
 
+export function isToolcraftTimelinePanelVisibleTarget(target: string): boolean {
+  return target === toolcraftTimelinePanelVisibleTarget;
+}
+
+export function isToolcraftTimelinePanelExtendedTarget(target: string): boolean {
+  return target === toolcraftTimelinePanelExtendedTarget;
+}
+
+export function isToolcraftTimelinePanelRuntimeTarget(target: string): boolean {
+  return (
+    isToolcraftTimelinePanelExtendedTarget(target) ||
+    isToolcraftTimelinePanelVisibleTarget(target)
+  );
+}
+
 export function isToolcraftReservedTarget(
   target: string,
 ): target is ToolcraftReservedTarget {