@pixel-point/toolcraft 0.0.13 → 0.0.15

package/templates/starter/src/app/acceptance/output-export-model.ts

@@ -0,0 +1,146 @@
+import type {
+  ResolvedToolcraftAppSchema,
+  ToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+
+import { getControlLabelText } from "./controls";
+import { normalizeToolcraftSemanticText } from "./semantic";
+
+export type ToolcraftControlsSection = NonNullable<
+  ResolvedToolcraftAppSchema["panels"]["controls"]
+>["sections"][number];
+
+export type ToolcraftOutputExportFacts = {
+  backgroundColorEntry: readonly [string, ToolcraftControlSchema] | undefined;
+  backgroundSection: ToolcraftControlsSection | undefined;
+  backgroundSectionIndex: number;
+  expectedOutputSettingsIndex: number;
+  finalExportSettingsIndex: number;
+  hasVideoExportAction: boolean;
+  imageExportSection: ToolcraftControlsSection | undefined;
+  imageExportSectionIndex: number;
+  imageFormatEntry: readonly [string, ToolcraftControlSchema] | undefined;
+  imageResolutionEntry: readonly [string, ToolcraftControlSchema] | undefined;
+  includeBackgroundEntry: readonly [string, ToolcraftControlSchema] | undefined;
+  panelActionsSectionIndex: number;
+  videoExportSectionIndex: number;
+};
+
+export function getSearchableControlText({
+  control,
+  controlId,
+  sectionTitle,
+}: {
+  control: ToolcraftControlSchema;
+  controlId: string;
+  sectionTitle?: string | undefined;
+}): string {
+  return [
+    sectionTitle ?? "",
+    controlId,
+    control.target,
+    getControlLabelText(control),
+  ]
+    .join(" ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2");
+}
+
+function getFirstPanelActionsSectionIndex(schema: ResolvedToolcraftAppSchema): number {
+  return (schema.panels.controls?.sections ?? []).findIndex((section) =>
+    Object.values(section.controls).some((control) => control.type === "panelActions"),
+  );
+}
+
+function getSchemaControlsSectionByTitle(
+  schema: ResolvedToolcraftAppSchema,
+  title: string,
+): ToolcraftControlsSection | undefined {
+  const normalizedTitle = normalizeToolcraftSemanticText(title);
+
+  return (schema.panels.controls?.sections ?? []).find(
+    (section) => normalizeToolcraftSemanticText(section.title) === normalizedTitle,
+  );
+}
+
+function getSchemaControlsSectionIndexByTitle(
+  schema: ResolvedToolcraftAppSchema,
+  title: string,
+): number {
+  const normalizedTitle = normalizeToolcraftSemanticText(title);
+
+  return (schema.panels.controls?.sections ?? []).findIndex(
+    (section) => normalizeToolcraftSemanticText(section.title) === normalizedTitle,
+  );
+}
+
+function getSectionControlEntryByTarget(
+  section: ToolcraftControlsSection | undefined,
+  target: string,
+): readonly [string, ToolcraftControlSchema] | undefined {
+  if (!section) {
+    return undefined;
+  }
+
+  return Object.entries(section.controls).find(([, control]) => control.target === target);
+}
+
+function getOutputBackgroundColorEntry(
+  section: ToolcraftControlsSection | undefined,
+): readonly [string, ToolcraftControlSchema] | undefined {
+  if (!section) {
+    return undefined;
+  }
+
+  return Object.entries(section.controls).find(([controlId, control]) => {
+    if (control.type !== "color") {
+      return false;
+    }
+
+    return /\b(background|backdrop|scene|canvas)\b/i.test(
+      [section.title, controlId, control.target, getControlLabelText(control)]
+        .join(" ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2"),
+    );
+  });
+}
+
+export function buildToolcraftOutputExportFacts({
+  hasVideoExportAction,
+  schema,
+}: {
+  hasVideoExportAction: boolean;
+  schema: ResolvedToolcraftAppSchema;
+}): ToolcraftOutputExportFacts {
+  const backgroundSection = getSchemaControlsSectionByTitle(schema, "Background");
+  const imageExportSection = getSchemaControlsSectionByTitle(schema, "Image Export");
+  const imageExportSectionIndex = getSchemaControlsSectionIndexByTitle(schema, "Image Export");
+  const videoExportSectionIndex = getSchemaControlsSectionIndexByTitle(schema, "Video Export");
+
+  return {
+    backgroundColorEntry: getOutputBackgroundColorEntry(backgroundSection),
+    backgroundSection,
+    backgroundSectionIndex: getSchemaControlsSectionIndexByTitle(schema, "Background"),
+    expectedOutputSettingsIndex:
+      imageExportSectionIndex >= 0 ? imageExportSectionIndex : videoExportSectionIndex,
+    finalExportSettingsIndex: hasVideoExportAction
+      ? videoExportSectionIndex
+      : imageExportSectionIndex,
+    hasVideoExportAction,
+    imageExportSection,
+    imageExportSectionIndex,
+    imageFormatEntry: getSectionControlEntryByTarget(
+      imageExportSection,
+      "export.image.format",
+    ),
+    imageResolutionEntry: getSectionControlEntryByTarget(
+      imageExportSection,
+      "export.image.resolution",
+    ),
+    includeBackgroundEntry: getSectionControlEntryByTarget(
+      backgroundSection,
+      "export.includeBackground",
+    ),
+    panelActionsSectionIndex: getFirstPanelActionsSectionIndex(schema),
+    videoExportSectionIndex,
+  };
+}

package/templates/starter/src/app/acceptance/output-export.ts

@@ -0,0 +1,45 @@
+import type { ResolvedToolcraftAppSchema } from "@repo/toolcraft-runtime";
+
+import {
+  getToolcraftOutputBackgroundErrors,
+  isOutputBackgroundToggleControl,
+} from "./output-background-rules";
+import {
+  schemaHasPngExportPanelAction,
+  schemaHasVideoExportPanelAction,
+} from "./output-export-actions";
+import { getToolcraftOutputExportLayoutErrors } from "./output-export-layout-rules";
+import { buildToolcraftOutputExportFacts } from "./output-export-model";
+import { getToolcraftImageExportErrors } from "./output-image-export-rules";
+import type { ToolcraftVisibleControl } from "./types";
+
+export {
+  isOutputBackgroundToggleControl,
+  schemaHasPngExportPanelAction,
+  schemaHasVideoExportPanelAction,
+};
+
+export function getToolcraftOutputExportErrors({
+  controls,
+  schema,
+  hasVideoExportAction = schemaHasVideoExportPanelAction(schema),
+}: {
+  controls: readonly ToolcraftVisibleControl[];
+  hasVideoExportAction?: boolean;
+  schema: ResolvedToolcraftAppSchema;
+}): string[] {
+  if (!schemaHasPngExportPanelAction(schema)) {
+    return [];
+  }
+
+  const facts = buildToolcraftOutputExportFacts({
+    hasVideoExportAction,
+    schema,
+  });
+
+  return [
+    ...getToolcraftOutputExportLayoutErrors(facts),
+    ...getToolcraftOutputBackgroundErrors({ controls, facts }),
+    ...getToolcraftImageExportErrors(facts),
+  ];
+}

package/templates/starter/src/app/acceptance/output-image-export-rules.ts

@@ -0,0 +1,87 @@
+import { sectionHasInlineLayoutGroupForPair } from "./inline-layout";
+import type { ToolcraftOutputExportFacts } from "./output-export-model";
+
+export function getToolcraftImageExportErrors(
+  facts: ToolcraftOutputExportFacts,
+): string[] {
+  const errors: string[] = [];
+  const imageFormatControl = facts.imageFormatEntry?.[1];
+  const imageResolutionControl = facts.imageResolutionEntry?.[1];
+  const imageFormatOptionValues =
+    imageFormatControl?.options?.map((option) => option.value.toLowerCase()) ?? [];
+  const imageResolutionOptionValues =
+    imageResolutionControl?.options?.map((option) => option.value.toLowerCase()) ?? [];
+
+  if (!facts.imageExportSection) {
+    errors.push(
+      'Apps with Export PNG must expose image export settings in a separate controls section titled "Image Export" directly above sticky footer export actions or directly before "Video Export" when video export also exists.',
+    );
+  }
+
+  if (!imageFormatControl) {
+    errors.push(
+      'The separate "Image Export" section must include a format control with target "export.image.format".',
+    );
+  } else {
+    if (imageFormatControl.type !== "select") {
+      errors.push(
+        'Image Export format must be a Select control so it matches the Video Export settings structure.',
+      );
+    }
+
+    if (!imageFormatOptionValues.includes("png") || !imageFormatOptionValues.includes("jpg")) {
+      errors.push('Image Export format options must include "png" and "jpg".');
+    }
+
+    if (imageFormatControl.defaultValue !== "png") {
+      errors.push('Image Export format must default to "png".');
+    }
+  }
+
+  if (!imageResolutionControl) {
+    errors.push(
+      'The separate "Image Export" section must include a resolution control with target "export.image.resolution".',
+    );
+  } else {
+    if (imageResolutionControl.type !== "select") {
+      errors.push(
+        'Image Export resolution must be a Select control so it matches the Video Export settings structure.',
+      );
+    }
+
+    if (
+      !imageResolutionOptionValues.includes("2k") ||
+      !imageResolutionOptionValues.includes("4k") ||
+      !imageResolutionOptionValues.includes("8k")
+    ) {
+      errors.push(
+        'Image Export resolution options must include "2k", "4k", and "8k".',
+      );
+    }
+
+    if (imageResolutionControl.defaultValue !== "4k") {
+      errors.push('Image Export resolution must default to "4k".');
+    }
+  }
+
+  const imageFormatControlId = facts.imageFormatEntry?.[0];
+  const imageResolutionControlId = facts.imageResolutionEntry?.[0];
+  const imageExportHasInlinePair =
+    facts.imageExportSection === undefined ||
+    imageFormatControlId === undefined ||
+    imageResolutionControlId === undefined
+      ? false
+      : sectionHasInlineLayoutGroupForPair(
+          facts.imageExportSection,
+          imageFormatControlId,
+          imageResolutionControlId,
+        );
+
+  if (!imageExportHasInlinePair) {
+    errors.push(
+      "Image Export format and resolution must render as one compact two-column inline row, matching Video Export settings.",
+    );
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/reference-runtime-coverage.ts

@@ -0,0 +1,96 @@
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftReferenceCoverage,
+  ToolcraftTransferMode,
+} from "./types";
+
+const requiredReferenceCloneCoverage = [
+  "canvas-sizing",
+  "control-mapping",
+  "renderer-state",
+] satisfies readonly ToolcraftReferenceCoverage[];
+
+export function getReferenceBehaviorCoverageErrors({
+  acceptance,
+  referenceCoverageFromInventory,
+  transferMode,
+}: {
+  acceptance: readonly ToolcraftComponentAcceptance[];
+  referenceCoverageFromInventory: ReadonlySet<ToolcraftReferenceCoverage>;
+  transferMode: Extract<ToolcraftTransferMode, { mode: "reference-runtime-clone" }>;
+}): string[] {
+  const errors: string[] = [];
+  const declaredReferenceCoverage = new Set(transferMode.behaviorCoverage);
+
+  for (const coverage of requiredReferenceCloneCoverage) {
+    if (!declaredReferenceCoverage.has(coverage)) {
+      errors.push(
+        `reference-runtime-clone transferMode must include behaviorCoverage "${coverage}".`,
+      );
+    }
+  }
+
+  for (const coverage of declaredReferenceCoverage) {
+    const entry = acceptance.find(
+      (acceptanceEntry) => acceptanceEntry.referenceCoverage === coverage,
+    );
+
+    if (!entry) {
+      errors.push(
+        `reference-runtime-clone behaviorCoverage "${coverage}" is missing an acceptance entry with referenceCoverage "${coverage}".`,
+      );
+      continue;
+    }
+
+    if (!entry.automated || !entry.automatedTestName.trim()) {
+      errors.push(
+        `${entry.id} must have automated coverage proving reference behavior "${coverage}".`,
+      );
+    }
+
+    if (!entry.browser || !entry.browserTestName.trim()) {
+      errors.push(
+        `${entry.id} must have browser coverage proving reference behavior "${coverage}".`,
+      );
+    }
+
+    if (!entry.expectedObservable.trim()) {
+      errors.push(
+        `${entry.id} must describe the observable reference behavior for "${coverage}".`,
+      );
+    }
+  }
+
+  for (const coverage of declaredReferenceCoverage) {
+    if (!referenceCoverageFromInventory.has(coverage)) {
+      errors.push(
+        `reference-runtime-clone behaviorCoverage "${coverage}" must be represented in referenceFeatureInventory by an item whose acceptanceId points to that referenceCoverage.`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+export function getUnmappedReferenceAcceptanceErrors({
+  acceptance,
+  referenceFeatureAcceptanceIds,
+}: {
+  acceptance: readonly ToolcraftComponentAcceptance[];
+  referenceFeatureAcceptanceIds: ReadonlySet<string>;
+}): string[] {
+  const errors: string[] = [];
+
+  for (const entry of acceptance) {
+    if (
+      (entry.referenceCoverage || entry.referenceTimelineCoverage) &&
+      !referenceFeatureAcceptanceIds.has(entry.id)
+    ) {
+      errors.push(
+        `${entry.id} declares reference coverage but is not mapped from referenceFeatureInventory. Every reference acceptance row must correspond to an inventoried reference feature.`,
+      );
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/reference-runtime-feature-inventory.ts

@@ -0,0 +1,171 @@
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftReferenceCoverage,
+  ToolcraftReferenceFeatureStatus,
+  ToolcraftReferenceTimelineCoverage,
+  ToolcraftTransferMode,
+} from "./types";
+
+const referenceFeatureStatusValues = new Set<ToolcraftReferenceFeatureStatus>([
+  "intentionally-changed",
+  "ported",
+  "toolcraft-native",
+]);
+
+const explicitReferenceChangeReasonPattern =
+  /\b(user|requested|explicit|approved|redesign|change request)\b/i;
+
+export type ReferenceFeatureInventoryValidationResult = {
+  errors: string[];
+  referenceCoverageFromInventory: ReadonlySet<ToolcraftReferenceCoverage>;
+  referenceFeatureAcceptanceIds: ReadonlySet<string>;
+  referenceTimelineCoverageFromInventory: ReadonlySet<ToolcraftReferenceTimelineCoverage>;
+};
+
+export function getReferenceFeatureInventoryValidationResult({
+  acceptance,
+  transferMode,
+}: {
+  acceptance: readonly ToolcraftComponentAcceptance[];
+  transferMode: Extract<ToolcraftTransferMode, { mode: "reference-runtime-clone" }>;
+}): ReferenceFeatureInventoryValidationResult {
+  const errors: string[] = [];
+  const referenceFeatureInventory = transferMode.referenceFeatureInventory ?? [];
+  const acceptanceById = new Map(acceptance.map((entry) => [entry.id, entry]));
+  const referenceFeatureIds = new Set<string>();
+  const referenceFeatureAcceptanceIds = new Set<string>();
+  const referenceCoverageFromInventory = new Set<ToolcraftReferenceCoverage>();
+  const referenceTimelineCoverageFromInventory =
+    new Set<ToolcraftReferenceTimelineCoverage>();
+
+  if (referenceFeatureInventory.length === 0) {
+    errors.push(
+      "reference-runtime-clone transferMode must declare referenceFeatureInventory with every user-visible and output-affecting behavior from the inspected reference, mapped to Toolcraft implementation and acceptance coverage.",
+    );
+  }
+
+  for (const [index, feature] of referenceFeatureInventory.entries()) {
+    const featureLabel = feature.id.trim() || `#${index + 1}`;
+
+    if (!feature.id.trim()) {
+      errors.push(
+        `referenceFeatureInventory item ${index + 1} must include a stable id.`,
+      );
+    } else if (referenceFeatureIds.has(feature.id)) {
+      errors.push(
+        `referenceFeatureInventory id "${feature.id}" is duplicated; each reference feature must be inventoried once.`,
+      );
+    } else {
+      referenceFeatureIds.add(feature.id);
+    }
+
+    if (!feature.featureName.trim()) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" must include a short featureName.`,
+      );
+    }
+
+    if (!feature.sourceEvidence.trim()) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" must include sourceEvidence from the inspected reference source, runtime, UI, or browser behavior.`,
+      );
+    }
+
+    if (!feature.behaviorEvidence.trim()) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" must include behaviorEvidence from the original, restored, or source-only reference study proving this feature was observed before Toolcraft mapping.`,
+      );
+    }
+
+    if (!feature.referenceBehavior.trim()) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" must describe the referenceBehavior to preserve.`,
+      );
+    }
+
+    if (!feature.toolcraftMapping.trim()) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" must describe the Toolcraft mapping for the preserved behavior.`,
+      );
+    }
+
+    if (!referenceFeatureStatusValues.has(feature.status)) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" status must be "ported", "toolcraft-native", or "intentionally-changed".`,
+      );
+    }
+
+    if (feature.status === "intentionally-changed") {
+      if (!feature.userApprovedChangeReason?.trim()) {
+        errors.push(
+          `referenceFeatureInventory "${featureLabel}" status "intentionally-changed" requires userApprovedChangeReason.`,
+        );
+      } else if (
+        !explicitReferenceChangeReasonPattern.test(feature.userApprovedChangeReason)
+      ) {
+        errors.push(
+          `referenceFeatureInventory "${featureLabel}" userApprovedChangeReason must cite explicit user approval or redesign/change-request evidence.`,
+        );
+      }
+    }
+
+    const acceptanceId = feature.acceptanceId.trim();
+
+    if (!acceptanceId) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" must include acceptanceId for the test proving the mapped reference behavior.`,
+      );
+      continue;
+    }
+
+    referenceFeatureAcceptanceIds.add(acceptanceId);
+
+    const entry = acceptanceById.get(acceptanceId);
+
+    if (!entry) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" points to missing acceptanceId "${acceptanceId}".`,
+      );
+      continue;
+    }
+
+    if (!entry.referenceCoverage && !entry.referenceTimelineCoverage) {
+      errors.push(
+        `referenceFeatureInventory "${featureLabel}" acceptanceId "${acceptanceId}" must point to an acceptance entry with referenceCoverage or referenceTimelineCoverage.`,
+      );
+    }
+
+    if (entry.referenceCoverage) {
+      referenceCoverageFromInventory.add(entry.referenceCoverage);
+    }
+
+    if (entry.referenceTimelineCoverage) {
+      referenceTimelineCoverageFromInventory.add(entry.referenceTimelineCoverage);
+    }
+
+    if (!entry.automated || !entry.automatedTestName.trim()) {
+      errors.push(
+        `${acceptanceId} must have automated coverage proving inventoried reference feature "${featureLabel}".`,
+      );
+    }
+
+    if (!entry.browser || !entry.browserTestName.trim()) {
+      errors.push(
+        `${acceptanceId} must have browser coverage proving inventoried reference feature "${featureLabel}".`,
+      );
+    }
+
+    if (!entry.expectedObservable.trim()) {
+      errors.push(
+        `${acceptanceId} must describe the observable result for inventoried reference feature "${featureLabel}".`,
+      );
+    }
+  }
+
+  return {
+    errors,
+    referenceCoverageFromInventory,
+    referenceFeatureAcceptanceIds,
+    referenceTimelineCoverageFromInventory,
+  };
+}

package/templates/starter/src/app/acceptance/reference-runtime-study.ts

@@ -0,0 +1,73 @@
+import type {
+  ToolcraftReferenceStudyStatus,
+  ToolcraftTransferMode,
+} from "./types";
+
+const referenceStudyStatusValues = new Set<ToolcraftReferenceStudyStatus>([
+  "ran-original",
+  "restored-local",
+  "source-inspection-only",
+]);
+
+const referenceStudySourceOnlyReasonPattern =
+  /\b(cannot|can't|unable|unavailable|missing|broken|fails?|blocked|no\s+(?:server|deps?|dependency|access)|not\s+(?:runnable|available))\b/i;
+
+export function getReferenceStudyErrors(
+  transferMode: Extract<ToolcraftTransferMode, { mode: "reference-runtime-clone" }>,
+): string[] {
+  const errors: string[] = [];
+  const referenceStudy = transferMode.referenceStudy;
+
+  if (!referenceStudy) {
+    errors.push(
+      "reference-runtime-clone transferMode must declare referenceStudy proving the reference was inspected and, when runnable or reconstructable, run or restored locally before implementation.",
+    );
+    return errors;
+  }
+
+  if (!referenceStudyStatusValues.has(referenceStudy.status)) {
+    errors.push(
+      'referenceStudy.status must be "ran-original", "restored-local", or "source-inspection-only".',
+    );
+  }
+
+  if (!referenceStudy.referenceLocation.trim()) {
+    errors.push(
+      "referenceStudy.referenceLocation must name the inspected reference folder, URL, artifact, or source location.",
+    );
+  }
+
+  if (!referenceStudy.sourceEvidence.trim()) {
+    errors.push(
+      "referenceStudy.sourceEvidence must summarize the source/runtime files, routes, schemas, or assets inspected.",
+    );
+  }
+
+  if (!referenceStudy.behaviorEvidence.trim()) {
+    errors.push(
+      "referenceStudy.behaviorEvidence must summarize the runtime/browser behavior checked from the original or restored reference.",
+    );
+  }
+
+  if (!referenceStudy.reproductionSteps.trim()) {
+    errors.push(
+      "referenceStudy.reproductionSteps must record how the reference was run, restored in the Toolcraft environment, or why source-only inspection was used.",
+    );
+  }
+
+  if (referenceStudy.status === "source-inspection-only") {
+    if (!referenceStudy.sourceOnlyReason?.trim()) {
+      errors.push(
+        'referenceStudy.status "source-inspection-only" requires sourceOnlyReason explaining why the reference could not be run or restored locally.',
+      );
+    } else if (
+      !referenceStudySourceOnlyReasonPattern.test(referenceStudy.sourceOnlyReason)
+    ) {
+      errors.push(
+        'referenceStudy.sourceOnlyReason must state the concrete blocker that made running or restoring the reference unavailable.',
+      );
+    }
+  }
+
+  return errors;
+}