@pixel-point/toolcraft 0.0.14 → 0.0.15

package/templates/starter/src/app/acceptance/runtime-setup.ts

@@ -0,0 +1,117 @@
+import type { ResolvedToolcraftAppSchema } from "@repo/toolcraft-runtime";
+
+import { getToolcraftSectionLabel } from "./sections";
+
+const runtimeSetupControlTargets = new Set([
+  "runtime.settingsTransfer",
+  "canvas.aspectRatio",
+  "canvas.renderScale",
+  "canvas.size.width",
+  "canvas.size.height",
+  "panels.timeline.extended",
+]);
+
+export function isRuntimeSetupControlTarget(target: string): boolean {
+  return runtimeSetupControlTargets.has(target);
+}
+
+export function getToolcraftRuntimeSetupSectionErrors(
+  schema: ResolvedToolcraftAppSchema,
+): string[] {
+  const errors: string[] = [];
+  const controlsPanel = schema.panels.controls;
+
+  if (!controlsPanel) {
+    return [
+      "Generated Toolcraft apps must define a controls panel so the mandatory runtime Setup section is visible.",
+    ];
+  }
+
+  const sections = schema.panels.controls?.sections ?? [];
+
+  if (sections.length === 0) {
+    return [
+      'Runtime Setup must be the first visible controls-panel section titled "Setup". Do not ship an empty controls panel.',
+    ];
+  }
+
+  const setupSection = sections[0];
+  const setupTitle = setupSection?.title?.trim();
+  const setupControls = Object.values(setupSection?.controls ?? {});
+  const setupTargets = new Set(setupControls.map((control) => control.target));
+  const hasSetupTarget = (target: string) => setupTargets.has(target);
+
+  if (setupTitle !== "Setup") {
+    errors.push(
+      'Runtime Setup must be the first visible controls-panel section titled "Setup". Do not move Export Settings, Import Settings, canvas sizing, Resolution scale, or Timeline into app-authored sections.',
+    );
+  }
+
+  if (
+    !setupControls.some(
+      (control) =>
+        control.type === "settingsTransfer" &&
+        control.target === "runtime.settingsTransfer",
+    )
+  ) {
+    errors.push(
+      'Runtime Setup must include settingsTransfer at target "runtime.settingsTransfer" so Export Settings and Import Settings are always visible.',
+    );
+  }
+
+  if (schema.canvas.enabled && schema.canvas.sizing.mode === "editable-output") {
+    const missingCanvasTargets = [
+      "canvas.aspectRatio",
+      "canvas.size.width",
+      "canvas.size.height",
+    ].filter((target) => !hasSetupTarget(target));
+
+    if (missingCanvasTargets.length > 0) {
+      errors.push(
+        `Runtime Setup for editable-output canvas must include Aspect ratio, Canvas width, and Canvas height. Missing targets: ${missingCanvasTargets.join(", ")}.`,
+      );
+    }
+  }
+
+  if (schema.canvas.renderScale.enabled && !hasSetupTarget("canvas.renderScale")) {
+    errors.push(
+      'Runtime Setup must include Resolution scale at target "canvas.renderScale" whenever canvas.renderScale is enabled.',
+    );
+  }
+
+  if (schema.panels.timeline?.enabled) {
+    if (!hasSetupTarget("panels.timeline.extended")) {
+      errors.push(
+        'Runtime Setup must include the Timeline switch at target "panels.timeline.extended" whenever panels.timeline is enabled.',
+      );
+    }
+  } else if (
+    sections.some((section) =>
+      Object.values(section.controls).some(
+        (control) => control.target === "panels.timeline.extended",
+      ),
+    )
+  ) {
+    errors.push(
+      'Runtime Setup must not include the Timeline switch unless panels.timeline is enabled.',
+    );
+  }
+
+  for (const [sectionIndex, section] of sections.entries()) {
+    const isRuntimeSetupSection = sectionIndex === 0 && section.title?.trim() === "Setup";
+
+    for (const [controlId, control] of Object.entries(section.controls)) {
+      if (!isRuntimeSetupControlTarget(control.target) || isRuntimeSetupSection) {
+        continue;
+      }
+
+      const sectionLabel = getToolcraftSectionLabel(section.title, sectionIndex);
+
+      errors.push(
+        `${sectionLabel} / ${controlId} uses runtime Setup target "${control.target}". Runtime Setup owns Export Settings, Import Settings, Aspect ratio, Canvas width, Canvas height, Resolution scale, and Timeline; do not declare these controls in app-authored sections.`,
+      );
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/section-title-rules.ts

@@ -0,0 +1,8 @@
+export const genericControlSectionTitlePattern =
+  /^(controls?|settings?|parameters?|options?|configuration|config|adjustments?)$/i;
+
+export const controlTypeSectionTitlePattern =
+  /^(sliders?|colors?|colours?|inputs?|selects?|switches?|checkboxes?|toggles?|buttons?|actions?)$/i;
+
+export const weakControlLabelContextSectionTitlePattern =
+  /^(appearance|look|looks|properties?|style|styles|values?|visuals?)$/i;

package/templates/starter/src/app/acceptance/sections.ts

@@ -0,0 +1,6 @@
+export function getToolcraftSectionLabel(
+  sectionTitle: string | undefined,
+  sectionIndex: number,
+): string {
+  return sectionTitle?.trim() || `untitled section ${sectionIndex + 1}`;
+}

package/templates/starter/src/app/acceptance/semantic.ts

@@ -0,0 +1,63 @@
+export function humanizeToolcraftLabelPart(value: string): string {
+  const text = value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!text) {
+    return "";
+  }
+
+  return text.replace(/\b([a-z])/g, (match) => match.toUpperCase());
+}
+
+export function lowerCaseToolcraftLabelStart(value: string): string {
+  return value ? `${value.charAt(0).toLowerCase()}${value.slice(1)}` : value;
+}
+
+export function normalizeToolcraftSemanticText(value: string | undefined): string {
+  return humanizeToolcraftLabelPart(value ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "");
+}
+
+export function getToolcraftTargetParts(target: string): string[] {
+  return target.split(".").filter(Boolean);
+}
+
+export function getToolcraftTargetProperty(target: string): string {
+  return getToolcraftTargetParts(target).at(-1) ?? "";
+}
+
+export function getToolcraftStrictTargetPrefix(target: string): string | null {
+  const parts = getToolcraftTargetParts(target);
+
+  if (parts.length < 3) {
+    return null;
+  }
+
+  const prefix = parts.slice(0, -1).join(".");
+
+  if (prefix === "canvas.size") {
+    return null;
+  }
+
+  return prefix;
+}
+
+export function getToolcraftLooseTargetPrefix(target: string): string | null {
+  const parts = getToolcraftTargetParts(target);
+
+  if (parts.length < 2) {
+    return null;
+  }
+
+  const prefix = parts.slice(0, -1).join(".");
+
+  if (prefix === "canvas.size") {
+    return null;
+  }
+
+  return prefix;
+}

package/templates/starter/src/app/acceptance/timeline-loop.ts

@@ -0,0 +1,21 @@
+import type {
+  ToolcraftAnimationIntent,
+  ToolcraftTimelineLoopDurationIntent,
+} from "./types";
+
+export function getTimelineLoopDurationIntent(
+  animationIntent: ToolcraftAnimationIntent | undefined,
+): ToolcraftTimelineLoopDurationIntent | undefined {
+  if (
+    animationIntent?.mode !== "timeline-playback" &&
+    animationIntent?.mode !== "timeline-keyframes"
+  ) {
+    return undefined;
+  }
+
+  return animationIntent.loopDuration;
+}
+
+export function isValidTimelineLoopDurationSource(source: string): boolean {
+  return source === "reference" || source === "user-request" || source === "product-derived";
+}

package/templates/starter/src/app/acceptance/types.ts

@@ -0,0 +1,363 @@
+import type {
+  ToolcraftBuiltInControlType as RuntimeToolcraftBuiltInControlType,
+  ToolcraftControlOrderRole,
+  ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+import { TOOLCRAFT_BUILT_IN_CONTROL_TYPES } from "@repo/toolcraft-runtime";
+
+export type ToolcraftAcceptanceEvidence =
+  | "command-side-effect"
+  | "exported-bytes"
+  | "media-lifecycle"
+  | "persistence-state"
+  | "product-output"
+  | "rendered-pixels"
+  | "timeline-output"
+  | "viewport-side-effect";
+
+export type ToolcraftReferenceCoverage =
+  | "canvas-sizing"
+  | "control-mapping"
+  | "export-at-time"
+  | "export-copy"
+  | "media-lifecycle"
+  | "pause-resume"
+  | "renderer-loop"
+  | "renderer-state"
+  | "restart"
+  | "spawn-update-cadence"
+  | "time-progress";
+
+export type ToolcraftReferenceTimelineCoverage =
+  | "all-range"
+  | "duration"
+  | "export-at-time"
+  | "export-range"
+  | "jump-to-trim-start"
+  | "keyframes"
+  | "loop"
+  | "playback"
+  | "range-playback"
+  | "restart"
+  | "scrub"
+  | "state-jump"
+  | "time-progress"
+  | "trim-range";
+
+export type ToolcraftTimelinePlaybackCoverage =
+  | "duration"
+  | "loop"
+  | "pause-resume"
+  | "rendered-frame"
+  | "scrub";
+
+export type ToolcraftCanvasSizingCoverage = "fixed-output-size" | "intrinsic-media-size";
+
+export type ToolcraftPersistenceCoverage = "reload";
+
+export type ToolcraftSettingsTransferCoverage = "opt-out";
+
+export type ToolcraftConditionalVisibilityCoverage = "hidden" | "visible";
+
+export type ToolcraftBackgroundOutputCoverage =
+  | "image-transparent-when-excluded"
+  | "preview-hidden-when-excluded"
+  | "video-background-preserved";
+
+export type ToolcraftMediaLifecycleCoverage =
+  | "default-remove"
+  | "default-reset"
+  | "flip"
+  | "order-output"
+  | "remove"
+  | "reorder"
+  | "reset"
+  | "rotate"
+  | "transform-output"
+  | "upload";
+
+export type ToolcraftAutonomousAnimationCoverage =
+  | "no-duration-control"
+  | "no-export-at-time"
+  | "no-loop-control"
+  | "no-play-pause"
+  | "no-scrub"
+  | "no-user-facing-transport";
+
+export type ToolcraftTimelineLoopDurationSource =
+  | "product-derived"
+  | "reference"
+  | "user-request";
+
+export type ToolcraftTimelineLoopDurationIntent = {
+  evidence: string;
+  seconds: number;
+  source: ToolcraftTimelineLoopDurationSource;
+};
+
+export type ToolcraftTimelineLoopProof = {
+  direction: "forward-only";
+  durationChange: "reproved-after-edit";
+  reversePlayback: "forbidden";
+  seam: "first-last-match";
+};
+
+export type ToolcraftAnimationIntent =
+  | {
+      mode: "none";
+    }
+  | {
+      behaviorCoverage: readonly ToolcraftAutonomousAnimationCoverage[];
+      mode: "autonomous";
+      reason: string;
+    }
+  | {
+      loopDuration: ToolcraftTimelineLoopDurationIntent;
+      mode: "timeline-keyframes";
+    }
+  | {
+      loopDuration: ToolcraftTimelineLoopDurationIntent;
+      mode: "timeline-playback";
+    };
+
+export type ToolcraftReferenceTimelineMode =
+  | "custom-reference-timeline"
+  | "none"
+  | "toolcraft-keyframes"
+  | "toolcraft-playback";
+
+export type ToolcraftReferenceTimelineContract = {
+  behaviorCoverage: readonly ToolcraftReferenceTimelineCoverage[];
+  loopDuration?: ToolcraftTimelineLoopDurationIntent;
+  mode: ToolcraftReferenceTimelineMode;
+};
+
+export type ToolcraftReferenceStudyStatus =
+  | "ran-original"
+  | "restored-local"
+  | "source-inspection-only";
+
+export type ToolcraftReferenceStudyEvidence = {
+  behaviorEvidence: string;
+  referenceLocation: string;
+  reproductionSteps: string;
+  sourceEvidence: string;
+  sourceOnlyReason?: string;
+  status: ToolcraftReferenceStudyStatus;
+};
+
+export type ToolcraftVideoReferenceStoryboardFrame = {
+  behaviorObservation: string;
+  frameId: string;
+  frameSource: string;
+  timeSeconds: number;
+  visualObservation: string;
+};
+
+export type ToolcraftVideoReferenceTransition = {
+  behaviorDelta: string;
+  fromFrameId: string;
+  id: string;
+  toFrameId: string;
+};
+
+export type ToolcraftVideoReferenceAcceptanceMapping = {
+  acceptanceId: string;
+  behavior: string;
+  frameIds: readonly string[];
+};
+
+export type ToolcraftVideoReferenceStudyEvidence = {
+  acceptanceMapping: readonly ToolcraftVideoReferenceAcceptanceMapping[];
+  behaviorDecomposition: string;
+  extractionEvidence: string;
+  referenceLocation: string;
+  storyboard: readonly ToolcraftVideoReferenceStoryboardFrame[];
+  transitionAnalysis: readonly ToolcraftVideoReferenceTransition[];
+};
+
+export type ToolcraftReferenceFeatureStatus =
+  | "intentionally-changed"
+  | "ported"
+  | "toolcraft-native";
+
+export type ToolcraftReferenceFeatureInventoryItem = {
+  acceptanceId: string;
+  behaviorEvidence: string;
+  featureName: string;
+  id: string;
+  referenceBehavior: string;
+  sourceEvidence: string;
+  status: ToolcraftReferenceFeatureStatus;
+  toolcraftMapping: string;
+  userApprovedChangeReason?: string;
+};
+
+export type ToolcraftLayerCoverage =
+  | "grouping"
+  | "media-lifecycle"
+  | "reorder"
+  | "selected-layer-controls"
+  | "selection"
+  | "visibility";
+
+export type ToolcraftControlPartCoverage =
+  | "anchorGrid.position"
+  | "channelMixer.activeChannel"
+  | "channelMixer.values"
+  | "curves.activeChannel"
+  | "curves.points"
+  | "colorOpacity.hex"
+  | "colorOpacity.opacity"
+  | "fontPicker.color"
+  | "fontPicker.fontId"
+  | "fontPicker.fontSize"
+  | "fontPicker.fontWeight"
+  | "fontPicker.letterSpacing"
+  | "fontPicker.lineHeight"
+  | "fontPicker.opacity"
+  | "fontPicker.textCase"
+  | "gradient.angle"
+  | "gradient.gradientType"
+  | "gradient.stops.color"
+  | "gradient.stops.opacity"
+  | "gradient.stops.position"
+  | "palette.family"
+  | "palette.shade"
+  | "rangeInput.end"
+  | "rangeInput.start"
+  | "rangeSlider.lower"
+  | "rangeSlider.upper"
+  | "vector.x"
+  | "vector.y";
+
+export type ToolcraftCustomControlCoverage =
+  | "built-in-gap"
+  | "kit-primitives"
+  | "minimal-ui"
+  | "product-output"
+  | "runtime-state";
+
+export const builtInToolcraftControlTypeValues =
+  TOOLCRAFT_BUILT_IN_CONTROL_TYPES;
+
+export type ToolcraftBuiltInControlType = RuntimeToolcraftBuiltInControlType;
+
+export type ToolcraftBuiltInFitCheck = {
+  capabilities: readonly ToolcraftCustomControlCapability[];
+  checkedBuiltIns: readonly ToolcraftBuiltInControlType[];
+  closestBuiltIn: ToolcraftBuiltInControlType | "none";
+  productObservable: string;
+  whyInsufficient: string;
+};
+
+export type ToolcraftCustomControlCapability =
+  | "collection"
+  | "commands"
+  | "custom-interaction"
+  | "custom-value-model"
+  | "custom-visualization"
+  | "reorder"
+  | "selection";
+
+export type ToolcraftTransferMode =
+  | {
+      animationIntent?: ToolcraftAnimationIntent;
+      mode: "new-toolcraft-app";
+      videoReferenceStudy?: ToolcraftVideoReferenceStudyEvidence;
+    }
+  | {
+      animationIntent?: ToolcraftAnimationIntent;
+      behaviorCoverage: readonly ToolcraftReferenceCoverage[];
+      mode: "reference-runtime-clone";
+      referenceFeatureInventory?: readonly ToolcraftReferenceFeatureInventoryItem[];
+      referenceName: string;
+      referenceStudy?: ToolcraftReferenceStudyEvidence;
+      referenceTimeline: ToolcraftReferenceTimelineContract;
+      sourceOfTruth: "reference-runtime";
+      videoReferenceStudy?: ToolcraftVideoReferenceStudyEvidence;
+    };
+
+export type ToolcraftProductReadiness =
+  | {
+      mode: "starter";
+      reason: string;
+    }
+  | {
+      mode: "product";
+      productName: string;
+      productSummary: string;
+      requestedBehavior: string;
+    };
+
+export type ToolcraftComponentAcceptance = {
+  actionCoverage?: readonly string[];
+  automated: boolean;
+  automatedTestName: string;
+  browser: boolean;
+  browserTestName: string;
+  componentType: string;
+  evidence: ToolcraftAcceptanceEvidence;
+  expectedObservable: string;
+  fixture: string;
+  id: string;
+  canvasHandle?: {
+    exportCleanTestName: string;
+    outputObservable: string;
+    testId: string;
+    writesTarget: string;
+  };
+  kind: "canvas-handle" | "control" | "runtime";
+  canvasSizingCoverage?: ToolcraftCanvasSizingCoverage;
+  layerCoverage?: ToolcraftLayerCoverage;
+  mediaLifecycleCoverage?: readonly ToolcraftMediaLifecycleCoverage[];
+  optionCoverage?: "each-visible-item" | readonly string[];
+  persistenceCoverage?: ToolcraftPersistenceCoverage;
+  referenceCoverage?: ToolcraftReferenceCoverage;
+  referenceTimelineCoverage?: ToolcraftReferenceTimelineCoverage;
+  settingsTransferCoverage?: ToolcraftSettingsTransferCoverage;
+  target?: string;
+  timelineCoverage?: "keyframes" | "playback";
+  timelinePlaybackCoverage?:
+    | "all-playback-behavior"
+    | readonly ToolcraftTimelinePlaybackCoverage[];
+  timelineLoopProof?: ToolcraftTimelineLoopProof;
+  controlPartCoverage?:
+    | "all-visible-parts"
+    | readonly ToolcraftControlPartCoverage[];
+  customControlCoverage?:
+    | "all-custom-control-behavior"
+    | readonly ToolcraftCustomControlCoverage[];
+  builtInFitCheck?: ToolcraftBuiltInFitCheck;
+  backgroundOutputCoverage?:
+    | "all-required-background-output"
+    | readonly ToolcraftBackgroundOutputCoverage[];
+  userAction: string;
+  visibilityCoverage?:
+    | "all-conditional-visibility"
+    | readonly ToolcraftConditionalVisibilityCoverage[];
+};
+
+export type ToolcraftVisibleControl = {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  sectionTitle?: string;
+};
+
+export type ToolcraftControlOrderItem = {
+  controlId: string;
+  rank: number;
+  role: ToolcraftControlOrderRole;
+  sectionTitle?: string;
+  target: string;
+  type: string;
+};
+
+export type ToolcraftControlSectionInventoryEntry = {
+  entity?: string;
+  groupingReason: string;
+  splitReason?: string;
+  targets: readonly string[];
+  title: string;
+  workflowStage?: string;
+};