*/ private const ADDITIONAL_PROMPT_FILTERS = array( Generators::TITLE => 'aipt_title_additional_prompt_enabled', Generators::FAQ => 'aipt_faq_additional_prompt_enabled', Generators::SEO_META => 'aipt_seo_meta_additional_prompt_enabled', Generators::IMAGE_ALT => 'aipt_image_alt_additional_prompt_enabled', ); /** * Whether $generator's blueprint-level `rules.instructions` and (where * the structure has one) per-unit `instruction` field may reach the AI. * * Every generator's are Business; Description's joined in 2.8.1 with * its own bridge, separate from its custom prompt, which stays free. * `Premium\ContentStructure\InstructionsService` registers it. * * Public: {@see \AIPT\Api\ContentStructure\Engine\ExecutionContextBuilder} * reuses this exact gate for the product AI note — the note is never a * second, separate instructions filter, it rides the same per-generator * entitlement this method already decides. * * @param string $generator Generator key. * @return bool */ public function instructionsAllowed( string $generator ): bool { if ( Generators::DESCRIPTION === $generator ) { return (bool) apply_filters( 'aipt_description_instructions_enabled', false ); } if ( Generators::TAXONOMY === $generator ) { return (bool) apply_filters( 'aipt_taxonomy_additional_prompt_allowed', false ); } $filter = self::ADDITIONAL_PROMPT_FILTERS[ $generator ] ?? ''; return '' === $filter ? true : (bool) apply_filters( $filter, false ); } /** * @param string $generator Generator key. * @param array &$definition Clamped definition (mutated in place). * @param array &$applied Accumulated appliedFreeDefaults entries. * @return void */ public function clamp( string $generator, array &$definition, array &$applied ): void { if ( $this->instructionsAllowed( $generator ) ) { return; } $dropped_blueprint_level = $this->clampBlueprintLevelInstructions( $definition ); $dropped_per_unit = $this->clampPerUnitInstruction( $generator, $definition ); if ( $dropped_blueprint_level || $dropped_per_unit ) { $applied[] = $this->freeDefault( 'instructions', $this->instructionsFeature( $generator ), __( 'Extra instructions on this template were not sent to the AI in this run.', 'ai-product-tools' ), __( 'extra instructions', 'ai-product-tools' ) ); } } /** * The `appliedFreeDefaults` entry for a product's AI note being withheld * from this run because {@see instructionsAllowed()} denies this * generator. Built here so its `PlanDenial` reason code * reuses the exact same feature key {@see instructionsFeature()} already * picks for this generator's regular instructions clamp - the note * shares that one entitlement, it is never a second gate with its own * message variant. * * Added to the result only by a caller that actually knows THIS * product/subject had a non-empty note to drop - * {@see \AIPT\Api\ContentStructure\Engine\ExecutionContextBuilder::buildCtx()} * is where that fact is known (never this class, which clamps the * BlueprintDefinition before any subject/product data exists). * * @param string $generator Generator key whose note was withheld. * @return array{key:string,reason:string} */ public function aiNoteFreeDefault( string $generator ): array { return $this->freeDefault( 'aiNote', $this->instructionsFeature( $generator ), __( "This product's AI note was not used in this run.", 'ai-product-tools' ), __( 'AI notes', 'ai-product-tools' ) ); } /** * Clear every enabled `rules.instructions` entry (shared across all six * generators' definitions). A disabled or already-empty list is left * alone and reports no effect. * * @param array &$definition Clamped definition (mutated in place). * @return bool Whether anything was actually dropped. */ private function clampBlueprintLevelInstructions( array &$definition ): bool { $instructions = isset( $definition['rules']['instructions'] ) && is_array( $definition['rules']['instructions'] ) ? $definition['rules']['instructions'] : array(); $has_enabled = false; foreach ( $instructions as $instruction ) { if ( is_array( $instruction ) && ! empty( $instruction['enabled'] ) && '' !== trim( (string) ( $instruction['text'] ?? '' ) ) ) { $has_enabled = true; break; } } if ( ! $has_enabled ) { return false; } $definition['rules']['instructions'] = array(); return true; } /** * Clear the per-unit `instruction` field where the generator's * structure has one: taxonomy sections, FAQ groups, the single * image_alt structure field. Title and SEO meta have no such field, and * a description section's own instruction is not part of this gate. * * FAQ and image_alt both carry the same carve-out: a structure's * instruction is left alone when it still matches one of the * generator's own shipped starter defaults (running a template's own * wording is not the paid custom-instruction capability), and cleared * only when it differs, which is what a merchant's own customization * looks like. Taxonomy has no such carve-out because none of its * starter templates ship a non-empty section `instruction` today * (verified by its own starter-templates entitlement test), so every * non-empty value it ever sees is a merchant's. * * @param string $generator Generator key. * @param array &$definition Clamped definition (mutated in place). * @return bool Whether anything was actually dropped. */ private function clampPerUnitInstruction( string $generator, array &$definition ): bool { $dropped = false; if ( Generators::TAXONOMY === $generator && isset( $definition['structure']['sections'] ) && is_array( $definition['structure']['sections'] ) ) { foreach ( $definition['structure']['sections'] as $i => $section ) { if ( is_array( $section ) && '' !== trim( (string) ( $section['instruction'] ?? '' ) ) ) { $definition['structure']['sections'][ $i ]['instruction'] = ''; $dropped = true; } } } if ( Generators::FAQ === $generator && isset( $definition['structure']['groups'] ) && is_array( $definition['structure']['groups'] ) ) { $starter_group_instructions = TemplateCatalog::starterGroupInstructions( $generator ); foreach ( $definition['structure']['groups'] as $i => $group ) { if ( ! is_array( $group ) ) { continue; } $instruction = trim( (string) ( $group['instruction'] ?? '' ) ); if ( '' === $instruction ) { continue; } $id = (string) ( $group['id'] ?? '' ); $starter = $starter_group_instructions[ $id ] ?? array(); if ( in_array( $instruction, $starter, true ) ) { continue; } $definition['structure']['groups'][ $i ]['instruction'] = ''; $dropped = true; } } if ( Generators::IMAGE_ALT === $generator ) { $instruction = trim( (string) ( $definition['structure']['instruction'] ?? '' ) ); $starter = TemplateCatalog::starterInstruction( $generator, (string) ( $definition['structure']['starter'] ?? '' ) ); if ( '' !== $instruction && '' !== $starter ) { $definition['structure']['instruction'] = $starter; } elseif ( '' !== $instruction && ! $this->isStarterInstruction( $generator, $instruction ) ) { $definition['structure']['instruction'] = ''; $dropped = true; } } return $dropped; } /** * Whether $instruction is one of $generator's starter templates' own * instructions, which run on every plan: the seven Image alt presets * are those instructions, and they are free starter templates because * running one is not writing a custom instruction. Writing a different * one is the paid "extra instructions" capability. The fallback for a * structure that names no `starter`: compared in the current locale * only. * * @param string $generator Generator key. * @param string $instruction Trimmed instruction text. * @return bool */ private function isStarterInstruction( string $generator, string $instruction ): bool { return in_array( $instruction, TemplateCatalog::starterInstructions( $generator ), true ); } /** * @param string $generator Generator key. * @return string Internal PlanDenial feature key (message-variant selection only; never exposed to the client). */ private function instructionsFeature( string $generator ): string { $map = array( Generators::DESCRIPTION => 'descriptionInstructions', Generators::TITLE => 'titleAdditionalPrompt', Generators::FAQ => 'faqAdditionalPrompt', Generators::SEO_META => 'seoMetaAdditionalPrompt', Generators::IMAGE_ALT => 'imageAltAdditionalPrompt', Generators::TAXONOMY => 'taxonomyAdditionalPrompt', ); return $map[ $generator ] ?? 'blueprintAdditionalPrompt'; } }