- '); }
+function wp_json_encode($value): string { return (string) json_encode($value, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); }
+function absint($value): int { return abs((int) $value); }
+function checked($actual, $expected = true, bool $display = true): string {
+ $result = $actual == $expected ? 'checked="checked"' : '';
+ if ($display) echo $result;
+ return $result;
+}
+function selected($actual, $expected = true, bool $display = true): string {
+ $result = $actual == $expected ? 'selected="selected"' : '';
+ if ($display) echo $result;
+ return $result;
+}
+function number_format_i18n($number): string { return number_format((float) $number); }
+function wp_trim_words($text, int $count = 55): string {
+ $words = preg_split('/\s+/', trim((string) $text)) ?: [];
+ return implode(' ', array_slice($words, 0, $count));
+}
+
+function get_option(string $name, $default = false) { return $GLOBALS['aksrt_test_state']['options'][$name] ?? $default; }
+function update_option(string $name, $value): bool { $GLOBALS['aksrt_test_state']['options'][$name] = $value; return true; }
+function wp_get_sidebars_widgets(): array { return $GLOBALS['aksrt_test_state']['sidebars']; }
+function wp_set_sidebars_widgets(array $sidebars): void { $GLOBALS['aksrt_test_state']['sidebars'] = $sidebars; }
+function register_rest_route(string $namespace, string $route, array $args): bool {
+ $GLOBALS['aksrt_test_state']['routes'][$namespace . $route] = $args;
+ return true;
+}
+function rest_ensure_response($data): WP_REST_Response { return $data instanceof WP_REST_Response ? $data : new WP_REST_Response($data); }
+function is_wp_error($value): bool { return $value instanceof WP_Error; }
+function is_singular(): bool { return (bool) $GLOBALS['aksrt_test_state']['singular']; }
+function get_queried_object_id(): int { return (int) $GLOBALS['aksrt_test_state']['current_id']; }
+function get_post($post = null) {
+ if ($post instanceof WP_Post) return $post;
+ return $GLOBALS['aksrt_test_state']['current_post'];
+}
+function aksrt_get_widget_null(string $message): string { return '
' . esc_html($message) . '
'; }
+function aksrt_get_pay_meta($post = null): array { unset($post); return $GLOBALS['aksrt_test_state']['pay_meta']; }
+function aksrt_has_paid_access($post = null): bool { unset($post); return (bool) $GLOBALS['aksrt_test_state']['paid_access']; }
+function aksrt_get_paywall_html(WP_Post $post, bool $fragment = false): string {
+ unset($post, $fragment);
+ $state = $GLOBALS['aksrt_test_state']['logged_in'] ? 'member-locked' : 'guest-locked';
+ return 'PAYWALL
';
+}
+function aksrt_get_pay_attributes_html($post, string $class): string { unset($post); return ''; }
+function aksrt_get_demo_link_html($post, string $class): string { unset($post); return 'DEMO'; }
+function is_user_logged_in(): bool { return (bool) $GLOBALS['aksrt_test_state']['logged_in']; }
+
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
diff --git a/tests/widget-system/run.php b/tests/widget-system/run.php
new file mode 100644
index 00000000..94bb4edc
--- /dev/null
+++ b/tests/widget-system/run.php
@@ -0,0 +1,217 @@
+schema_contract();
+ $this->query_contract();
+ $this->visibility_contract();
+ $this->transfer_round_trip();
+ $this->rest_contract();
+ $this->payment_states();
+ if ($this->failures) {
+ fwrite(STDERR, "Widget system tests failed:\n- " . implode("\n- ", $this->failures) . "\n");
+ exit(1);
+ }
+ echo "Widget system tests passed: {$this->assertions} assertions across schema, query, visibility, transfer, REST and payment states.\n";
+ }
+
+ private function schema_contract(): void {
+ $fields = [
+ ['id' => 'mode', 'type' => 'select', 'default' => 'cards', 'options' => ['cards' => 'Cards', 'list' => 'List']],
+ ['id' => 'count', 'type' => 'slider', 'default' => 3, 'min' => 1, 'max' => 8],
+ ['id' => 'ids', 'type' => 'text', 'sanitize' => 'ids'],
+ ['id' => 'link', 'type' => 'link'],
+ ['id' => 'layout', 'type' => 'fieldset', 'fields' => [
+ ['id' => 'enabled', 'type' => 'switcher', 'default' => false],
+ ['id' => 'gap', 'type' => 'number', 'default' => 8, 'min' => 0, 'max' => 40],
+ ]],
+ ['id' => 'rows', 'type' => 'group', 'max_items' => 2, 'fields' => [
+ ['id' => 'title', 'type' => 'text'],
+ ['id' => 'tone', 'type' => 'radio', 'default' => 'blue', 'options' => ['blue' => 'Blue', 'red' => 'Red']],
+ ]],
+ ];
+ $defaults = FieldSchema::defaults($fields);
+ $this->same('cards', $defaults['mode'], 'schema defaults preserve enums');
+ $this->same(['enabled' => false, 'gap' => 8], $defaults['layout'], 'nested defaults are recursive');
+ $normalized = FieldSchema::normalize($fields, [
+ 'mode' => 'invalid', 'count' => 99, 'ids' => '2, 2，7 bad -4',
+ 'link' => ['url' => 'javascript:alert(1)', 'text' => '课程', 'target' => 'popup'],
+ 'layout' => ['enabled' => 'yes', 'gap' => -9, 'unknown' => 'drop'],
+ 'rows' => [
+ ['title' => '第一项', 'tone' => 'red'],
+ ['title' => '第二项', 'tone' => 'invalid'],
+ ['title' => '第三项'],
+ ],
+ ]);
+ $this->same('cards', $normalized['mode'], 'invalid enum falls back');
+ $this->same(8, $normalized['count'], 'numeric value clamps to maximum');
+ $this->same('2,7,4', $normalized['ids'], 'ID list is unique and normalized');
+ $this->same(['url' => '', 'text' => '课程', 'target' => ''], $normalized['link'], 'link parts sanitize independently');
+ $this->same(['enabled' => true, 'gap' => 0], $normalized['layout'], 'nested values clamp and drop unknown keys');
+ $this->same(2, count($normalized['rows']), 'group max_items is enforced');
+ $this->same('blue', $normalized['rows'][1]['tone'], 'nested enum fallback is enforced');
+
+ $definition = new WidgetDefinition([
+ 'slug' => 'dependency_test', 'name' => 'Dependency Test',
+ 'common' => ['title' => false, 'affix' => false, 'visibility' => false, 'animation' => false, 'layout' => false],
+ 'fields' => [
+ ['id' => 'controller', 'type' => 'select', 'default' => 'off', 'options' => ['off' => 'Off', 'on' => 'On']],
+ ['id' => 'dependent', 'type' => 'text', 'dependency' => ['controller', '==', 'on']],
+ ],
+ ]);
+ $widget = new SchemaWidget($definition);
+ ob_start();
+ $widget->render_full_form(['controller' => 'on', 'dependent' => 'visible']);
+ $html = (string) ob_get_clean();
+ $this->contains('data-dependency=', $html, 'form exports dependency rule');
+ $this->contains('"controller"', $html, 'dependency JSON is safely escaped');
+ }
+
+ private function query_contract(): void {
+ $args = PostQuery::arguments([
+ 'count' => 99, 'category_ids' => '2,5', 'category_id' => 9, 'tag_ids' => '8,13',
+ 'limit_day' => 14, 'orderby' => 'downloads', 'order' => 'asc', 'pay_type' => 'gallery',
+ ], 0);
+ $this->same(50, $args['posts_per_page'], 'query count clamps');
+ $this->same(1, $args['paged'], 'query page clamps');
+ $this->same([9], $args['category__in'], 'segment category overrides category list');
+ $this->same([8, 13], $args['tag__in'], 'query tag filter is normalized');
+ $this->same('ASC', $args['order'], 'query order allowlist is applied');
+ $this->same('meta_value_num', $args['orderby'], 'metric ordering uses numeric meta');
+ $this->contains('gallery', json_encode($args['meta_query']), 'DomainModel pay type reaches meta query');
+ $invalid = PostQuery::arguments(['pay_type' => '6', 'orderby' => 'drop table'], 1);
+ $this->false(isset($invalid['meta_query']), 'legacy numeric pay types are rejected');
+ $this->same('date', $invalid['orderby'], 'unknown orderby falls back');
+ $tabs = ['tabs' => [['title' => 'A', 'category_id' => 2], ['title' => 'B', 'category_id' => 3]]];
+ $this->same(3, PostQuery::segment($tabs, '1')['category_id'], 'valid tab segment resolves');
+ $this->same(2, PostQuery::segment($tabs, '99')['category_id'], 'invalid tab segment falls back to first');
+ }
+
+ private function visibility_contract(): void {
+ $this->true(WidgetVisibility::should_render([], 0, false), 'unrestricted widget renders');
+ $this->true(WidgetVisibility::should_render(['show_id_type' => 'show', 'show_ids' => '3,8'], 8, true), 'show list matches singular ID');
+ $this->false(WidgetVisibility::should_render(['show_id_type' => 'show', 'show_ids' => '3,8'], 4, true), 'show list rejects other IDs');
+ $this->false(WidgetVisibility::should_render(['show_id_type' => 'show', 'show_ids' => '3,8'], 0, false), 'show list rejects archives');
+ $this->false(WidgetVisibility::should_render(['show_id_type' => 'hide', 'show_ids' => '3,8'], 3, true), 'hide list suppresses matching ID');
+ $this->true(WidgetVisibility::should_render(['show_id_type' => 'hide', 'show_ids' => '3,8'], 0, false), 'hide list keeps archives');
+ $this->same('aksrt-widget--only-pc', WidgetVisibility::device_class(['show_type' => 'only_pc']), 'PC device class is stable');
+ $this->same('aksrt-widget--only-mobile', WidgetVisibility::device_class(['show_type' => 'only_sm']), 'mobile device class is stable');
+ $this->same('', WidgetVisibility::device_class(['show_type' => 'invalid']), 'invalid device rule adds no class');
+ }
+
+ private function transfer_round_trip(): void {
+ aksrt_test_reset_state();
+ $GLOBALS['wp_registered_sidebars'] = ['home_sidebar' => [], 'single_sidebar' => []];
+ update_option('widget_aksrt_widget_posts', [2 => ['title' => '课程列表', 'count' => 999, 'style' => 'mini'], '_multiwidget' => 1]);
+ $GLOBALS['aksrt_test_state']['sidebars'] = ['home_sidebar' => ['text-1', 'aksrt_widget_posts-2']];
+ $payload = WidgetTransfer::export('home_sidebar');
+ $this->same(WidgetTransfer::FORMAT, $payload['format'], 'export format is versioned');
+ $this->same(1, count($payload['sidebars']['home_sidebar']), 'export ignores non-schema widgets');
+ $this->same(50, $payload['sidebars']['home_sidebar'][0]['settings']['count'], 'export normalizes saved settings');
+ update_option('widget_aksrt_widget_posts', []);
+ $GLOBALS['aksrt_test_state']['sidebars']['single_sidebar'] = ['text-9'];
+ $result = WidgetTransfer::import($payload, 'append', 'single_sidebar');
+ $this->same(['sidebars' => 1, 'widgets' => 1], $result, 'append import reports changes');
+ $this->same(['text-9', 'aksrt_widget_posts-1'], $GLOBALS['aksrt_test_state']['sidebars']['single_sidebar'], 'append import preserves existing widgets');
+ $round_trip = WidgetTransfer::export('single_sidebar');
+ $this->same($payload['sidebars']['home_sidebar'][0], $round_trip['sidebars']['single_sidebar'][0], 'export/import round trip preserves normalized module');
+ $replacement = WidgetTransfer::template_payload('links_navigation');
+ $result = WidgetTransfer::import($replacement, 'replace', 'single_sidebar');
+ $this->same(3, $result['widgets'], 'targeted template import combines template areas');
+ $this->false(in_array('text-9', $GLOBALS['aksrt_test_state']['sidebars']['single_sidebar'], true), 'replace import removes previous assignment');
+ try {
+ WidgetTransfer::import(['format' => 'zibll.widgets', 'sidebars' => []]);
+ $this->failures[] = 'transfer rejects legacy formats: no exception thrown';
+ } catch (InvalidArgumentException $error) {
+ $this->contains(WidgetTransfer::FORMAT, $error->getMessage(), 'legacy import rejection names accepted format');
+ }
+ }
+
+ private function rest_contract(): void {
+ aksrt_test_reset_state();
+ $controller = new RestController();
+ $controller->register_routes();
+ $this->same(2, count($GLOBALS['aksrt_test_state']['routes']), 'REST registers items and quote routes');
+ $route = $GLOBALS['aksrt_test_state']['routes']['aksrt/v1/widgets/(?P[a-z][a-z0-9_]*)/items'];
+ $this->same('__return_true', $route['permission_callback'], 'public items route is read-only accessible');
+ $this->true($controller->validate_widget('posts'), 'known widget validates');
+ $this->false($controller->validate_widget('shop_products'), 'unknown/shop widget is rejected');
+ $error = $controller->get_items(new WP_REST_Request(['widget' => 'posts', 'instance' => 'aksrt_widget_posts-1', 'page' => 1, 'query' => 'arbitrary']));
+ $this->error('aksrt_widget_unknown_parameter', $error, 'REST rejects arbitrary query parameters');
+ $error = $controller->get_items(new WP_REST_Request(['widget' => 'search', 'instance' => 'aksrt_widget_search-1', 'page' => 1]));
+ $this->error('aksrt_widget_items_unsupported', $error, 'REST rejects non-dynamic widgets');
+ $error = $controller->get_items(new WP_REST_Request(['widget' => 'posts', 'instance' => 'aksrt_widget_posts-1', 'page' => 1]));
+ $this->error('aksrt_widget_instance_not_registered', $error, 'REST requires an assigned instance');
+ $GLOBALS['aksrt_test_state']['sidebars'] = ['home_top_content' => ['aksrt_widget_posts-1']];
+ update_option('widget_aksrt_widget_posts', [1 => ['title' => 'Saved only', 'count' => 2, 'style' => 'list'], '_multiwidget' => 1]);
+ $response = $controller->get_items(new WP_REST_Request(['widget' => 'posts', 'instance' => 'aksrt_widget_posts-1', 'page' => 2, 'segment' => '']));
+ $this->true($response instanceof WP_REST_Response, 'registered instance returns REST response');
+ $data = $response->get_data();
+ $this->true($data['success'], 'REST success envelope is stable');
+ $this->same(2, $data['page'], 'REST page reaches saved-query pipeline');
+ $this->contains('暂无文章', $data['html'], 'REST returns deterministic empty state');
+ $this->same(2, end($GLOBALS['aksrt_test_state']['query_args'])['posts_per_page'], 'REST reloads saved normalized configuration');
+ $error = $controller->get_items(new WP_REST_Request(['widget' => 'posts', 'instance' => 'aksrt_widget_hot_posts-1', 'page' => 1]));
+ $this->error('aksrt_widget_invalid_instance', $error, 'REST binds instance ID to requested widget');
+ }
+
+ private function payment_states(): void {
+ aksrt_test_reset_state();
+ $GLOBALS['aksrt_test_state']['current_post'] = new WP_Post(77, 5);
+ $method = new ReflectionMethod(ContentRenderer::class, 'post_pay');
+ $render = static fn(): string => (string) $method->invoke(null, ['theme' => 'jb-red']);
+ $this->contains('未配置付费内容', $render(), 'unconfigured article renders explicit empty state');
+
+ $authorized = [
+ 'free' => ['pay_type' => 'reading', 'price' => 0],
+ 'purchased' => ['pay_type' => 'reading', 'price' => 29],
+ 'vip' => ['pay_type' => 'vip', 'price' => 0],
+ ];
+ foreach ($authorized as $label => $meta) {
+ $GLOBALS['aksrt_test_state']['pay_meta'] = $meta;
+ $GLOBALS['aksrt_test_state']['paid_access'] = true;
+ $this->contains('内容已解锁', $render(), $label . ' authorization delegates to existing access service');
+ }
+ $GLOBALS['aksrt_test_state']['pay_meta'] = ['pay_type' => 'video', 'price' => 49];
+ $GLOBALS['aksrt_test_state']['paid_access'] = false;
+ $GLOBALS['aksrt_test_state']['logged_in'] = false;
+ $this->contains('guest-locked', $render(), 'guest unauthorized state delegates to paywall');
+ $GLOBALS['aksrt_test_state']['logged_in'] = true;
+ $this->contains('member-locked', $render(), 'logged-in unauthorized state delegates to paywall');
+ }
+
+ private function same($expected, $actual, string $message): void {
+ $this->assertions++;
+ if ($expected !== $actual) $this->failures[] = $message . ' (expected ' . var_export($expected, true) . ', got ' . var_export($actual, true) . ')';
+ }
+ private function true($actual, string $message): void { $this->same(true, (bool) $actual, $message); }
+ private function false($actual, string $message): void { $this->same(false, (bool) $actual, $message); }
+ private function contains(string $needle, ?string $haystack, string $message): void {
+ $this->assertions++;
+ if ($haystack === null || !str_contains($haystack, $needle)) $this->failures[] = $message . ' (missing ' . $needle . ')';
+ }
+ private function error(string $code, $value, string $message): void {
+ $this->assertions++;
+ if (!$value instanceof WP_Error || $value->get_error_code() !== $code) $this->failures[] = $message . ' (expected error ' . $code . ')';
+ }
+}
+
+(new WidgetSystemTest())->run();
diff --git a/tools/audit-widget-system.php b/tools/audit-widget-system.php
index 65a4cd1a..d0066084 100644
--- a/tools/audit-widget-system.php
+++ b/tools/audit-widget-system.php
@@ -258,8 +258,13 @@ foreach ($pinned_assets as $asset => $hash) {
$path = $root . '/assets/widgets/third-party/' . $asset;
if (!is_file($path)) {
$errors[] = 'Missing pinned widget dependency: ' . $asset;
- } elseif (hash_file('sha256', $path) !== $hash) {
- $errors[] = 'Pinned widget dependency changed: ' . $asset;
+ } else {
+ $contents = (string) file_get_contents($path);
+ $raw_hash = hash('sha256', $contents);
+ $lf_hash = hash('sha256', str_replace("\r\n", "\n", $contents));
+ if ($raw_hash !== $hash && $lf_hash !== $hash) {
+ $errors[] = 'Pinned widget dependency changed: ' . $asset;
+ }
}
}
if (!is_file($root . '/assets/widgets/third-party/THIRD_PARTY.md')) {
diff --git a/tools/generate-widget-golden-fixture.php b/tools/generate-widget-golden-fixture.php
new file mode 100644
index 00000000..87f4093c
--- /dev/null
+++ b/tools/generate-widget-golden-fixture.php
@@ -0,0 +1,229 @@
+ 'inc/widgets/widget-more.php',
+ 'content' => 'inc/widgets/widget-posts.php',
+ 'knowledge_product' => 'inc/widgets/widget-produck.php',
+ 'slider' => 'inc/widgets/widget-slider.php',
+ 'user' => 'inc/widgets/widget-user.php',
+];
+$viewports = [
+ ['name' => 'desktop', 'width' => 1440, 'height' => 1100],
+ ['name' => 'tablet', 'width' => 1024, 'height' => 1000],
+ ['name' => 'mobile', 'width' => 390, 'height' => 844],
+];
+$modes = ['light', 'dark'];
+
+$images = [
+ 'https://fixtures.aksrt.test/media/course-cover-01.jpg',
+ 'https://fixtures.aksrt.test/media/course-cover-02.jpg',
+ 'https://fixtures.aksrt.test/media/course-cover-03.jpg',
+];
+
+function fixture_text(string $id, string $slug, int $index): string {
+ $labels = [
+ 'question' => '购买后可以长期学习吗？',
+ 'answer' => '可以，已购买内容会永久保存在你的学习中心。',
+ 'name' => 'AKSRT 学员 ' . ($index + 1),
+ 'author' => 'AKSRT 学员 ' . ($index + 1),
+ 'role' => '知识产品体验官',
+ 'price' => '¥99',
+ 'value' => (string) (($index + 1) * 1280) . '+',
+ 'label' => '累计学习人数',
+ 'heading' => '从入门到精通的系统学习路径',
+ 'description' => '固定内容用于组件 DOM、响应式和视觉差异验收。',
+ 'content' => '结构清晰、案例完整，并持续更新配套资料。',
+ 'title' => 'AKSRT 固定示例 ' . ($index + 1),
+ 'text' => '保持好奇，持续创造。',
+ ];
+ if (isset($labels[$id])) {
+ return $labels[$id];
+ }
+ if (str_contains($id, 'video')) {
+ return 'https://fixtures.aksrt.test/media/lesson.m3u8';
+ }
+ if (str_contains($id, 'url')) {
+ return 'https://fixtures.aksrt.test/' . $slug . '/' . ($index + 1);
+ }
+ if (str_contains($id, 'ids')) {
+ return str_contains($id, 'term') || str_contains($id, 'category') ? '101,102,103' : '';
+ }
+ return 'AKSRT ' . str_replace('_', ' ', $id) . ' ' . ($index + 1);
+}
+
+function fixture_value(array $field, string $slug, int $index, array $images) {
+ $type = (string) ($field['type'] ?? 'text');
+ $id = (string) ($field['id'] ?? '');
+ $default = $field['default'] ?? null;
+ if ($id === 'title') return 'AKSRT · ' . ucfirst(str_replace('_', ' ', $slug));
+ if ($id === 'subtitle') return '固定内容与交互状态视觉验收';
+ if ($id === 'title_highlight') return 'AKSRT';
+ if ($id === 'show_type') return 'all';
+ if ($id === 'show_id_type' || $id === 'show_ids') return '';
+ if ($id === 'layout_bg') {
+ return [
+ 'light' => ['color' => '#ffffff', 'image' => '', 'position' => 'center center', 'repeat' => 'no-repeat', 'attachment' => 'scroll', 'size' => 'cover'],
+ 'dark' => ['color' => '#1d1e24', 'image' => '', 'position' => 'center center', 'repeat' => 'no-repeat', 'attachment' => 'scroll', 'size' => 'cover'],
+ ];
+ }
+ if ($type === 'group') {
+ $rows = [];
+ $count = min(3, max(1, (int) ($field['max_items'] ?? 3)));
+ for ($row = 0; $row < $count; $row++) {
+ $item = [];
+ foreach ((array) ($field['fields'] ?? []) as $child) {
+ $child_id = (string) ($child['id'] ?? '');
+ if ($child_id !== '') $item[$child_id] = fixture_value($child, $slug, $row, $images);
+ }
+ $rows[] = $item;
+ }
+ return $rows;
+ }
+ if (in_array($type, ['fieldset', 'accordion'], true)) {
+ $value = [];
+ foreach ((array) ($field['fields'] ?? []) as $child) {
+ $child_id = (string) ($child['id'] ?? '');
+ if ($child_id !== '') $value[$child_id] = fixture_value($child, $slug, $index, $images);
+ }
+ return $value;
+ }
+ if ($type === 'link') return ['url' => 'https://fixtures.aksrt.test/' . $slug, 'text' => '查看详情', 'target' => ''];
+ if ($type === 'upload') return $images[$index % count($images)];
+ if ($type === 'icon') return 'fas fa-graduation-cap';
+ if ($type === 'color') return '#667eea';
+ if ($type === 'spacing') return ['top' => 0, 'right' => 0, 'bottom' => 20, 'left' => 0];
+ if ($type === 'background') return ['color' => '#ffffff', 'image' => '', 'position' => 'center center', 'repeat' => 'no-repeat', 'attachment' => 'scroll', 'size' => 'cover'];
+ if ($type === 'switcher') return $default === null ? true : (bool) $default;
+ if (in_array($type, ['number', 'spinner', 'slider'], true)) return $default ?? ($field['min'] ?? 1);
+ if (in_array($type, ['radio', 'button_set', 'select', 'palette'], true)) return $default ?? (array_key_first((array) ($field['options'] ?? [])) ?? '');
+ if ($type === 'checkbox') return $default ?? [];
+ if ($id === 'title_link') return ['url' => 'https://fixtures.aksrt.test/' . $slug, 'text' => '查看更多', 'target' => ''];
+ if ($default !== null && $default !== '') return $default;
+ return fixture_text($id, $slug, $index);
+}
+
+$dynamic = ['posts', 'tab_posts', 'oneline_posts', 'hot_posts'];
+$expandable = ['posts_toc', 'faq'];
+$tabbed = ['tab_posts', 'feature_intro'];
+$carousel = ['partners', 'notice', 'oneline_posts', 'reviews', 'slider', 'slider_media_combo'];
+$components = [];
+$matrix = [];
+foreach (WidgetRegistry::all() as $slug => $definition) {
+ $settings = [];
+ foreach ($definition->fields() as $field) {
+ $id = (string) ($field['id'] ?? '');
+ $type = (string) ($field['type'] ?? 'text');
+ if ($id === '' || in_array($type, ['content', 'subheading', 'submessage'], true)) continue;
+ $settings[$id] = fixture_value($field, $slug, 0, $images);
+ }
+ $settings = $definition->normalize($settings);
+ $states = ['default', 'hover', 'focus'];
+ if (in_array($slug, $expandable, true)) $states[] = 'expanded';
+ if (in_array($slug, $tabbed, true)) $states[] = 'alternate-tab';
+ if (in_array($slug, $carousel, true)) $states[] = 'next-slide';
+ if (in_array($slug, $dynamic, true)) $states = array_merge($states, ['loading', 'empty', 'error']);
+ if ($slug === 'post_pay') $states = array_merge($states, ['guest-locked', 'member-locked', 'authorized', 'unconfigured']);
+ if ($slug === 'user_card') $states = array_merge($states, ['guest', 'signed-in']);
+ $source = $group_sources[$definition->group()] ?? 'inc/widgets/widget-index.php';
+ $components[$slug] = [
+ 'id_base' => $definition->id_base(),
+ 'name' => $definition->name(),
+ 'group' => $definition->group(),
+ 'size' => $definition->size(),
+ 'reference' => ['file' => $source, 'sha256' => $reference_hashes[$source] ?? ''],
+ 'field_ids' => array_values(array_filter(array_map(static fn(array $field): string => (string) ($field['id'] ?? ''), $definition->fields()))),
+ 'settings' => $settings,
+ 'root_selector' => '[data-aksrt-widget="' . $slug . '"]',
+ 'states' => array_values(array_unique($states)),
+ ];
+ foreach ($viewports as $viewport) {
+ foreach ($modes as $mode) {
+ $id = $slug . ':' . $viewport['name'] . ':' . $mode;
+ $matrix[$id] = [
+ 'widget' => $slug,
+ 'viewport' => $viewport,
+ 'mode' => $mode,
+ 'path' => 'tests/visual-results/' . $slug . '/' . $viewport['name'] . '-' . $mode . '.png',
+ ];
+ }
+ }
+}
+
+$fixture = [
+ 'schema' => 'aksrt.widget-golden.v1',
+ 'captured_at' => (string) ($baseline['captured_at'] ?? ''),
+ 'reference' => [
+ 'source_root' => $reference_root,
+ 'fingerprint' => hash('sha256', implode('', $reference_hashes)),
+ 'files' => $reference_hashes,
+ 'policy' => $baseline['source_policy'] ?? [],
+ ],
+ 'acceptance' => [
+ 'dimension_delta_px_max' => 2,
+ 'pixel_difference_percent_max' => 1.5,
+ 'console_errors_max' => 0,
+ 'unexpected_network_failures_max' => 0,
+ 'a11y_critical_max' => 0,
+ 'a11y_serious_max' => 0,
+ 'reduced_motion_required' => true,
+ ],
+ 'dataset' => [
+ 'site' => ['name' => 'AKSRT 知识库', 'url' => 'https://fixtures.aksrt.test'],
+ 'terms' => [
+ ['id' => 101, 'taxonomy' => 'category', 'name' => '产品设计', 'count' => 24],
+ ['id' => 102, 'taxonomy' => 'category', 'name' => '前端开发', 'count' => 36],
+ ['id' => 103, 'taxonomy' => 'post_tag', 'name' => '系统课程', 'count' => 18],
+ ],
+ 'users' => [
+ ['id' => 201, 'name' => '林知夏', 'role' => '讲师', 'points' => 9680, 'followers' => 3280],
+ ['id' => 202, 'name' => '周屿', 'role' => '作者', 'points' => 7420, 'followers' => 2160],
+ ['id' => 203, 'name' => '陈墨', 'role' => '学员', 'points' => 5360, 'followers' => 980],
+ ],
+ 'posts' => [
+ ['id' => 301, 'title' => '从零构建知识产品体系', 'pay_type' => 'reading', 'author' => 201, 'category' => 101],
+ ['id' => 302, 'title' => '现代 WordPress 主题工程实践', 'pay_type' => 'video', 'author' => 202, 'category' => 102],
+ ['id' => 303, 'title' => '高质量课程资料包', 'pay_type' => 'download', 'author' => 201, 'category' => 102],
+ ['id' => 304, 'title' => '视觉案例图库', 'pay_type' => 'gallery', 'author' => 202, 'category' => 101],
+ ['id' => 305, 'title' => '会员专属进阶课', 'pay_type' => 'vip', 'author' => 201, 'category' => 101],
+ ['id' => 306, 'title' => '公开学习指南', 'pay_type' => 'no', 'author' => 203, 'category' => 102],
+ ],
+ 'comments' => [
+ ['id' => 401, 'user' => 203, 'post' => 301, 'content' => '课程结构清晰，案例非常实用。'],
+ ['id' => 402, 'user' => 202, 'post' => 302, 'content' => '对主题工程化讲解得很完整。'],
+ ],
+ 'payment_states' => ['guest-locked', 'member-locked', 'free', 'purchased', 'vip-authorized', 'unconfigured'],
+ 'media' => ['images' => $images, 'video' => 'https://fixtures.aksrt.test/media/lesson.m3u8'],
+ ],
+ 'components' => $components,
+ 'screenshot_matrix' => $matrix,
+];
+
+$output = $root . '/tests/fixtures/widget-golden-v1.json';
+file_put_contents($output, json_encode($fixture, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) . "\n");
+echo 'Generated widget golden fixture: ' . count($components) . ' components, ' . count($matrix) . " screenshots.\n";
diff --git a/tools/validate-widget-golden.php b/tools/validate-widget-golden.php
new file mode 100644
index 00000000..eb521e9f
--- /dev/null
+++ b/tools/validate-widget-golden.php
@@ -0,0 +1,70 @@
+ $component) {
+ $definition = WidgetRegistry::get((string) $slug);
+ if ($definition === null) continue;
+ if (($component['id_base'] ?? '') !== $definition->id_base()) $errors[] = $slug . ': id_base mismatch.';
+ if (($component['settings'] ?? []) !== $definition->normalize((array) ($component['settings'] ?? []))) $errors[] = $slug . ': settings are not normalized.';
+ foreach (['default', 'hover', 'focus'] as $state) {
+ if (!in_array($state, (array) ($component['states'] ?? []), true)) $errors[] = $slug . ': missing state ' . $state . '.';
+ }
+}
+foreach ((array) ($fixture['reference']['files'] ?? []) as $relative => $expected) {
+ $path = rtrim((string) ($fixture['reference']['source_root'] ?? ''), '\\/') . DIRECTORY_SEPARATOR . str_replace('/', DIRECTORY_SEPARATOR, (string) $relative);
+ if (!is_file($path) || hash_file('sha256', $path) !== $expected) $errors[] = 'Reference drift: ' . $relative;
+}
+
+$require_results = in_array('--require-results', $argv, true);
+if ($require_results) {
+ $result_path = $root . '/tests/visual-results/manifest.json';
+ if (!is_file($result_path)) {
+ $errors[] = 'Visual result manifest is missing.';
+ } else {
+ $result = json_decode((string) file_get_contents($result_path), true, 512, JSON_THROW_ON_ERROR);
+ if (($result['schema'] ?? '') !== 'aksrt.widget-visual-results.v1') $errors[] = 'Invalid visual result schema.';
+ $screenshots = (array) ($result['screenshots'] ?? []);
+ foreach ($matrix as $id => $expected) {
+ $actual = (array) ($screenshots[$id] ?? []);
+ $path = $root . DIRECTORY_SEPARATOR . str_replace('/', DIRECTORY_SEPARATOR, (string) ($expected['path'] ?? ''));
+ if (!$actual || !is_file($path)) $errors[] = $id . ': screenshot result is missing.';
+ }
+ foreach ($components as $slug => $component) {
+ $states = (array) ($result['components'][$slug]['states'] ?? []);
+ foreach ((array) ($component['states'] ?? []) as $state) {
+ if (($states[$state] ?? '') !== 'pass') $errors[] = $slug . ': state not passed: ' . $state . '.';
+ }
+ }
+ $acceptance = (array) ($fixture['acceptance'] ?? []);
+ $metrics = (array) ($result['metrics'] ?? []);
+ if ((float) ($metrics['dimension_delta_px_max'] ?? INF) > (float) $acceptance['dimension_delta_px_max']) $errors[] = 'Dimension delta exceeds threshold.';
+ if ((float) ($metrics['pixel_difference_percent_max'] ?? INF) > (float) $acceptance['pixel_difference_percent_max']) $errors[] = 'Pixel difference exceeds threshold.';
+ if ((int) ($result['console']['errors'] ?? PHP_INT_MAX) > (int) $acceptance['console_errors_max']) $errors[] = 'Console contains errors.';
+ if ((int) ($result['network']['unexpected_failures'] ?? PHP_INT_MAX) > (int) $acceptance['unexpected_network_failures_max']) $errors[] = 'Network contains unexpected failures.';
+ if ((int) ($result['a11y']['critical'] ?? PHP_INT_MAX) > (int) $acceptance['a11y_critical_max']) $errors[] = 'Accessibility critical findings remain.';
+ if ((int) ($result['a11y']['serious'] ?? PHP_INT_MAX) > (int) $acceptance['a11y_serious_max']) $errors[] = 'Accessibility serious findings remain.';
+ if (empty($result['reduced_motion']['passed'])) $errors[] = 'Reduced-motion behavior was not verified.';
+ }
+}
+
+if ($errors) {
+ fwrite(STDERR, "Widget golden validation failed:\n- " . implode("\n- ", array_slice($errors, 0, 50)) . "\n");
+ exit(1);
+}
+
+echo 'Widget golden fixture passed: 37 components, 222 screenshot targets, frozen reference intact';
+echo $require_results ? ", runtime results passed.\n" : ", runtime results pending.\n";