docs(core): [SITE-04] document component lifecycle and selector contracts

2026-10-13 07:46:17 -08:00 · 2026-09-16 05:13:52 +08:00
1 parent 5910c3f179
commit bb2fec8dd1
@@ -0,0 +1,50 @@
+# SITE-04 checkpoint: shared component contracts
+
+Six bilingual layers/controls/contextmenu guides now cover shared creation,
+configuration mutation, identity, insertion order, callbacks, updates and cleanup.
+The layer guide owns the common contract; the other guides link to it and explain
+their distinct return values, routing, selectors and desktop/mobile behavior.
+Existing runnable snippets are unchanged. Configuration tables now include
+beforeUnmount, numeric content/tooltips and the required top/left/right positions.
+
+The guides explain that update shallow-merges the original options before replacing
+the node, uses the merged beforeUnmount callback, and is not an atomic rollback.
+Controls retain undefined returns. Player destruction does not invoke every entry's
+beforeUnmount. The selector section covers initial labels, bound readonly metadata,
+HTML coercion, selection flags, latest-result ownership, removal and object reuse.
+Internal cache-entry types are not incorrectly advertised as runtime named exports.
+No production code, public declarations, dependencies or project scripts changed.
+
+The [core mapping](../core-content-review.json) adds 73 explicit declaration records
+from root/runtime component shapes and the three Artplayer manager properties.
+Total: 245 reviewed, 718 remaining out of 963. Counts include aliases and separate
+declaration shapes; they are not independent feature or overall completion counts.
+All seven previous groups' source and guide hashes were checked unchanged.
+
+## Verification
+
+- Six exact TS examples pass strict NodeNext with skipLibCheck:false and types:[].
+  All 24 previous Run Code snippets are unchanged and parse. Local links and
+  heading fragments resolve, including the shared component contract anchors.
+- Chromium 153.0.8010.12, Firefox 155.0 and Windows WebKit 26.6 pass 18 generated
+  page cases and all 72 code-forwarding checks. Popup targets are isolated; this
+  does not execute the online editor. Two Chromium screenshots were inspected.
+- Each engine passes 38 actual DOM assertions against core bytes matched to the
+  registered candidate. These cover manager aliases/cache/callbacks; duplicate,
+  missing, disabled and factory cases; ordering and numeric-zero fallbacks; shallow
+  replacement, listener release and throwing hooks; three control positions;
+  async selector races and removed results; item reuse/sharing; menu returns and
+  visibility; and destruction without per-entry hooks. No retries or page errors.
+- Existing component-resource/accessibility/documentation tests: 35 pass,
+  zero fail/skip, 1253.4366ms. This is not playback, SDK or physical-device proof.
+- Final build: 9.18s VitePress / 10.77s Yarn. LLM generation/check, inventory and
+  demo-route validation pass. Node 24.21.0, Yarn 1.22.22, TypeScript 5.9.3.
+- A failed edited-guide build is retained: bare generic type text was parsed as
+  HTML. Inline code formatting and accurate export wording fixed it. An earlier
+  ignored edit-helper fence syntax error happened before changing any guide.
+- All 21 library build envelopes remain valid; release blockers remain open.
+
+See [evidence](../baselines/site04-components.json). SITE-04 stays doing and totals
+remain 224/22/39. Continue remaining core groups, then the planned implementation
+checks. Formal review rounds remain user-directed. No push, deployment or publish.
+Revert this checkpoint to restore guides, generated pages, evidence and mapping.
@@ -3,13 +3,13 @@
  "task": "SITE-04",
  "inventory": {
    "path": "refactor/baselines/site-inventory.json",
-    "sha256": "a19f81c07794bdaf2004c2a1e3031546fb1b91d644e84dd9d2c789827c2b45df"
+    "sha256": "9fd886d897e4df9aacac7fb494dd3737fbc2bc935f7b6ec12964136a22570e2f"
  },
-  "reviewedAt": "2026-09-15T20:59:37.308Z",
+  "reviewedAt": "2026-09-15T21:13:25.985Z",
  "counts": {
    "inventoryRecords": 963,
-    "reviewedRecords": 172,
-    "unreviewedRecords": 791
+    "reviewedRecords": 245,
+    "unreviewedRecords": 718
  },
  "note": "Explicit declaration-record semantic mapping, including overload/getter/setter rows and root/runtime aliases. Counts are not overall API or release completion. Recheck affected groups if their source/document hashes drift. Other declarations and inline members are not implicitly covered.",
  "groups": [
@@ -1605,6 +1605,643 @@
        }
      ],
      "evidence": "baselines/site04-template-icons.json"
+    },
+    {
+      "id": "components",
+      "status": "semantic-reviewed",
+      "conclusion": "Layer/control/contextmenu managers, root/runtime shapes and numeric overloads; config mutation, names/aliases/order, node movement and callback receivers; shallow nontransactional replacement, returns, missing/disabled entries and hook failure; scoped cleanup versus destroy hook; selector flags, coercion, bindings, async generations and reuse; controls routing/state/init and mobile context-menu boundary.",
+      "records": [
+        {
+          "id": "packages/artplayer/public/artplayer.ts#Artplayer.layers@174",
+          "file": "packages/artplayer/public/artplayer.ts",
+          "declaration": "Artplayer",
+          "name": "layers",
+          "line": 174
+        },
+        {
+          "id": "packages/artplayer/public/artplayer.ts#Artplayer.controls@175",
+          "file": "packages/artplayer/public/artplayer.ts",
+          "declaration": "Artplayer",
+          "name": "controls",
+          "line": 175
+        },
+        {
+          "id": "packages/artplayer/public/artplayer.ts#Artplayer.contextmenu@176",
+          "file": "packages/artplayer/public/artplayer.ts",
+          "declaration": "Artplayer",
+          "name": "contextmenu",
+          "line": 176
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentInput.html@5",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentInput",
+          "name": "html",
+          "line": 5
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Selector.default@12",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Selector",
+          "name": "default",
+          "line": 12
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Selector.html@17",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Selector",
+          "name": "html",
+          "line": 17
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Selector.value@22",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Selector",
+          "name": "value",
+          "line": 22
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.id@34",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "id",
+          "line": 34
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.name@39",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "name",
+          "line": 39
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.$parent@44",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "$parent",
+          "line": 44
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.show@49",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "show",
+          "line": 49
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.show@54",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "show",
+          "line": 54
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.toggle@59",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "toggle",
+          "line": 59
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.add@64",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "add",
+          "line": 64
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.remove@72",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "remove",
+          "line": 72
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#Component.update@77",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "Component",
+          "name": "update",
+          "line": 77
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.html@87",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "html",
+          "line": 87
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.disable@92",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "disable",
+          "line": 92
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.name@97",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "name",
+          "line": 97
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.index@102",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "index",
+          "line": 102
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.style@107",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "style",
+          "line": 107
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.click@112",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "click",
+          "line": 112
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.mounted@117",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "mounted",
+          "line": 117
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.beforeUnmount@122",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "beforeUnmount",
+          "line": 122
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.tooltip@127",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "tooltip",
+          "line": 127
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.position@132",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "position",
+          "line": 132
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.selector@137",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "selector",
+          "line": 137
+        },
+        {
+          "id": "packages/artplayer/public/component.ts#ComponentOption.onSelect@142",
+          "file": "packages/artplayer/public/component.ts",
+          "declaration": "ComponentOption",
+          "name": "onSelect",
+          "line": 142
+        },
+        {
+          "id": "packages/artplayer/public/runtime.ts#Artplayer.layers@87",
+          "file": "packages/artplayer/public/runtime.ts",
+          "declaration": "Artplayer",
+          "name": "layers",
+          "line": 87
+        },
+        {
+          "id": "packages/artplayer/public/runtime.ts#Artplayer.controls@88",
+          "file": "packages/artplayer/public/runtime.ts",
+          "declaration": "Artplayer",
+          "name": "controls",
+          "line": 88
+        },
+        {
+          "id": "packages/artplayer/public/runtime.ts#Artplayer.contextmenu@89",
+          "file": "packages/artplayer/public/runtime.ts",
+          "declaration": "Artplayer",
+          "name": "contextmenu",
+          "line": 89
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#SelectorItem.html@4",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "SelectorItem",
+          "name": "html",
+          "line": 4
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#SelectorItem.value@5",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "SelectorItem",
+          "name": "value",
+          "line": 5
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#SelectorItem.default@6",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "SelectorItem",
+          "name": "default",
+          "line": 6
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#SelectorItem.$control_option@7",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "SelectorItem",
+          "name": "$control_option",
+          "line": 7
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#SelectorItem.$control_item@8",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "SelectorItem",
+          "name": "$control_item",
+          "line": 8
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#SelectorItem.$control_value@9",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "SelectorItem",
+          "name": "$control_value",
+          "line": 9
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.html@13",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "html",
+          "line": 13
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.disable@14",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "disable",
+          "line": 14
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.name@15",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "name",
+          "line": 15
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.index@16",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "index",
+          "line": 16
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.style@17",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "style",
+          "line": 17
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.tooltip@18",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "tooltip",
+          "line": 18
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.position@19",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "position",
+          "line": 19
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.selector@20",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "selector",
+          "line": 20
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.click@21",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "click",
+          "line": 21
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.mounted@22",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "mounted",
+          "line": 22
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.beforeUnmount@23",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "beforeUnmount",
+          "line": 23
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentOption.onSelect@24",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentOption",
+          "name": "onSelect",
+          "line": 24
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ControlOption.position@30",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ControlOption",
+          "name": "position",
+          "line": 30
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentEntry.$ref@36",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentEntry",
+          "name": "$ref",
+          "line": 36
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentEntry.events@37",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentEntry",
+          "name": "events",
+          "line": 37
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#ComponentEntry.option@38",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "ComponentEntry",
+          "name": "option",
+          "line": 38
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.id@42",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "id",
+          "line": 42
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.art@43",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "art",
+          "line": 43
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.name@44",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "name",
+          "line": 44
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.$parent@45",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "$parent",
+          "line": 45
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.cache@46",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "cache",
+          "line": 46
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.show@47",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "show",
+          "line": 47
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.toggle@48",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "toggle",
+          "line": 48
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.add@49",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "add",
+          "line": 49
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.remove@50",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "remove",
+          "line": 50
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.update@51",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "update",
+          "line": 51
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Component.selector@52",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Component",
+          "name": "selector",
+          "line": 52
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.isHover@56",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "isHover",
+          "line": 56
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.timer@57",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "timer",
+          "line": 57
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.setting@58",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "setting",
+          "line": 58
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.thumbnails@59",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "thumbnails",
+          "line": 59
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.init@60",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "init",
+          "line": 60
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.add@61",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "add",
+          "line": 61
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.update@62",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "update",
+          "line": 62
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.check@63",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "check",
+          "line": 63
+        },
+        {
+          "id": "packages/artplayer/public/runtime/component.ts#Controls.selector@64",
+          "file": "packages/artplayer/public/runtime/component.ts",
+          "declaration": "Controls",
+          "name": "selector",
+          "line": 64
+        }
+      ],
+      "sources": [
+        {
+          "path": "packages/artplayer/src/utils/component.ts",
+          "sha256": "c3fa96467e8b315d974a42a19591aa4a4a7514853db796135b2acbcdcb160ea3"
+        },
+        {
+          "path": "packages/artplayer/src/component/types.ts",
+          "sha256": "d7b0e7008b0f6c82e3e97ac43e0188598dca4f740a860e7a60b3b38a46f4565d"
+        },
+        {
+          "path": "packages/artplayer/src/component/dom.ts",
+          "sha256": "740f63e6e5942c444b9f05605880f8d56a77b066dbe5c4791da74f78cb96c668"
+        },
+        {
+          "path": "packages/artplayer/src/component/resources.ts",
+          "sha256": "ff158ef0db8ba13343ff6ba329713820cfe2f5c2c446a7873a6cfff782855edf"
+        },
+        {
+          "path": "packages/artplayer/src/component/focus.ts",
+          "sha256": "f4aff802711f6146c80e8c6bd90bc2cb406ccbdb581aef41f436ff5c03871ad3"
+        },
+        {
+          "path": "packages/artplayer/src/component/selection.ts",
+          "sha256": "1f0bd089415da28db862647ffd1a0b4af752576465fb616d4b97ae4f8dcae3a7"
+        },
+        {
+          "path": "packages/artplayer/src/control/index.ts",
+          "sha256": "0d8e5a281f2eeba06c4cc4ac5a042847df53db1a19fdf140efea17d6ab2c0b78"
+        },
+        {
+          "path": "packages/artplayer/src/control/builtins.ts",
+          "sha256": "2a0e12a9741713c92938e1d2009149bbbde498284aa85c63f270d02b27dc22b1"
+        },
+        {
+          "path": "packages/artplayer/src/control/selector.ts",
+          "sha256": "a6f0c564c674530da9a0e4ed8762c6dfb81fa89373d64313e1020550731441f6"
+        },
+        {
+          "path": "packages/artplayer/src/control/selector-keyboard.ts",
+          "sha256": "6a749f48b23cda62148298e648bb380a6067cc18c7be4258b9ec85c382a56165"
+        },
+        {
+          "path": "packages/artplayer/src/layer.ts",
+          "sha256": "4014268eed043d5dd7b925cdeef6245e357cda67192a1301c5612ef98cdbec12"
+        },
+        {
+          "path": "packages/artplayer/src/contextmenu/index.ts",
+          "sha256": "7532165d162fa463f1fe3c538d6bda0f579b5907b05137382efeb0018719b011"
+        },
+        {
+          "path": "packages/artplayer/src/contextmenu/keyboard.ts",
+          "sha256": "eaa1af6b1abf8947d957208a0535f1b34f6c88e95394efd56cae905ccdea564c"
+        },
+        {
+          "path": "packages/artplayer/src/contextmenu/position.ts",
+          "sha256": "851ed1a884a13fbe430be77e7f72ae46d8a719175647e058644834aabd27ac58"
+        },
+        {
+          "path": "packages/artplayer/src/scheme/index.ts",
+          "sha256": "dc4a3b5e08478cf72b46b0b59c023359ad5f79b891ea8a6a119ce24a5251821a"
+        },
+        {
+          "path": "packages/artplayer/src/dom/tree.ts",
+          "sha256": "3bc517ab9fa5317a1445156d53afb27182685eb3b4c0ac2ff41bbde55c9eecb6"
+        },
+        {
+          "path": "packages/artplayer/src/lifecycle/instance.ts",
+          "sha256": "3168f7db4271bae7a242e80798546b755ac15443e15dd9ebb7675f5a259299d8"
+        },
+        {
+          "path": "packages/artplayer/public/artplayer.ts",
+          "sha256": "26a42ac66811e70f68a8ebe62cbf304eb1993451b3e658961be98e7106162527"
+        },
+        {
+          "path": "packages/artplayer/public/component.ts",
+          "sha256": "aa1c43be67322781b4b355b143bc69d9f29d22e578e4974d6a13e957a7c0334f"
+        },
+        {
+          "path": "packages/artplayer/public/runtime.ts",
+          "sha256": "ec4b1d56993eb482a77eb0f94b701047549d009e6ba6433f27e7d464fef30c2b"
+        },
+        {
+          "path": "packages/artplayer/public/runtime/component.ts",
+          "sha256": "840213299c942fe058eb5436977ceec066b9dccda24c55ae9f464b399c979e39"
+        }
+      ],
+      "docs": [
+        {
+          "path": "packages/artplayer-vitepress/docs/component/layers.md",
+          "sha256": "70c33c261db52675db4ee87258893abe6a735b6fc13c8918982753dce876a10f",
+          "anchor": "component-contract"
+        },
+        {
+          "path": "packages/artplayer-vitepress/docs/component/controls.md",
+          "sha256": "a6e6336216320f1be37980cc17c08c4d1e4e3eb95711dd30f54b29f210bd9b28",
+          "anchor": "control-contract"
+        },
+        {
+          "path": "packages/artplayer-vitepress/docs/component/contextmenu.md",
+          "sha256": "aa8721dff63d86684ece122f13a7cdd6e8bfa8de11ee9822de221858a79e395e",
+          "anchor": "contextmenu-contract"
+        },
+        {
+          "path": "packages/artplayer-vitepress/docs/en/component/layers.md",
+          "sha256": "62f73b48fac53397c9c2a3ce846db8cf3fc466383ba38a7ea3001c81e92b82d0",
+          "anchor": "component-contract"
+        },
+        {
+          "path": "packages/artplayer-vitepress/docs/en/component/controls.md",
+          "sha256": "b88bad51d3791f6ee2ef51b3f6005ce1a20707add9c4efc52418d0c97cfad800",
+          "anchor": "control-contract"
+        },
+        {
+          "path": "packages/artplayer-vitepress/docs/en/component/contextmenu.md",
+          "sha256": "a4f1bd30fe36283b2a07cdfc49306a41644367d98e5bb3eb849645aa8ae55bb8",
+          "anchor": "contextmenu-contract"
+        }
+      ],
+      "evidence": "baselines/site04-components.json"
    }
  ]
 }
@@ -687,7 +687,7 @@
 - SITE-DANMUKU-01: [记录](changes/2026-09-15-SITE-DANMUKU-01-guides.md) [记录](baselines/danmuku-docs-validation.json)
 - SITE-HLS-01: [记录](changes/2026-09-15-SITE-HLS-01-guides.md) [记录](baselines/hls-docs-validation.json)
 - SITE-DASH-01: [记录](changes/2026-09-15-SITE-DASH-01-guides.md) [记录](baselines/dash-docs-validation.json)
- SITE-04: [记录](site-content-review.md) [记录](changes/2026-09-16-SITE-04-chapter-ambilight-guides.md) [记录](baselines/site04-chapter-ambilight-guides.json) [记录](changes/2026-09-16-SITE-04-dpip-asr-guides.md) [记录](baselines/site04-dpip-asr-guides.json) [记录](changes/2026-09-16-SITE-04-auto-multi-guides.md) [记录](baselines/site04-auto-multi-guides.json) [记录](changes/2026-09-16-SITE-04-ads-vast-guides.md) [记录](baselines/site04-ads-vast-guides.json) [记录](changes/2026-09-16-SITE-04-jassub-mask-cast-guides.md) [记录](baselines/site04-jassub-mask-cast-guides.json) [记录](changes/2026-09-16-SITE-04-tools-guides.md) [记录](baselines/site04-tools-guides.json) [记录](changes/2026-09-16-SITE-04-proxies-guides.md) [记录](baselines/site04-proxies-guides.json) [记录](changes/2026-09-16-SITE-04-existing-guides.md) [记录](baselines/site04-existing-guides.json) [记录](core-content-review.json) [记录](baselines/site04-core-services.json) [记录](changes/2026-09-16-SITE-04-core-services.md) [记录](baselines/site04-template-icons.json) [记录](changes/2026-09-16-SITE-04-template-icons.md)
+- SITE-04: [记录](site-content-review.md) [记录](changes/2026-09-16-SITE-04-chapter-ambilight-guides.md) [记录](baselines/site04-chapter-ambilight-guides.json) [记录](changes/2026-09-16-SITE-04-dpip-asr-guides.md) [记录](baselines/site04-dpip-asr-guides.json) [记录](changes/2026-09-16-SITE-04-auto-multi-guides.md) [记录](baselines/site04-auto-multi-guides.json) [记录](changes/2026-09-16-SITE-04-ads-vast-guides.md) [记录](baselines/site04-ads-vast-guides.json) [记录](changes/2026-09-16-SITE-04-jassub-mask-cast-guides.md) [记录](baselines/site04-jassub-mask-cast-guides.json) [记录](changes/2026-09-16-SITE-04-tools-guides.md) [记录](baselines/site04-tools-guides.json) [记录](changes/2026-09-16-SITE-04-proxies-guides.md) [记录](baselines/site04-proxies-guides.json) [记录](changes/2026-09-16-SITE-04-existing-guides.md) [记录](baselines/site04-existing-guides.json) [记录](core-content-review.json) [记录](baselines/site04-core-services.json) [记录](changes/2026-09-16-SITE-04-core-services.md) [记录](baselines/site04-template-icons.json) [记录](changes/2026-09-16-SITE-04-template-icons.md) [记录](baselines/site04-components.json) [记录](changes/2026-09-16-SITE-04-components.md)
 - SITE-07: [记录](site-inventory.md) [记录](baselines/site-provenance.json) [记录](changes/2026-09-14-SITE-07-vendor-notices.md) [记录](baselines/site-notices-checkpoint.json) [记录](baselines/site-codicons-provenance.json) [记录](baselines/site-codicons-validation.json) [记录](changes/2026-09-15-SITE-07-codicons.md) [记录](baselines/vconsole-notices-provenance.json) [记录](baselines/vconsole-notices-validation.json) [记录](changes/2026-09-15-SITE-07-vconsole-notices.md) [记录](console-modernization.md) [记录](baselines/site-console-inventory.json) [记录](baselines/site-console-validation.json) [记录](changes/2026-09-15-SITE-07-console-baseline.md) [记录](baselines/console-feed-provenance.json) [记录](changes/2026-09-15-SITE-07-console-feed-source.md) [记录](baselines/console-commonjs-provenance.json) [记录](changes/2026-09-15-SITE-07-console-commonjs.md) [记录](baselines/console-esm-provenance.json) [记录](changes/2026-09-15-SITE-07-console-esm.md) [记录](baselines/console-embedded-notices.json) [记录](baselines/console-notices-validation.json) [记录](changes/2026-09-15-SITE-07-console-notices.md) [记录](baselines/console-embedded-sources.json) [记录](baselines/console-embedded-validation.json) [记录](changes/2026-09-15-SITE-07-console-embedded-sources.md) [记录](baselines/console-derived-attribution.json) [记录](baselines/console-derived-validation.json) [记录](changes/2026-09-15-SITE-07-console-derived-attribution.md) [记录](baselines/console-stackoverflow-provenance.json) [记录](baselines/console-stackoverflow-validation.json) [记录](changes/2026-09-15-SITE-07-console-stackoverflow.md) [记录](baselines/console-shallowequal-validation.json) [记录](changes/2026-09-15-SITE-07-console-shallowequal.md) [记录](console-notice-review.md) [记录](baselines/console-notice-review-validation.json) [记录](changes/2026-09-15-SITE-07-console-notice-review.md) [记录](baselines/monaco-typescript-provenance.json) [记录](baselines/monaco-typescript-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-typescript.md) [记录](baselines/monaco-languages-provenance.json) [记录](baselines/monaco-languages-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-languages.md) [记录](baselines/monaco-language-notices.json) [记录](baselines/monaco-language-notices-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-language-notices.md) [记录](baselines/monaco-modes-provenance.json) [记录](baselines/monaco-modes-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-modes.md) [记录](baselines/monaco-basic-provenance.json) [记录](baselines/monaco-basic-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-basic.md) [记录](baselines/monaco-core-origins-provenance.json) [记录](baselines/monaco-core-origins-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-core-origins.md) [记录](baselines/monaco-core-build-provenance.json) [记录](baselines/monaco-core-build-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-core-build.md) [记录](baselines/monaco-contributions-provenance.json) [记录](baselines/monaco-contributions-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-contributions.md) [记录](baselines/monaco-css-build-provenance.json) [记录](baselines/monaco-css-build-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-css.md) [记录](baselines/monaco-node-path-provenance.json) [记录](baselines/monaco-node-path-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-node-path.md) [记录](changes/2026-09-15-SITE-07-monaco-dom.md) [记录](baselines/monaco-dom-origins-validation.json) [记录](changes/2026-09-15-SITE-07-monaco-unicode.md) [记录](baselines/monaco-unicode-provenance.json) [记录](baselines/monaco-unicode-validation.json) [记录](changes/2026-09-15-SITE-07-font-notices.md) [记录](baselines/site-font-notices-provenance.json) [记录](baselines/site-font-notices-validation.json)
 - EX-01: [记录](changes/2026-09-14-EX-01-react-consumer.md) [记录](baselines/react-consumer-validation.json) [记录](scripts/react-consumer.mjs)
 - EX-02: [记录](changes/2026-09-14-EX-02-vue-consumer.md) [记录](baselines/vue-consumer-validation.json) [记录](scripts/vue-consumer.mjs)
@@ -1,5 +1,14 @@
 # 进度与证据

+## SITE-04 核心公共组件语义映射
+
+核对layers/controls/contextmenu的公共接口、配置修改、浅合并替换、回调/清理、
+返回值与选择器异步归属，补齐六份双语指南；73条新声明映射使累计达到245/963，
+718条仍待核对。六份严格TS、18组页面、72次代码转发、三浏览器各38项DOM断言及
+35项现有测试通过。见[记录](changes/2026-09-16-SITE-04-components.md)及
+[证据](baselines/site04-components.json)。文档初次构建的泛型文本HTML解析失败已修复并保留日志。
+21库build证据仍有效；SITE-04保持doing，224/22/39不变，不进入正式复盘。
+
 ## SITE-04 核心模板和图标语义映射

 补齐高级属性和静态属性的四份双语指南，明确节点/查询、SSR、静态HTML、图标节点
@@ -79,6 +79,12 @@ setter重复形状；不能当成81个独立功能。两份高级属性指南与
 18次转发、三浏览器各63项DOM断言及31项测试通过。前五组的相关指南段落与源码
 指纹均复核未变后才更新整页哈希；本页未涉及的组件等章节不因此自动算通过。

+公共组件随后新增73条：根/runtime组件、配置、选择项和三个实例管理器入口。
+六份layers/controls/contextmenu指南补齐共享规则及各自差异；累计245条映射，718条
+仍待核对。六份严格TS、18组页面、72次转发、三浏览器各38项实际DOM断言及35项
+现有测试通过，见[证据](baselines/site04-components.json)。前七组源码/指南哈希不变。
+设置面板、剩余播放/事件/工具等声明不会因此自动算通过。
+
 - 核心：依据 site-inventory.json 的 963 条成员逐项或按明确的共享声明分组核对；
  必须记录对应文档及语义结论，不能仅按同名标题匹配标为通过。
 - Danmuku、HLS、DASH、Audio、VTT 的当前声明/源码语义已补核对；既有媒体报告
@@ -4577,7 +4577,9 @@
        "baselines/site04-core-services.json",
        "changes/2026-09-16-SITE-04-core-services.md",
        "baselines/site04-template-icons.json",
-        "changes/2026-09-16-SITE-04-template-icons.md"
+        "changes/2026-09-16-SITE-04-template-icons.md",
+        "baselines/site04-components.json",
+        "changes/2026-09-16-SITE-04-components.md"
      ]
    },
    {