@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/tests/graph-html-density.regression-1.sh

@@ -0,0 +1,228 @@
+#!/bin/bash
+# Regression: engine graph HTML should keep density contracts for larger graphs
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+source "$REPO_ROOT/tests/lib/graph-html-engine-helpers.sh"
+
+write_density_fixture() {
+    local output="$1"
+    local count="$2"
+
+    node - <<'NODE' "$output" "$count"
+const fs = require("fs");
+const output = process.argv[2];
+const count = Number(process.argv[3]);
+const nodes = Array.from({ length: count }, (_, index) => {
+  const type = index % 8 === 0 ? "source" : index % 3 === 0 ? "topic" : "entity";
+  const community = String(index % 6);
+  return {
+    id: `node-${index}`,
+    label: `Density Node ${index}`,
+    type,
+    community,
+    confidence: "EXTRACTED",
+    content: `# Density Node ${index}\n\n这是第 ${index} 个密度测试节点，用来验证大量节点时不会全部铺成大卡片。\n\n关联到 [[node-${Math.max(0, index - 1)}|前一个节点]]。`
+  };
+});
+const edges = [];
+for (let index = 1; index < count; index++) {
+  edges.push({
+    id: `edge-${index}`,
+    from: `node-${index - 1}`,
+    to: `node-${index}`,
+    type: index % 5 === 0 ? "INFERRED" : "EXTRACTED",
+    weight: index % 5 === 0 ? 0.6 : 0.9
+  });
+}
+const communities = Array.from({ length: 6 }, (_, index) => ({
+  id: String(index),
+  label: `社区 ${index}`,
+  node_count: nodes.filter((node) => node.community === String(index)).length,
+  source_count: 1,
+  is_primary: index === 0,
+  recommended_start_node_id: `node-${index}`
+}));
+const graph = {
+  meta: {
+    wiki_title: "密度测试知识库",
+    build_date: "2026-04-27",
+    total_nodes: nodes.length,
+    total_edges: edges.length
+  },
+  nodes,
+  edges,
+  learning: {
+    entry: { recommended_start_node_id: "node-0" },
+    views: {
+      path: { enabled: true, degraded: false, node_ids: ["node-0", "node-1", "node-2"] },
+      community: { enabled: true, degraded: false, node_ids: nodes.filter((node) => node.community === "0").map((node) => node.id) },
+      global: { enabled: true, degraded: false, node_ids: nodes.map((node) => node.id) }
+    },
+    communities
+  },
+  insights: {
+    surprising_connections: [],
+    isolated_nodes: [],
+    bridge_nodes: [],
+    sparse_communities: [],
+    meta: { degraded: false }
+  }
+};
+fs.writeFileSync(output, JSON.stringify(graph, null, 2));
+NODE
+}
+
+test_graph_engine_exports_density_rules() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "e.getAtlasDensityMode="
+    assert_file_contains "$html" "screenEffectiveDensityMode"
+    assert_file_contains "$html" "nodeDisplayModeForDensity"
+    assert_file_contains "$html" "e.resolveAtlasVisibleSnapshot="
+    assert_file_contains "$html" "e.edgeStrokeWidth="
+    assert_file_contains "$html" "e.cardDims="
+    assert_file_contains "$html" ".node.is-overview"
+    assert_file_contains "$html" ".node[data-visual-role=\"map-pin\"]"
+    assert_file_contains "$html" "dataset.densityMode"
+    assert_file_contains "$html" "dataset.effectiveDensity"
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_html_builds_large_density_fixture_as_single_file() {
+    local tmp_dir output_dir html
+    tmp_dir="$(mktemp -d)"
+    output_dir="$tmp_dir/wiki"
+    mkdir -p "$output_dir"
+
+    write_density_fixture "$output_dir/graph-data.json" 200
+    ensure_graph_engine_dist
+    bash "$REPO_ROOT/scripts/build-graph-html.sh" "$tmp_dir" > /dev/null 2>&1 \
+        || fail "build-graph-html.sh should succeed on 200-node density fixture"
+
+    html="$output_dir/knowledge-graph.html"
+    assert_single_file_engine_output "$output_dir"
+    assert_file_contains "$html" "密度测试知识库"
+    assert_file_contains "$html" "Density Node 199"
+    assert_file_contains "$html" "200 节点"
+    assert_file_contains "$html" "199 关联"
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_html_density_preview_for_compact_and_point_nodes() {
+    local tmp_dir output_dir html playwright_node_path
+    tmp_dir="$(mktemp -d)"
+    output_dir="$tmp_dir/wiki"
+    mkdir -p "$output_dir"
+
+    write_density_fixture "$output_dir/graph-data.json" 240
+    ensure_graph_engine_dist
+    bash "$REPO_ROOT/scripts/build-graph-html.sh" "$tmp_dir" > /dev/null 2>&1 \
+        || fail "build-graph-html.sh should succeed on density preview fixture"
+    html="$output_dir/knowledge-graph.html"
+
+    playwright_node_path="$(
+        npx --yes -p playwright -c 'node -e "const path=require(\"path\"); console.log(path.dirname(process.env.PATH.split(\":\")[0]))"'
+    )"
+    GRAPH_DENSITY_PREVIEW_HTML="$html" NODE_PATH="$playwright_node_path" node "$REPO_ROOT/tests/browser/graph-density-preview.mjs" \
+        || fail "density preview browser regression should pass"
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_density_thresholds_and_budgets() {
+    ensure_graph_engine_dist
+    node --input-type=module - <<'NODE' "$REPO_ROOT" || fail "density thresholds and budgets should hold"
+import assert from "node:assert/strict";
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+
+const repoRoot = process.argv[2];
+const engine = await import(pathToFileURL(path.join(repoRoot, "packages/graph-engine/dist/engine.esm.js")).href);
+const {
+  buildAtlasModel,
+  deriveAtlasLayout,
+  resolveAtlasVisibleSnapshot,
+  nodeDisplayModeForDensity,
+  screenEffectiveDensityMode
+} = engine;
+
+function makeGraph(count, edgeCount) {
+  const nodes = Array.from({ length: count }, (_, index) => ({
+    id: `node-${index}`,
+    label: `Density Node ${index}`,
+    type: index % 8 === 0 ? "source" : index % 3 === 0 ? "topic" : "entity",
+    community: String(index % 6),
+    confidence: "EXTRACTED",
+    content: `# Density Node ${index}\n\n节点 ${index}。`
+  }));
+  const edges = Array.from({ length: edgeCount }, (_, index) => ({
+    id: `edge-${index}`,
+    from: `node-${index % count}`,
+    to: `node-${(index * 7 + 1) % count}`,
+    type: index % 5 === 0 ? "INFERRED" : "EXTRACTED",
+    weight: index % 9 === 0 ? 0.4 : 0.9
+  })).filter((edge) => edge.from !== edge.to);
+  return {
+    meta: { wiki_title: "密度预算测试" },
+    nodes,
+    edges,
+    learning: { entry: { recommended_start_node_id: "node-0" } }
+  };
+}
+
+function snapshotFor(count, edgeCount, selectedNodeId) {
+  const model = buildAtlasModel(makeGraph(count, edgeCount));
+  const layout = deriveAtlasLayout(model);
+  return resolveAtlasVisibleSnapshot(model, layout, {
+    activeCommunityId: "all",
+    focusMode: "all",
+    query: "",
+    selectedNodeId,
+    filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: true, UNVERIFIED: true }
+  });
+}
+
+const pointSnapshot = snapshotFor(201, 900, "node-200");
+assert.equal(pointSnapshot.densityMode, "point-plus-focus");
+assert.ok(Object.keys(pointSnapshot.labelNodeIds).length <= 61);
+assert.ok(pointSnapshot.labelNodeIds["node-200"]);
+assert.ok(pointSnapshot.importantNodeIds["node-0"]);
+assert.ok(pointSnapshot.edges.length <= 800);
+
+const overviewSnapshot = snapshotFor(501, 1500, "node-500");
+assert.equal(overviewSnapshot.densityMode, "overview");
+assert.ok(Object.keys(overviewSnapshot.labelNodeIds).length <= 41);
+assert.ok(overviewSnapshot.labelNodeIds["node-500"]);
+assert.ok(overviewSnapshot.importantNodeIds["node-0"]);
+assert.ok(overviewSnapshot.edges.length <= 1000);
+
+assert.equal(screenEffectiveDensityMode(120, 1), "compact-card");
+assert.equal(screenEffectiveDensityMode(120, 2), "card");
+assert.equal(screenEffectiveDensityMode(120, 0.5), "point-plus-focus");
+assert.equal(nodeDisplayModeForDensity({ selected: false, labelVisible: false, visualRole: "map-pin" }, "card"), "card");
+assert.equal(nodeDisplayModeForDensity({ selected: false, labelVisible: false, visualRole: "map-pin" }, "compact-card"), "compact-card");
+assert.equal(nodeDisplayModeForDensity({ selected: false, labelVisible: false, visualRole: "map-pin" }, "point-plus-focus"), "point");
+assert.equal(nodeDisplayModeForDensity({ selected: true, labelVisible: false, visualRole: "map-pin" }, "overview"), "card");
+NODE
+}
+
+main() {
+    npm run build -w @llm-wiki/graph-engine > /dev/null 2>&1 \
+        || fail "graph-engine build should succeed before density regression"
+    test_graph_engine_exports_density_rules
+    test_graph_html_builds_large_density_fixture_as_single_file
+    test_graph_html_density_preview_for_compact_and_point_nodes
+    test_graph_density_thresholds_and_budgets
+    [ -f "$REPO_ROOT/tests/fixtures/graph-interactive-dense/wiki/graph-data.json" ] || fail "dense fixture should exist"
+    echo "PASS: graph HTML density regression coverage"
+}
+
+main "$@"

package/skills/llm-wiki-skill/tests/graph-html-drawer-neighbors.regression-1.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Regression: offline host without onOpenPage should expose the built-in reader
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+source "$REPO_ROOT/tests/lib/graph-html-engine-helpers.sh"
+
+test_graph_html_has_builtin_reader_region() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" ".graph-reader {"
+    assert_file_contains "$html" ".graph-reader[data-state=\"open\"]"
+    assert_file_contains "$html" ".graph-reader-body"
+    assert_file_contains "$html" "graph-reader-markdown"
+    assert_file_contains "$html" "选择一个节点查看内容"
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_html_reader_uses_marked_and_purify() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "marked.parse"
+    assert_file_contains "$html" "DOMPurify.sanitize"
+    assert_file_contains "$html" "graph-reader-markdown"
+    grep -Eq '[[:alnum:]_$]+\.content\|\|[[:alnum:]_$]+\.summary\|\|[[:alnum:]_$]+\.label' "$html" \
+        || fail "Expected $html to contain the reader content/summary/label fallback chain"
+
+    rm -rf "$tmp_dir"
+}
+
+main() {
+    test_graph_html_has_builtin_reader_region
+    test_graph_html_reader_uses_marked_and_purify
+    echo "PASS: graph HTML built-in reader regression coverage"
+}
+
+main "$@"

package/skills/llm-wiki-skill/tests/graph-html-insights.regression-1.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Regression: engine atlas should keep weighted relationship cues
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+source "$REPO_ROOT/tests/lib/graph-html-engine-helpers.sh"
+
+test_graph_html_has_weighted_edge_hooks() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "edgeStrokeWidth"
+    assert_file_contains "$html" "edgeOpacity"
+    assert_file_contains "$html" "edgeVisualStrokeWidth"
+    assert_file_contains "$html" "edgeVisualOpacity"
+    assert_file_contains "$html" "edgeRelationClass"
+    assert_file_contains "$html" "strokeWidth"
+    assert_file_contains "$html" "opacity"
+    assert_file_contains "$html" "data-relation-type"
+    assert_file_contains "$html" "data-confidence"
+    assert_file_contains "$html" "confidence-inferred"
+    assert_file_contains "$html" "confidence-ambiguous"
+    assert_file_contains "$html" "relation-contrast"
+    assert_file_contains "$html" "relation-conflict"
+    assert_file_contains "$html" "#d94693"
+    assert_file_contains "$html" "atlasConfidenceLabel"
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_html_has_structural_selection_actions_without_offline_ask_ui() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "why_no_connection"
+    assert_file_contains "$html" "find_potential_bridges"
+    assert_file_contains "$html" "resolveSelectionForCapabilities"
+    assert_file_contains "$html" "graph-selection-panel"
+    assert_file_contains "$html" "graph-selection-facts"
+    assert_file_contains "$html" "Shift+点击 增删节点"
+    assert_file_not_contains "$html" "提问选区"
+    assert_file_not_contains "$html" "onAsk:"
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_html_offline_selection_panel_behaves_in_browser() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    local playwright_node_path
+    playwright_node_path="$(
+        npx --yes -p playwright -c 'node -e "const path=require(\"path\"); console.log(path.dirname(process.env.PATH.split(\":\")[0]))"'
+    )"
+    GRAPH_HTML_INSIGHTS_HTML="$html" NODE_PATH="$playwright_node_path" node "$REPO_ROOT/tests/browser/graph-html-insights.mjs" \
+        || fail "offline graph selection browser regression should pass"
+
+    rm -rf "$tmp_dir"
+}
+
+main() {
+    npm run build -w @llm-wiki/graph-engine > /dev/null 2>&1 \
+        || fail "graph-engine build should succeed before insights regression"
+    test_graph_html_has_weighted_edge_hooks
+    test_graph_html_has_structural_selection_actions_without_offline_ask_ui
+    test_graph_html_offline_selection_panel_behaves_in_browser
+    echo "PASS: graph HTML insights regression coverage"
+}
+
+main "$@"

package/skills/llm-wiki-skill/tests/graph-html-long-label.regression-1.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Regression: long card labels should truncate safely and expose full title text
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+source "$REPO_ROOT/tests/lib/graph-html-engine-helpers.sh"
+
+test_graph_html_has_truncate_label_markup_hooks() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" ".node-name"
+    assert_file_contains "$html" "text-overflow: ellipsis;"
+    assert_file_contains "$html" "white-space: nowrap;"
+    grep -Eq "title=[a-z]+\.label" "$html" || fail "Expected $html to contain minified node title assignment (title=<var>.label)"
+    assert_file_contains "$html" "node-kind"
+    assert_file_contains "$html" "node-meta"
+    assert_file_contains "$html" "display: none;"
+    assert_file_contains "$html" ".node:hover .node-kind"
+    assert_file_contains "$html" ".node:hover .node-meta"
+    assert_file_contains "$html" "graph-hover-preview"
+    assert_file_contains "$html" "graph-hover-preview-summary"
+    assert_file_contains "$html" "-webkit-line-clamp: 3;"
+    assert_file_contains "$html" "graph-reader-body pre"
+    assert_file_contains "$html" "overflow-wrap: anywhere;"
+
+    rm -rf "$tmp_dir"
+}
+
+test_default_nodes_hide_details_until_hover_or_selection() {
+    local tmp_dir html playwright_node_path
+    tmp_dir="$(mktemp -d)"
+
+    npm run build -w @llm-wiki/graph-engine > /dev/null 2>&1 \
+        || fail "graph-engine build should succeed before node slim browser regression"
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+    node - "$tmp_dir/wiki/graph-data.json" <<'NODE'
+const fs = require("fs");
+const file = process.argv[2];
+const graph = JSON.parse(fs.readFileSync(file, "utf8"));
+graph.nodes.push({
+  id: "empty-preview",
+  label: "空内容节点",
+  type: "topic",
+  community: "t1",
+  content: "",
+  source_path: "/fake/wiki/topics/empty-preview.md"
+});
+graph.meta.total_nodes = graph.nodes.length;
+fs.writeFileSync(file, `${JSON.stringify(graph, null, 2)}\n`);
+NODE
+    bash "$REPO_ROOT/scripts/build-graph-html.sh" "$tmp_dir" > /dev/null 2>&1 \
+        || fail "build-graph-html.sh should succeed on node preview fixture"
+    playwright_node_path="$(
+        npx --yes -p playwright -c 'node -e "const path=require(\"path\"); console.log(path.dirname(process.env.PATH.split(\":\")[0]))"'
+    )"
+
+    GRAPH_NODE_SLIM_HTML="$html" NODE_PATH="$playwright_node_path" node "$REPO_ROOT/tests/browser/graph-node-slim.mjs" \
+        || fail "default node slim browser regression should pass"
+
+    rm -rf "$tmp_dir"
+}
+
+test_label_truncation_helpers_are_carried_by_engine_bundle() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "truncateLabel"
+    assert_file_contains "$html" "splitLabelGraphemes"
+    assert_file_contains "$html" "cardDims"
+
+    rm -rf "$tmp_dir"
+}
+
+main() {
+    npm run build -w @llm-wiki/graph-engine > /dev/null 2>&1 \
+        || fail "graph-engine build should succeed before long-label regression"
+    test_graph_html_has_truncate_label_markup_hooks
+    test_label_truncation_helpers_are_carried_by_engine_bundle
+    test_default_nodes_hide_details_until_hover_or_selection
+    echo "PASS: graph HTML long-label regression coverage"
+}
+
+main "$@"

package/skills/llm-wiki-skill/tests/graph-html-minimap.regression-1.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Regression: engine graph HTML should keep minimap landmarks
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+source "$REPO_ROOT/tests/lib/graph-html-engine-helpers.sh"
+
+test_graph_html_has_minimap_markup() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" ".mini-map"
+    assert_file_contains "$html" ".mini-map svg"
+    assert_file_contains "$html" ".mini-map-viewport"
+    assert_file_contains "$html" ".mini-map .is-selected"
+    assert_file_contains "$html" "data-mini-map-viewport"
+    assert_file_contains "$html" 'viewBox`,`0 0 160 54`'
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_html_minimap_runtime_renders_nodes() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "t.minimap.nodes"
+    assert_file_contains "$html" '`circle`'
+    assert_file_contains "$html" '`is-selected`'
+    assert_file_contains "$html" "miniNodeElements"
+    assert_file_contains "$html" "miniViewportElement"
+    assert_file_contains "$html" "is-viewport-animating"
+
+    rm -rf "$tmp_dir"
+}
+
+main() {
+    npm run build -w @llm-wiki/graph-engine > /dev/null 2>&1 \
+        || fail "graph-engine build should succeed before minimap regression"
+    test_graph_html_has_minimap_markup
+    test_graph_html_minimap_runtime_renders_nodes
+    echo "PASS: graph HTML minimap regression coverage"
+}
+
+main "$@"

package/skills/llm-wiki-skill/tests/graph-html-mobile.regression-1.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Regression: engine offline graph HTML must remain responsive
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+source "$REPO_ROOT/tests/lib/graph-html-engine-helpers.sh"
+
+test_graph_html_has_responsive_css() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "@media (max-width: 720px)"
+    assert_file_contains "$html" ".offline-header { align-items: flex-start; flex-direction: column; }"
+    assert_file_contains "$html" ".offline-toolbar-host { width: 100%; flex-basis: auto; }"
+    assert_file_contains "$html" "#graph-root { min-height: 520px; }"
+    assert_file_contains "$html" "width: min(360px, calc(100% - 32px));"
+    assert_file_contains "$html" "overflow-wrap: anywhere;"
+
+    rm -rf "$tmp_dir"
+}
+
+test_graph_html_has_stable_mobile_shell_dimensions() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" ".offline-shell"
+    assert_file_contains "$html" "grid-template-rows: auto minmax(0, 1fr);"
+    assert_file_contains "$html" "#graph-root"
+    assert_file_contains "$html" "height: 100%;"
+    assert_file_contains "$html" "min-height: 560px;"
+
+    rm -rf "$tmp_dir"
+}
+
+main() {
+    test_graph_html_has_responsive_css
+    test_graph_html_has_stable_mobile_shell_dimensions
+    echo "PASS: graph HTML mobile regression coverage"
+}
+
+main "$@"

package/skills/llm-wiki-skill/tests/graph-html-oriental-atlas-contract.regression-1.sh

@@ -0,0 +1,94 @@
+#!/bin/bash
+# Regression: generated graph HTML must keep the approved engine atlas shell
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+source "$REPO_ROOT/tests/lib/graph-html-engine-helpers.sh"
+
+test_oriental_atlas_has_approved_engine_shell() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" 'class="offline-shell"'
+    assert_file_contains "$html" 'class="offline-header"'
+    assert_file_contains "$html" 'class="offline-badges"'
+    assert_file_contains "$html" 'id="graph-root"'
+    assert_file_contains "$html" "llm-wiki-graph-engine"
+    assert_file_contains "$html" "community-wash-layer"
+    assert_file_contains "$html" "edge-layer"
+    assert_file_contains "$html" "node-layer"
+    assert_file_contains "$html" ".mini-map"
+    assert_file_contains "$html" ".graph-reader"
+
+    rm -rf "$tmp_dir"
+}
+
+test_oriental_atlas_rejects_old_template_shell() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_not_contains "$html" 'id="nav-panel"'
+    assert_file_not_contains "$html" 'id="mode-switch"'
+    assert_file_not_contains "$html" 'id="nav-close"'
+    assert_file_not_contains "$html" 'id="secondary-panel"'
+    assert_file_not_contains "$html" 'id="dr-close"'
+    assert_file_not_contains "$html" 'class="drawer" id="drawer"'
+    assert_file_not_contains "$html" 'id="node-layer"'
+    assert_file_not_contains "$html" 'id="edge-layer"'
+    assert_file_not_contains "$html" "学习驾驶舱"
+    assert_file_not_contains "$html" "GitHub"
+
+    rm -rf "$tmp_dir"
+}
+
+test_oriental_atlas_has_required_copy() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "HTML测试知识库 知识舆图"
+    assert_file_contains "$html" "国风知识库·数字山水图"
+    assert_file_contains "$html" "3 节点"
+    assert_file_contains "$html" "2 关联"
+    assert_file_contains "$html" 'data-llm-wiki-offline-graph="engine"'
+    assert_file_contains "$html" "选择一个节点查看内容"
+
+    rm -rf "$tmp_dir"
+}
+
+test_oriental_atlas_runtime_uses_shared_engine_state() {
+    local tmp_dir html
+    tmp_dir="$(mktemp -d)"
+
+    build_graph_html_fixture "$tmp_dir"
+    html="$tmp_dir/wiki/knowledge-graph.html"
+
+    assert_file_contains "$html" "window.LlmWikiGraphEngine.createGraphEngine"
+    assert_file_contains "$html" "window.__LLM_WIKI_GRAPH_ENGINE__"
+    assert_file_contains "$html" "window.__LLM_WIKI_GRAPH_PINS_KEY__"
+    assert_file_contains "$html" "persistPins: function"
+    assert_file_contains "$html" "localStorage.setItem"
+    assert_file_not_contains "$html" "graph-wash.js"
+    assert_file_not_contains "$html" "graph-wash-helpers.js"
+
+    rm -rf "$tmp_dir"
+}
+
+main() {
+    test_oriental_atlas_has_approved_engine_shell
+    test_oriental_atlas_rejects_old_template_shell
+    test_oriental_atlas_has_required_copy
+    test_oriental_atlas_runtime_uses_shared_engine_state
+    echo "PASS: oriental atlas HTML contract regression coverage"
+}
+
+main "$@"