@proteus-vue/component-ir 0.3.0-beta.11 → 0.3.0-beta.21

package/dist/index.d.ts

@@ -15,3 +15,12 @@ export { classifySpecApi, classifySpecComponent, auditSpecCoverage, auditSpecOve
 export type { MpSpecStatus, MpSpecClass, MpOfficialSpec, SpecCoverageReport } from './mp-spec-coverage';
 export { DEGRADATION_TABLE, MP_UNSUPPORTED_PROPS, degradeProp, degradationOf, auditDegradation, formatDegradationReport, checkPropDegradation, collectPropDiagnostics, RULE_REGISTERED_PROPS, HOST_FALLBACK_TAGS, PROP_NO_DEGRADATION, } from './degradation';
 export type { DegradationEnd, DegradationTier, DegradationEntry, DegradationMap, DegradationIssue, DegradationReport, PropDiagnostic, } from './degradation';
+export type { PKind, ResolvedLength, Edges, LayoutProps, PaintProps, TextProps, PaintHint, PProps, PFlags, PNode, PTree, DynamicBinding, UpdateKind, PDiagnostic, } from './pnode';
+export { resolveLength, parseStyleString, normalizeStyleDecls, normalizeStyleString, expandEdges, parseTransform, camel, splitTopLevel } from './pnode-style';
+export type { LengthContext, NormalizeOptions, NormalizeResult } from './pnode-style';
+export { analyzePTree, flattenRate, groupBindingsByNode } from './pnode-analyze';
+export type { AnalyzeOptions, AnalyzeResult, NodeFacts } from './pnode-analyze';
+export { buildPTree, buildPTreeFromComponentIR, rawFromComponentIR, kindFromSemantic, inferUpdateKind, inferOpCode } from './pnode-build';
+export type { PRawNode, BuildOptions } from './pnode-build';
+export { formatPTrace, formatPNodeLine, decisionOf, walkPTree } from './pnode-trace';
+export type { PTraceOptions } from './pnode-trace';

package/dist/index.js

@@ -20,6 +20,8 @@ var SEMANTIC_ENUM = [
   // ★#405 语义登记批：组件库扩展组件（Fluid S1-S4 + 工程兜底，语义层待 L2 落地——G-31.4 降级 planned）
   "layout.aspect",
   "layout.zone",
+  "layout.formfactor",
+  // ★★Fluid System v2：柔性形态容器（形态编排）
   // —— 基础 UI 原语（G-32 ② UI 18 + 既有按钮）——
   "ui.text",
   "ui.heading",
@@ -191,6 +193,8 @@ var TAG_SEMANTIC_MAP = {
   //    ——同一语义由两个标签提供；本条与 p-view 是并列的别名情形，非「先例」关系）
   "p-aspect": "layout.aspect",
   "p-zone": "layout.zone",
+  "p-formfactor": "layout.formfactor",
+  // ★★Fluid System v2：柔性形态容器
   "p-loading": "ui.loading",
   "p-scale": "ui.scale",
   "p-skeleton": "ui.skeleton",
@@ -386,6 +390,16 @@ var SEMANTIC_BACKEND_MAP = {
     flutter: "NavigationRail",
     headless: "sidebar"
   },
+  // ★★Fluid System v2（2026-09-26）：柔性形态容器——各端按形态画像编排拓扑/能力/密度/缩放
+  "layout.formfactor": {
+    "vue-dom": "div.proteus-formfactor",
+    "native-ios": "UIViewController.formFactor",
+    "native-android": "FormFactorLayout",
+    "native-harmony": "GridRow.formFactor",
+    skyline: "view.formfactor",
+    flutter: "LayoutBuilder.formFactor",
+    headless: "formfactor"
+  },
   // —— 基础 UI 原语 ——
   "ui.text": {
     "vue-dom": "span",
@@ -995,6 +1009,8 @@ var LAYOUT = [
   // ★#405 语义登记批：Fluid 体系剩余组件（语义层待多端映射 → planned L2——G-31.4 不足 3 端降级）
   { id: "L13", kind: "layout", semantic: "layout.aspect", tag: "p-aspect", props: ["ratio", "maxWidth"], mpEquiv: "\u65E0\uFF08\u7EB5\u6A2A\u6BD4\u5BB9\u5668\uFF09", tier: "L2", status: "planned" },
   { id: "L14", kind: "layout", semantic: "layout.zone", tag: "p-zone", props: ["designWidth"], mpEquiv: "\u65E0\uFF08\u5BB9\u5668\u65AD\u70B9\u5206\u533A\uFF09", tier: "L2", status: "planned" },
+  // ★★Fluid System v2（2026-09-26）：柔性形态容器——按设备形态自动编排布局拓扑/能力/密度/缩放
+  { id: "L26", kind: "layout", semantic: "layout.formfactor", tag: "p-formfactor", props: ["declared", "width", "height"], mpEquiv: "\u65E0\uFF08\u5F62\u6001\u7F16\u6392\u5BB9\u5668\uFF1Aglance/stack/duo/rail-split/rail-grid/dashboard/hero-focus-row\uFF09", tier: "L2", status: "implemented" },
   // ★批次 7（2026-09-18）未登记组件补登记：安全区（刘海/折叠屏/降级）+ 侧边导航容器
   { id: "L15", kind: "layout", semantic: "layout.safe", tag: "p-safe", props: ["area", "fold", "fallback"], mpEquiv: "\u65E0\uFF08\u5B89\u5168\u533A\u8BED\u4E49\u5BB9\u5668\uFF09", tier: "L1", status: "implemented" },
   { id: "L16", kind: "layout", semantic: "layout.sidebar", tag: "p-sidebar", props: ["minSidebarWidth", "navWidth", "designWidth", "toggleLabel"], mpEquiv: "\u65E0\uFF08\u5BB9\u5668\u65AD\u70B9\u4FA7\u680F\uFF09", tier: "L1", status: "implemented" }
@@ -2317,6 +2333,688 @@ function collectPropDiagnostics(tag, props, end, table = DEGRADATION_TABLE) {
   }
   return out;
 }
+
+// src/pnode-style.ts
+function resolveLength(raw, ctx = { axis: "horizontal" }) {
+  const v = raw.trim().toLowerCase();
+  if (!v) return void 0;
+  if (v === "0" || /^0(\.0+)?$/.test(v)) return { kind: "absolute", dp: 0 };
+  if (v === "auto") return void 0;
+  const m = /^(-?\d*\.?\d+)\s*([a-z%]*)$/.exec(v);
+  if (!m) return void 0;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n)) return void 0;
+  switch (m[2]) {
+    case "":
+    case "px":
+      return { kind: "absolute", dp: n };
+    case "%":
+      return {
+        kind: "ratio",
+        ratio: n / 100,
+        base: ctx.axis === "vertical" ? "parentHeight" : "parentWidth"
+      };
+    case "vw":
+      return { kind: "ratio", ratio: n / 100, base: "viewportWidth" };
+    case "vh":
+      return { kind: "ratio", ratio: n / 100, base: "viewportHeight" };
+    case "rpx":
+      return { kind: "ratio", ratio: n / 750, base: "viewportWidth" };
+    case "em":
+      return { kind: "ratio", ratio: n, base: "fontSize" };
+    case "rem":
+      return { kind: "ratio", ratio: n, base: "rootFontSize" };
+    case "pt":
+      return { kind: "absolute", dp: n };
+    default:
+      return void 0;
+  }
+}
+function parseStyleString(style) {
+  const out = {};
+  for (const decl of style.split(";")) {
+    const i = decl.indexOf(":");
+    if (i <= 0) continue;
+    const key = camel(decl.slice(0, i).trim());
+    const val = decl.slice(i + 1).trim();
+    if (key && val) out[key] = val;
+  }
+  return out;
+}
+function camel(k) {
+  return k.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+}
+function splitTopLevel(value) {
+  const parts = [];
+  let depth = 0;
+  let cur = "";
+  for (const ch of value) {
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    if (/\s/.test(ch) && depth === 0) {
+      if (cur) parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur) parts.push(cur);
+  return parts;
+}
+function expandEdges(parts) {
+  const [a, b, c, d] = parts;
+  if (parts.length === 1) return { top: a, right: a, bottom: a, left: a };
+  if (parts.length === 2) return { top: a, right: b, bottom: a, left: b };
+  if (parts.length === 3) return { top: a, right: b, bottom: c, left: b };
+  return { top: a, right: b, bottom: c, left: d };
+}
+function parseTransform(raw) {
+  const t = {};
+  let threeD = false;
+  for (const m of raw.matchAll(/([a-zA-Z0-9]+)\(([^)]*)\)/g)) {
+    const fn = m[1].toLowerCase();
+    const args = m[2].split(",").map((s) => s.trim());
+    const num = (i) => Number.parseFloat(args[i] ?? "0");
+    switch (fn) {
+      case "translatex":
+        t.translateX = resolveLength(args[0] ?? "0")?.kind === "absolute" ? resolveLength(args[0]).dp : num(0);
+        break;
+      case "translatey":
+        t.translateY = resolveLength(args[0] ?? "0")?.kind === "absolute" ? resolveLength(args[0]).dp : num(0);
+        break;
+      case "translate":
+        t.translateX = num(0);
+        t.translateY = num(1);
+        break;
+      case "scale":
+        t.scale = args.length > 1 ? num(0) : num(0);
+        break;
+      case "rotate":
+        t.rotate = args[0]?.endsWith("deg") ? num(0) : num(0);
+        break;
+      // 3D（L3：创建合成层）
+      case "translatez":
+      case "translate3d":
+      case "rotatex":
+      case "rotatey":
+      case "rotate3d":
+      case "perspective":
+      case "matrix3d":
+        threeD = true;
+        break;
+      default:
+        threeD = true;
+        break;
+    }
+  }
+  return { t, threeD };
+}
+var L3_PROPS = /* @__PURE__ */ new Set([
+  "zIndex",
+  "boxShadow",
+  "filter",
+  "backdropFilter",
+  "willChange",
+  "position"
+  // 仅 fixed/sticky 属 L3（由值判定）
+]);
+var OUT_OF_PROFILE = /* @__PURE__ */ new Set([
+  "gridTemplateColumns",
+  "gridTemplateRows",
+  "gridArea",
+  "gridColumn",
+  "gridRow",
+  "float",
+  "clear",
+  "animation",
+  "animationName",
+  "animationDuration",
+  "transition",
+  "transitionProperty",
+  "cursor",
+  "userSelect",
+  "content",
+  "clipPath",
+  "mask",
+  "mixBlendMode"
+]);
+var L4_PASSTHROUGH = /* @__PURE__ */ new Set(["fontFamily", "fontStyle", "fontVariant", "textDecoration", "direction", "unicodeBidi"]);
+function normalizeStyleDecls(decls, opts = {}) {
+  const layout = {};
+  const paint = {};
+  const text = {};
+  const diagnostics = [];
+  const push = (severity, code, message) => {
+    diagnostics.push({ severity, code, message, nodeId: opts.nodeId, source: opts.source });
+  };
+  const len = (raw, axis = "horizontal") => {
+    const r = resolveLength(raw, { axis });
+    if (r === void 0 && raw.trim().toLowerCase() !== "auto") {
+      push("warn", "css.invalid-length", `\u65E0\u6CD5\u6298\u53E0\u7684\u957F\u5EA6\u503C\u300C${raw}\u300D\uFF08profile \u652F\u6301 px/%/vw/vh/rpx/em/rem/pt\uFF09`);
+    }
+    return r;
+  };
+  let needsCompositing = false;
+  let hasTransform = false;
+  for (const [kRaw, raw] of Object.entries(decls)) {
+    const k = camel(kRaw);
+    const v = raw.trim();
+    if (!v) continue;
+    if (OUT_OF_PROFILE.has(k)) {
+      push("error", "css.out-of-profile", `\u5C5E\u6027 ${kRaw} \u4E0D\u5728 CSS Profile \u5185\uFF08\u7F16\u8BD1\u671F\u62E6\u622A\uFF0C\u4E0D\u7559\u8FD0\u884C\u65F6\u9759\u9ED8\u964D\u7EA7\uFF09`);
+      continue;
+    }
+    if (L4_PASSTHROUGH.has(k)) continue;
+    switch (k) {
+      /* ── 布局（L2） ── */
+      case "display":
+        if (v === "flex" || v === "none" || v === "block" || v === "inline-block") layout.display = v;
+        else if (v === "grid") push("error", "css.grid-unsupported", "display:grid \u4E0D\u5728 Profile\uFF08\u5F85\u5B9A\u2014\u2014\u5EFA\u8BAE\u6539\u5D4C\u5957 flex\uFF09");
+        else push("warn", "css.invalid-value", `display:${v} \u672A\u652F\u6301`);
+        break;
+      case "flexDirection":
+        if (v === "row" || v === "column" || v === "row-reverse" || v === "column-reverse") layout.flexDirection = v;
+        break;
+      case "flexWrap":
+        if (v === "nowrap" || v === "wrap" || v === "wrap-reverse") layout.flexWrap = v;
+        break;
+      case "justifyContent":
+      case "alignItems":
+      case "alignSelf":
+      case "alignContent":
+        layout[k] = v;
+        break;
+      case "flexGrow":
+        layout.flexGrow = Number(v);
+        break;
+      case "flexShrink":
+        layout.flexShrink = Number(v);
+        break;
+      case "flexBasis":
+        layout.flexBasis = v === "auto" ? "auto" : len(v);
+        break;
+      case "flex": {
+        if (/^-?\d*\.?\d+$/.test(v)) {
+          layout.flexGrow = Number(v);
+          layout.flexShrink = 1;
+          layout.flexBasis = { kind: "absolute", dp: 0 };
+        }
+        break;
+      }
+      case "gap":
+      case "rowGap":
+      case "columnGap": {
+        layout[k] = len(v);
+        break;
+      }
+      case "width":
+      case "minWidth":
+      case "maxWidth":
+        layout[k] = len(v, "horizontal");
+        break;
+      case "height":
+      case "minHeight":
+      case "maxHeight":
+        layout[k] = len(v, "vertical");
+        break;
+      case "margin":
+      case "padding": {
+        const parts = splitTopLevel(v);
+        const axis = parts.map((p, i) => len(p, k === "margin" && i === 1 ? "horizontal" : "horizontal"));
+        void axis;
+        const resolved = parts.map((p) => resolveLength(p, { axis: "horizontal" })).filter((x) => !!x);
+        if (resolved.length === parts.length) layout[k] = expandEdges(resolved);
+        break;
+      }
+      case "marginTop":
+      case "marginRight":
+      case "marginBottom":
+      case "marginLeft":
+      case "paddingTop":
+      case "paddingRight":
+      case "paddingBottom":
+      case "paddingLeft": {
+        const side = k.replace(/^(margin|padding)([A-Z].*)$/, "$2");
+        const short = k.startsWith("margin") ? "margin" : "padding";
+        const l = resolveLength(v, { axis: "horizontal" });
+        if (l) {
+          layout[short] = layout[short] ?? {};
+          layout[short][side.toLowerCase()] = l;
+        }
+        break;
+      }
+      case "position":
+        if (v === "static" || v === "relative" || v === "absolute") layout.position = v;
+        else if (v === "fixed" || v === "sticky") {
+          needsCompositing = true;
+          push("warn", "css.l3-opt-in", `position:${v} \u5C5E L3\uFF08\u72EC\u7ACB\u5408\u6210\u5C42\uFF0C\u5404\u5360\u4E00\u5757 backing store\uFF09\u2014\u2014\u9700\u5728 config \u6216\u7EC4\u4EF6\u7EA7 opt-in`);
+        } else push("warn", "css.invalid-value", `position:${v} \u672A\u652F\u6301`);
+        break;
+      case "top":
+        layout.top = len(v, "vertical");
+        break;
+      case "bottom":
+        layout.bottom = len(v, "vertical");
+        break;
+      case "left":
+        layout.left = len(v, "horizontal");
+        break;
+      case "right":
+        layout.right = len(v, "horizontal");
+        break;
+      case "overflow":
+      case "overflowX":
+      case "overflowY": {
+        const val = v === "visible" || v === "hidden" || v === "scroll" || v === "auto" ? v : void 0;
+        if (val) {
+          if (k === "overflow") layout.overflow = val;
+          else layout.overflow = val;
+        }
+        break;
+      }
+      /* ── 绘制（L1 + L3） ── */
+      case "backgroundColor":
+        paint.backgroundColor = v;
+        break;
+      case "background": {
+        if (/gradient\(/.test(v)) paint.backgroundImage = v;
+        else if (/url\(/.test(v)) push("warn", "css.unsupported-image", "background \u7684\u56FE\u7247\u5F62\u6001\u9700\u6539\u7528 image \u7EC4\u4EF6\uFF08CSS Profile \u4E0D\u542B\u80CC\u666F\u56FE\uFF09");
+        else {
+          const first = splitTopLevel(v)[0] ?? "";
+          const isPlainColor = !/\b(no-repeat|repeat|cover|contain|center|left|right|top|bottom)\b/.test(v);
+          if (isPlainColor && first) paint.backgroundColor = first;
+          else push("warn", "css.background-compound", `background \u590D\u5408\u503C\u300C${v}\u300D\u65E0\u6CD5\u6298\u53E0\u4E3A\u5355\u4E00\u989C\u8272\u2014\u2014\u8BF7\u6539\u7528 background-color`);
+        }
+        break;
+      }
+      case "backgroundImage":
+        if (v.includes("gradient(")) paint.backgroundImage = v;
+        else push("warn", "css.unsupported-image", "background-image \u4EC5\u652F\u6301 gradient\uFF08\u5176\u4F59\u9700\u8D70 image \u7EC4\u4EF6\uFF09");
+        break;
+      case "borderRadius": {
+        const parts = splitTopLevel(v).map((p) => resolveLength(p, { axis: "horizontal" }));
+        if (parts.every((x) => !!x)) paint.borderRadius = expandEdges(parts);
+        break;
+      }
+      case "borderTopLeftRadius":
+      case "borderTopRightRadius":
+      case "borderBottomLeftRadius":
+      case "borderBottomRightRadius": {
+        const side = k.replace(/^border([A-Z].*)Radius$/, "$1");
+        const l = resolveLength(v, { axis: "horizontal" });
+        if (l) {
+          paint.borderRadius = paint.borderRadius ?? {};
+          paint.borderRadius[side.charAt(0).toLowerCase() + side.slice(1)] = l;
+        }
+        break;
+      }
+      case "border": {
+        const parts = splitTopLevel(v);
+        const w = parts.find((p) => /^-?\d*\.?\d+\s*(px|rpx|pt)?$/.test(p));
+        const style = parts.find((p) => ["solid", "dashed", "dotted", "none"].includes(p));
+        const color = parts.find((p) => !p.includes("px") && p !== style && p !== w);
+        if (w) {
+          const l = resolveLength(w, { axis: "horizontal" });
+          if (l) paint.borderWidth = { top: l, right: l, bottom: l, left: l };
+        }
+        if (style) paint.borderStyle = style;
+        if (color) paint.borderColor = color;
+        break;
+      }
+      case "borderWidth": {
+        const parts = splitTopLevel(v).map((p) => resolveLength(p, { axis: "horizontal" }));
+        if (parts.every((x) => !!x)) paint.borderWidth = expandEdges(parts);
+        break;
+      }
+      case "borderColor":
+        paint.borderColor = v;
+        break;
+      case "opacity": {
+        const n = Number(v);
+        if (Number.isFinite(n)) paint.opacity = n;
+        break;
+      }
+      case "transform": {
+        const { t, threeD } = parseTransform(v);
+        hasTransform = true;
+        if (threeD) {
+          needsCompositing = true;
+          push("warn", "css.l3-opt-in", `3D \u53D8\u6362\u5C5E L3\uFF08\u5408\u6210\u5C42 + \u5149\u6805\u5316\uFF09\u2014\u2014\u9700 opt-in\uFF1B\u503C\u300C${v}\u300D\u4EC5\u4F9B\u8BCA\u65AD`);
+        }
+        if (Object.keys(t).length) paint.transform = t;
+        break;
+      }
+      /* ── L3：标记合成层 + 需 opt-in（不静默丢弃——诊断保留原值） ── */
+      case "zIndex":
+      case "boxShadow":
+      case "filter":
+      case "backdropFilter":
+      case "willChange": {
+        needsCompositing = true;
+        void L3_PROPS;
+        push("warn", "css.l3-opt-in", `${kRaw} \u5C5E L3\uFF08\u5408\u6210\u5C42/\u79BB\u5C4F\u6E32\u67D3\u2014\u2014\u5404\u5360\u4E00\u5757 backing store\uFF09\u2014\u2014\u9700\u663E\u5F0F opt-in`);
+        break;
+      }
+      /* ── 文本 ── */
+      case "fontSize":
+        text.fontSize = len(v, "horizontal");
+        break;
+      case "fontWeight":
+        text.fontWeight = v === "normal" || v === "bold" ? v : Number(v);
+        break;
+      case "lineHeight": {
+        const n = Number(v);
+        if (Number.isFinite(n) && !/[a-z%]/.test(v)) text.lineHeight = n;
+        else text.lineHeight = resolveLength(v, { axis: "vertical" });
+        break;
+      }
+      case "letterSpacing":
+        text.letterSpacing = len(v, "horizontal");
+        break;
+      case "color":
+        text.color = v;
+        break;
+      case "textAlign":
+        if (v === "left" || v === "center" || v === "right" || v === "justify") text.textAlign = v;
+        break;
+      case "webkitLineClamp": {
+        const n = Number(v);
+        if (Number.isFinite(n)) text.maxLines = n;
+        break;
+      }
+      case "textOverflow":
+        if (v === "clip" || v === "ellipsis") text.textOverflow = v;
+        break;
+      case "whiteSpace":
+        if (v === "normal" || v === "nowrap" || v === "pre-wrap") text.whiteSpace = v;
+        break;
+      default:
+        push("error", "css.out-of-profile", `\u5C5E\u6027 ${kRaw} \u4E0D\u5728 CSS Profile \u5185`);
+        break;
+    }
+  }
+  const hasText = Object.keys(text).length > 0;
+  const paintHint = {
+    // 单色文本 → 紧凑 backing store 格式（实测 −39% 内存）
+    isMonochrome: !!(hasText && text.color && !paint.backgroundImage && !needsCompositing),
+    // 纯色背景 → 走 backgroundColor 通道、**不分配 backing store**（实测：仅色块 4.9MB vs 带文本 186.7MB）
+    isPureBackground: !!paint.backgroundColor && !paint.backgroundImage && !paint.borderWidth && !paint.borderRadius && !needsCompositing && !hasTransform && (paint.opacity === void 0 || paint.opacity === 1),
+    // 由树级分析填充（本函数只管单节点）
+    staticSubtree: false,
+    needsCompositingLayer: needsCompositing
+  };
+  return {
+    props: {
+      layout,
+      paint,
+      ...hasText ? { text } : {},
+      paintHint
+    },
+    diagnostics
+  };
+}
+function normalizeStyleString(style, opts = {}) {
+  return normalizeStyleDecls(parseStyleString(style), opts);
+}
+
+// src/pnode-analyze.ts
+var FLATTENABLE_KINDS = /* @__PURE__ */ new Set(["view", "text", "image"]);
+function analyzePTree(tree, opts = {}) {
+  const diagnostics = [];
+  const decisions = [];
+  const facts = opts.facts ?? /* @__PURE__ */ new Map();
+  const boundary = opts.boundaryIds ?? /* @__PURE__ */ new Set();
+  const boundProps = /* @__PURE__ */ new Map();
+  for (const b of tree.bindings) {
+    const list = boundProps.get(b.nodeId) ?? [];
+    list.push(b.propKey);
+    boundProps.set(b.nodeId, list);
+  }
+  let nodeCount = 0;
+  let flattenableCount = 0;
+  let compositingCount = 0;
+  const walk = (node) => {
+    nodeCount++;
+    const f = facts.get(node.id);
+    const ownDynamic = (boundProps.get(node.id)?.length ?? 0) > 0 || (f?.dynamicProps?.length ?? 0) > 0;
+    const hasEvent = f?.hasEvent === true || node.flags.hasEvent === true;
+    let childrenStatic = true;
+    for (const child of node.children) {
+      if (!walk(child)) childrenStatic = false;
+    }
+    const isStatic = !ownDynamic && !hasEvent && childrenStatic;
+    node.flags.isStatic = isStatic;
+    node.flags.hasEvent = hasEvent;
+    node.flags.isNativeHost = node.kind === "native-host";
+    node.props.paintHint.staticSubtree = isStatic;
+    if (node.props.paintHint.needsCompositingLayer) compositingCount++;
+    const reasons = [];
+    if (!FLATTENABLE_KINDS.has(node.kind)) reasons.push(`kind=${node.kind} \u975E\u7ED8\u5236\u578B`);
+    if (!isStatic) reasons.push("\u5B50\u6811\u542B\u52A8\u6001\u7ED1\u5B9A");
+    if (hasEvent) reasons.push("\u7ED1\u5B9A\u4E8B\u4EF6\uFF08\u62CD\u5E73\u540E\u4E0D\u518D\u6709\u72EC\u7ACB\u7ED8\u5236\u5BF9\u8C61\uFF0C\u4E8B\u4EF6\u4E0D\u53EF\u8FBE\uFF09");
+    if (f?.isAnimationTarget) reasons.push("\u52A8\u753B/\u8F6C\u573A\u76EE\u6807");
+    if (f?.isComponentRoot) reasons.push("\u81EA\u5B9A\u4E49\u7EC4\u4EF6\u6839\uFF08\u7EC4\u4EF6\u8FB9\u754C\uFF09");
+    if (node.props.paintHint.needsCompositingLayer) reasons.push("\u9700\u5408\u6210\u5C42\uFF08L3 \u7279\u6027\uFF09");
+    if (node.props.paint.transform) reasons.push("\u542B transform");
+    if (boundary.has(node.id)) reasons.push("\u7ED3\u6784\u8FB9\u754C\uFF08\u5BB9\u5668/\u5BBF\u4E3B\uFF09");
+    const flattenEligible = reasons.length === 0;
+    node.flags.flattenEligible = flattenEligible;
+    if (flattenEligible) flattenableCount++;
+    if (f?.requestFlatten && !flattenEligible) {
+      diagnostics.push({
+        severity: "error",
+        code: "css.flatten-violation",
+        message: `\u663E\u5F0F\u8BF7\u6C42\u62CD\u5E73\uFF0C\u4F46\u4E0D\u6EE1\u8DB3\u6761\u4EF6\uFF1A${reasons.join(" / ")}`,
+        nodeId: node.id,
+        source: node.source
+      });
+    }
+    decisions.push({
+      nodeId: node.id,
+      kind: node.kind,
+      semantic: node.semantic,
+      isStatic,
+      flattenEligible,
+      reasons
+    });
+    return isStatic;
+  };
+  for (const root of tree.roots) walk(root);
+  const stats = { nodeCount, flattenableCount, compositingCount };
+  tree.stats = stats;
+  tree.diagnostics.push(...diagnostics);
+  return { diagnostics, stats, decisions };
+}
+function flattenRate(stats) {
+  return stats.nodeCount > 0 ? stats.flattenableCount / stats.nodeCount : 0;
+}
+function groupBindingsByNode(bindings) {
+  const out = /* @__PURE__ */ new Map();
+  for (const b of bindings) {
+    const list = out.get(b.nodeId) ?? [];
+    list.push(b);
+    out.set(b.nodeId, list);
+  }
+  return out;
+}
+
+// src/pnode-build.ts
+function kindFromSemantic(semantic, tag) {
+  const s = semantic ?? "";
+  if (!s) {
+    if (tag === "text" || tag === "p-text") return "text";
+    if (tag === "image" || tag === "img") return "image";
+    return "view";
+  }
+  if (s.startsWith("layout.virtual-list") || s.startsWith("layout.masonry")) return "list";
+  if (s.startsWith("layout.")) return "view";
+  if (s === "ui.text" || s === "ui.heading" || s === "ui.label") return "text";
+  if (s === "ui.rich-text") return "rich-text";
+  if (s.startsWith("ui.image") || s === "ui.icon" || s === "ui.avatar" || s === "ui.media" || s === "ui.svg" || s === "ui.canvas") return "image";
+  if (s === "shell.webview" || s === "ui.map" || s === "ui.camera" || s === "shell.ad" || s === "ui.ad") return "native-host";
+  return "view";
+}
+function normalizePropsOf(raw, kind, st, ctx) {
+  const source = { tag: ctx.tag, line: void 0 };
+  const res = typeof raw.style === "string" ? normalizeStyleString(raw.style, { kind, nodeId: ctx.id, source }) : normalizeStyleDecls(raw.style ?? {}, { kind, nodeId: ctx.id, source });
+  st.diagnostics.push(...res.diagnostics);
+  return res.props;
+}
+function buildNode(raw, st) {
+  const id = st.nextId++;
+  const tag = raw.tag ?? raw.kind ?? "view";
+  const kind = raw.kind ?? kindFromSemantic(raw.semantic, tag);
+  const props = normalizePropsOf(raw, kind, st, { id, tag });
+  for (const b of raw.bindings ?? []) {
+    const updateKind = b.updateKind ?? inferUpdateKind(b.propKey);
+    st.bindings.push({
+      slotId: st.slot++,
+      nodeId: id,
+      propKey: b.propKey,
+      exprId: b.exprId,
+      updateKind,
+      // ★Vapor IR 扩展（方案 §3.2）：opCode 编译期确定 ⇒ 运行时无类型判断
+      opCode: b.opCode ?? inferOpCode(updateKind),
+      // ★缺省 L0：保守优先（误判 L1 = 静默不更新；方案 §5.1）
+      tier: b.tier ?? "L0",
+      deps: b.deps ?? []
+    });
+  }
+  const facts = {
+    hasEvent: raw.facts?.hasEvent,
+    isAnimationTarget: raw.facts?.isAnimationTarget,
+    isComponentRoot: raw.facts?.isComponentRoot,
+    requestFlatten: raw.facts?.requestFlatten,
+    dynamicProps: (raw.bindings ?? []).map((b) => b.propKey)
+  };
+  st.facts.set(id, facts);
+  const node = {
+    id,
+    kind,
+    semantic: raw.semantic,
+    props,
+    children: [],
+    flags: { isStatic: true, flattenEligible: false, isLayoutBoundary: false, hasEvent: false, isNativeHost: kind === "native-host" },
+    source: { tag }
+  };
+  if (raw.text !== void 0) node.text = raw.text;
+  node.children = (raw.children ?? []).map((c) => buildNode(c, st));
+  return node;
+}
+function inferUpdateKind(propKey) {
+  if (propKey.startsWith("text.")) return propKey === "text.color" || propKey === "text.fontSize" ? "style" : "text-content";
+  if (propKey.startsWith("layout.")) return "style";
+  if (propKey.startsWith("paint.")) return "style";
+  if (propKey === "visible" || propKey === "display") return "visibility";
+  if (propKey.startsWith("list.")) return "list-data";
+  return "attr";
+}
+function inferOpCode(updateKind) {
+  switch (updateKind) {
+    case "attr":
+      return 1 /* SET_PROP */;
+    case "style":
+      return 2 /* SET_STYLE */;
+    case "text-content":
+      return 3 /* SET_TEXT */;
+    case "visibility":
+      return 5 /* TOGGLE_VIS */;
+    case "list-data":
+      return 32 /* LIST_SET */;
+    default: {
+      const never = updateKind;
+      throw new Error(`\u672A\u77E5\u66F4\u65B0\u79CD\u7C7B\uFF1A${String(never)}`);
+    }
+  }
+}
+function buildPTree(raws, opts = {}) {
+  const st = {
+    nextId: opts.startId ?? 1,
+    bindings: [],
+    diagnostics: [],
+    facts: /* @__PURE__ */ new Map(),
+    slot: 0
+  };
+  const roots = raws.map((r) => buildNode(r, st));
+  const tree = {
+    roots,
+    bindings: st.bindings,
+    diagnostics: st.diagnostics,
+    stats: { nodeCount: 0, flattenableCount: 0, compositingCount: 0 }
+  };
+  analyzePTree(tree, { facts: st.facts, boundaryIds: opts.analyze?.boundaryIds });
+  return tree;
+}
+function styleOf(ir) {
+  const s = ir.props.style;
+  if (typeof s === "string") return s;
+  if (s && typeof s === "object") return s;
+  return void 0;
+}
+function rawFromComponentIR(ir) {
+  const children = (ir.children ?? []).map(rawFromComponentIR);
+  const raw = {
+    semantic: ir.semantic,
+    tag: ir.tag,
+    children
+  };
+  const st = styleOf(ir);
+  if (st) raw.style = st;
+  return raw;
+}
+function buildPTreeFromComponentIR(roots, opts = {}) {
+  return buildPTree(roots.map(rawFromComponentIR), opts);
+}
+
+// src/pnode-trace.ts
+function formatPNodeLine(decision) {
+  const bits = [
+    `#${decision.nodeId}`,
+    decision.kind,
+    decision.semantic ? `(${decision.semantic})` : "",
+    decision.isStatic ? "\u9759\u6001" : "\u52A8\u6001",
+    decision.flattenEligible ? "\u2705\u53EF\u62CD\u5E73" : `\u26D4\u53D7\u963B\uFF1A${decision.reasons.join(" / ")}`
+  ];
+  return bits.filter(Boolean).join(" ");
+}
+function formatPTrace(tree, analysis, opts = {}) {
+  const max = opts.maxNodes ?? 200;
+  const lines = [];
+  const rate = (flattenRate(tree.stats) * 100).toFixed(1);
+  lines.push("### \u6E32\u67D3 IR\uFF08\u6E32\u67D3\u5C42\u51B3\u7B56\uFF09");
+  lines.push(`  \u8282\u70B9 ${tree.stats.nodeCount} \xB7 \u53EF\u62CD\u5E73 ${tree.stats.flattenableCount}\uFF08\u62CD\u5E73\u7387 ${rate}%\uFF09\xB7 \u9700\u5408\u6210\u5C42 ${tree.stats.compositingCount}`);
+  lines.push(`  \u52A8\u6001\u7ED1\u5B9A ${tree.bindings.length} \u4E2A\u69FD\u4F4D`);
+  lines.push("  \uFF08\u53C2\u7167\uFF1A\u771F\u673A\u5B9E\u6D4B 4050 \u5143\u7D20\u62CD\u5E73\u7387 98.8% \u2192 \u5185\u5B58 186.7\u219217.7MB \xB7 \u8017\u65F6 190.5\u2192129.9ms\uFF09");
+  const ordered = [...analysis.decisions].sort((a, b) => a.nodeId - b.nodeId);
+  const shown = ordered.filter((d) => !opts.onlyBlocked || !d.flattenEligible).slice(0, max);
+  lines.push("");
+  lines.push(`  \u9010\u8282\u70B9\u51B3\u7B56${opts.onlyBlocked ? "\uFF08\u4EC5\u53D7\u963B\u9879\uFF09" : ""}\uFF1A`);
+  for (const d of shown) lines.push(`    ${formatPNodeLine(d)}`);
+  const hidden = ordered.filter((d) => !opts.onlyBlocked || !d.flattenEligible).length - shown.length;
+  if (hidden > 0) lines.push(`    \u2026 \u7701\u7565 ${hidden} \u4E2A\u8282\u70B9\uFF08--max-nodes \u8C03\u6574\uFF09`);
+  if (opts.includeDiagnostics !== false && tree.diagnostics.length) {
+    const errs = tree.diagnostics.filter((d) => d.severity === "error");
+    const warns = tree.diagnostics.filter((d) => d.severity === "warn");
+    lines.push("");
+    lines.push(`  \u8BCA\u65AD\uFF1Aerror ${errs.length} \xB7 warn ${warns.length}`);
+    for (const d of errs) lines.push(`    \u2717 [${d.code}] ${d.message}${d.source ? `\uFF08${d.source.tag}\uFF09` : ""}`);
+    for (const d of warns.slice(0, 20)) lines.push(`    \u26A0 [${d.code}] ${d.message}`);
+    if (warns.length > 20) lines.push(`    \u2026 \u53E6\u6709 ${warns.length - 20} \u6761 warn`);
+  }
+  return lines.join("\n");
+}
+function decisionOf(analysis, nodeId) {
+  return analysis.decisions.find((d) => d.nodeId === nodeId);
+}
+function walkPTree(roots, visit) {
+  const walk = (nodes, depth) => {
+    for (const n of nodes) {
+      visit(n, depth);
+      walk(n.children, depth + 1);
+    }
+  };
+  walk(roots, 0);
+}
 export {
   COMPONENT_IR_SCHEMA,
   DEFAULT_DESIGN_WIDTH,
@@ -2339,12 +3037,16 @@ export {
   SPEC_RATCHET,
   TAG_SEMANTIC_ALIASES,
   TAG_SEMANTIC_MAP,
+  analyzePTree,
   auditCatalogConsistency,
   auditDegradation,
   auditMatrixReferences,
   auditMiniprogramCoverage,
   auditSpecCoverage,
   auditSpecOverrideRefs,
+  buildPTree,
+  buildPTreeFromComponentIR,
+  camel,
   checkComponentSnapshot,
   checkPrimitiveCatalog,
   checkPropDegradation,
@@ -2353,19 +3055,36 @@ export {
   classifySpecComponent,
   collectPropDiagnostics,
   componentPrimitives,
+  decisionOf,
   degradationOf,
   degradeProp,
+  expandEdges,
   extractSemanticTree,
+  flattenRate,
   formatCoverageReport,
   formatDegradationReport,
+  formatPNodeLine,
+  formatPTrace,
+  groupBindingsByNode,
   implementedPrimitives,
+  inferOpCode,
+  inferUpdateKind,
+  kindFromSemantic,
   mapSemanticToBackend,
+  normalizeStyleDecls,
+  normalizeStyleString,
+  parseStyleString,
+  parseTransform,
   primitiveById,
   primitiveBySemantic,
   primitiveByTag,
+  rawFromComponentIR,
+  resolveLength,
+  splitTopLevel,
   toComponentIR,
   toComponentTree,
   validateComponentIR,
   validateComponentTree,
-  validateGridConstraints
+  validateGridConstraints,
+  walkPTree
 };

package/dist/pnode-analyze.d.ts

@@ -0,0 +1,42 @@
+import type { DynamicBinding, PDiagnostic, PTree } from './pnode';
+/** 分析输入：节点的「非样式」事实（由上游从模板/脚本提取） */
+export interface NodeFacts {
+    /** 该节点自身绑定的动态属性键（如 `text.color` / `layout.width`） */
+    dynamicProps?: string[];
+    /** 该节点是否绑定事件（click/touch/…） */
+    hasEvent?: boolean;
+    /** 是否为动画/转场目标（Transition · animate · worklet） */
+    isAnimationTarget?: boolean;
+    /** 是否为自定义组件根（组件边界不可拍平——否则跨组件通信失效） */
+    isComponentRoot?: boolean;
+    /** 显式请求拍平（声明式 directive / config）——不合资格时**报错** */
+    requestFlatten?: boolean;
+}
+export interface AnalyzeOptions {
+    /** 节点事实表（nodeId → facts）；缺省视为「无动态、无事件」 */
+    facts?: Map<number, NodeFacts>;
+    /** 结构边界：不可拍平的节点 id（如滚动容器 / 原生宿主 / 列表项模板根） */
+    boundaryIds?: Set<number>;
+}
+export interface AnalyzeResult {
+    diagnostics: PDiagnostic[];
+    stats: PTree['stats'];
+    /** 逐节点判定记录（trace / `proteus explain` 消费） */
+    decisions: Array<{
+        nodeId: number;
+        kind: string;
+        semantic?: string;
+        isStatic: boolean;
+        flattenEligible: boolean;
+        reasons: string[];
+    }>;
+}
+/**
+ * 树级分析（后序遍历）——填充 `flags` / `paintHint.staticSubtree` 并产出决策记录与诊断。
+ * **原地更新** tree（便于 compiler 直接在构建流程里调用），同时返回分析结果。
+ */
+export declare function analyzePTree(tree: PTree, opts?: AnalyzeOptions): AnalyzeResult;
+/** 拍平率（实测关心指标：拍平率越高，绘制对象越少 → 内存与 commit 成本越低） */
+export declare function flattenRate(stats: PTree['stats']): number;
+/** 把动态绑定按 nodeId 分组（M2 的 PatchTable 生成与运行时槽位索引会用到） */
+export declare function groupBindingsByNode(bindings: DynamicBinding[]): Map<number, DynamicBinding[]>;

package/dist/pnode-build.d.ts

@@ -0,0 +1,59 @@
+import type { ComponentIR } from './schema';
+import { OpCode } from '@proteus-vue/slot-runtime';
+import type { UpdateTier } from '@proteus-vue/slot-runtime';
+import type { PKind, PTree, UpdateKind } from './pnode';
+import type { NodeFacts, AnalyzeOptions } from './pnode-analyze';
+/**
+ * 语义 → 绘制类型（**框架层收敛点**：semantic 是后端映射依据，kind 是绘制层分工）。
+ * 映射表对齐 `render-backend/spi.ts` 的 `IRNode.semantic` 域前缀。
+ */
+export declare function kindFromSemantic(semantic: string | undefined, tag: string): PKind;
+/** 轻量声明节点（供测试与编译器直调——刻意不要求完整 ComponentIR） */
+export interface PRawNode {
+    kind?: PKind;
+    semantic?: string;
+    tag?: string;
+    /** 内联样式：字符串或声明表 */
+    style?: string | Record<string, string>;
+    /** 文本字面量（静态文本） */
+    text?: string;
+    /** 事实（事件/动画/组件根/显式拍平请求——传给分析器） */
+    facts?: Omit<NodeFacts, 'dynamicProps'>;
+    /** 动态绑定声明（编译器从模板分析得出） */
+    bindings?: Array<{
+        propKey: string;
+        exprId: string;
+        updateKind?: UpdateKind;
+        /** ★显式指定操作码（如 item 级 `LIST_UPDATE`；缺省由 updateKind 推导） */
+        opCode?: OpCode;
+        /** ★分层（缺省 L0——保守：没证明安全就不许假设安全） */
+        tier?: UpdateTier;
+        /** ★编译期识别的响应式依赖（V2 填充；缺省空数组） */
+        deps?: string[];
+    }>;
+    children?: PRawNode[];
+}
+export interface BuildOptions {
+    /** 起始 id（多次构建可错开——同输入同输出） */
+    startId?: number;
+    /** 自定义分析选项透传（boundaryIds 等） */
+    analyze?: AnalyzeOptions;
+}
+/** 绑定属性键 → 更新种类（运行时按种类走特化写值——D1「按槽位写值」） */
+export declare function inferUpdateKind(propKey: string): UpdateKind;
+/**
+ * 更新种类 → 指令操作码（**编译期确定，运行时无分支**——方案 §2.1）
+ *
+ * ★为什么 `list-data` 默认映射到 `LIST_SET` 而不是 `LIST_UPDATE`：
+ *   同一个 `updateKind` 有两种列表语义——「整体换数据源」（LIST_SET）与
+ *   「单项内一个槽位变化」（LIST_UPDATE，方案 §2.3 的核心收益）。
+ *   后者**必须由编译器显式指定**（它要知道 listId / itemKey / 项内槽位），
+ *   不能在推进时猜——猜错会把「改一项」误当成「换整表」，是静默的性能回退。
+ */
+export declare function inferOpCode(updateKind: UpdateKind): OpCode;
+/** 从轻量声明构建渲染 IR（含分析） */
+export declare function buildPTree(raws: PRawNode[], opts?: BuildOptions): PTree;
+/** 从 ComponentIR 转 PRawNode（保留语义、样式、文本） */
+export declare function rawFromComponentIR(ir: ComponentIR): PRawNode;
+/** 从语义 IR 构建渲染 IR（编译器集成入口） */
+export declare function buildPTreeFromComponentIR(roots: ComponentIR[], opts?: BuildOptions): PTree;

package/dist/pnode-style.d.ts

@@ -0,0 +1,50 @@
+import type { Edges, PDiagnostic, PKind, PProps, ResolvedLength, Transform2D } from './pnode';
+/** 长度解析上下文（基准语义） */
+export interface LengthContext {
+    /** 属性归属轴——决定 `%` 的基准（width/margin/padding → parentWidth；height → parentHeight） */
+    axis: 'horizontal' | 'vertical';
+}
+/**
+ * 单位折叠（Profile §3.2：编译期折叠为逻辑像素或比例系数）。
+ * · `px` / 无单位 0 → 绝对 dp
+ * · `%` → ratio（基准按轴）
+ * · `vw` / `vh` → ratio（视口基准）
+ * · `rpx` → ratio = v/750（小程序 750 设计宽语义；App 端同样按视口宽比例求值）
+ * · `em` → ratio（父字号基准）· `rem` → ratio（根字号基准）
+ * 非法值 → undefined（由调用方出诊断）
+ */
+export declare function resolveLength(raw: string, ctx?: LengthContext): ResolvedLength | undefined;
+/** 声明列表解析（`color: red; font-size: 14px` → 键值对；键统一 camelCase） */
+export declare function parseStyleString(style: string): Record<string, string>;
+/** kebab-case → camelCase（CSS 与 Vue style 对象两种写法都吃） */
+export declare function camel(k: string): string;
+/** 空格分隔值拆分（跳过函数括号内的空格：`1px solid rgb(0, 0, 0)`） */
+export declare function splitTopLevel(value: string): string[];
+/** 四边简写展开（1/2/3/4 值语义，对齐 CSS） */
+export declare function expandEdges<T>(parts: T[]): Partial<Edges<T>>;
+/** 2D 变换解析；含 3D 分量 → 返回 `threeD: true`（由调用方标记 L3） */
+export declare function parseTransform(raw: string): {
+    t: Transform2D;
+    threeD: boolean;
+};
+export interface NormalizeResult {
+    props: PProps;
+    diagnostics: PDiagnostic[];
+}
+export interface NormalizeOptions {
+    /** 节点类型（影响 PaintHint 推导——文本单色 / 纯背景） */
+    kind?: PKind;
+    /** 源码定位（诊断用） */
+    source?: {
+        tag: string;
+        line?: number;
+    };
+    nodeId?: number;
+}
+/**
+ * 归一化：声明表 → `PProps`（**编译期完成，运行时零解析**）。
+ * 诊断按 Profile 分级：L3 → warn（需 opt-in）；Profile 外 → error；非法单位 → warn。
+ */
+export declare function normalizeStyleDecls(decls: Record<string, string>, opts?: NormalizeOptions): NormalizeResult;
+/** 便捷：样式字符串 → PProps（内部先拆声明列表） */
+export declare function normalizeStyleString(style: string, opts?: NormalizeOptions): NormalizeResult;

package/dist/pnode-trace.d.ts

@@ -0,0 +1,21 @@
+import type { PNode, PTree } from './pnode';
+import type { AnalyzeResult } from './pnode-analyze';
+export interface PTraceOptions {
+    /** 只显示不能拍平的节点（排查用——默认全显示） */
+    onlyBlocked?: boolean;
+    /** 最多显示多少个节点（防输出爆炸——本仓效率规范明令「输出控制」） */
+    maxNodes?: number;
+    /** 是否包含诊断明细 */
+    includeDiagnostics?: boolean;
+}
+/** 单节点一行摘要：`#id kind semantic  [静态|动态] [可拍平|受阻:理由]` */
+export declare function formatPNodeLine(decision: AnalyzeResult['decisions'][number]): string;
+/**
+ * 渲染 IR 决策 trace（供 `proteus explain` 输出）。
+ * 输出结构：统计摘要 → 逐节点决策（按树序）→ 诊断（error 优先）。
+ */
+export declare function formatPTrace(tree: PTree, analysis: AnalyzeResult, opts?: PTraceOptions): string;
+/** 从 PTree 反查某节点的决策（explain 定位用） */
+export declare function decisionOf(analysis: AnalyzeResult, nodeId: number): AnalyzeResult['decisions'][number] | undefined;
+/** 树序遍历（trace 输出与调试用） */
+export declare function walkPTree(roots: PNode[], visit: (node: PNode, depth: number) => void): void;

package/dist/pnode.d.ts

@@ -0,0 +1,216 @@
+/** 渲染节点类型（比语义层粗——绘制层只区分「怎么画」） */
+export type PKind = 
+/** 盒子（背景/边框/圆角——可含子节点） */
+'view'
+/** 文本（单个文本节点，内容来自 text-content 槽或静态字面量） */
+ | 'text'
+/** 图像 */
+ | 'image'
+/** 列表（复用池管理，M3） */
+ | 'list'
+/** 富文本（平台文本引擎，L4） */
+ | 'rich-text'
+/** 原生组件宿主（map/webview/广告——必须原生嵌入，CSS Profile §0.2 非目标） */
+ | 'native-host';
+/**
+ * 归一化长度（**单位已在编译期折叠**——运行时不做单位换算，Profile §3.2）。
+ * · `absolute`：px → dp（App 端 1px = 1dp；密度缩放由平台层处理）
+ * · `ratio`：`%` / `vw` / `vh` / `rpx` / `em` / `rem` → 保留比例系数 + 基准，运行时按基准求值
+ */
+export type ResolvedLength = {
+    kind: 'absolute';
+    dp: number;
+} | {
+    kind: 'ratio';
+    ratio: number;
+    base: 'parentWidth' | 'parentHeight' | 'viewportWidth' | 'viewportHeight' | 'fontSize' | 'rootFontSize';
+};
+/** 四边值（margin / padding / border-radius 等） */
+export interface Edges<T> {
+    top: T;
+    right: T;
+    bottom: T;
+    left: T;
+}
+/** 布局属性（flex 为主——Profile L2；grid 待定，不在此层） */
+export interface LayoutProps {
+    display?: 'flex' | 'none' | 'block' | 'inline-block';
+    flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+    flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
+    justifyContent?: string;
+    alignItems?: string;
+    alignSelf?: string;
+    alignContent?: string;
+    flexGrow?: number;
+    flexShrink?: number;
+    flexBasis?: ResolvedLength | 'auto';
+    gap?: ResolvedLength;
+    rowGap?: ResolvedLength;
+    columnGap?: ResolvedLength;
+    width?: ResolvedLength;
+    height?: ResolvedLength;
+    minWidth?: ResolvedLength;
+    maxWidth?: ResolvedLength;
+    minHeight?: ResolvedLength;
+    maxHeight?: ResolvedLength;
+    margin?: Partial<Edges<ResolvedLength>>;
+    padding?: Partial<Edges<ResolvedLength>>;
+    /** ★fixed / sticky 属 L3（独立合成层）——此处只接受 static/relative/absolute（Profile L2） */
+    position?: 'static' | 'relative' | 'absolute';
+    top?: ResolvedLength;
+    right?: ResolvedLength;
+    bottom?: ResolvedLength;
+    left?: ResolvedLength;
+    overflow?: 'visible' | 'hidden' | 'scroll' | 'auto';
+}
+/** 2D 变换（L1）。3D 变换属 L3（会创建合成层）——由 diagnostics 拦下 */
+export interface Transform2D {
+    translateX?: number;
+    translateY?: number;
+    scale?: number;
+    rotate?: number;
+}
+/** 绘制属性 */
+export interface PaintProps {
+    backgroundColor?: string;
+    /** 线性渐变（Profile L1；实测 Skyline 亦接受该属性） */
+    backgroundImage?: string;
+    borderRadius?: Partial<Edges<ResolvedLength>>;
+    borderWidth?: Partial<Edges<ResolvedLength>>;
+    borderColor?: string;
+    borderStyle?: 'solid' | 'dashed' | 'dotted' | 'none';
+    opacity?: number;
+    transform?: Transform2D;
+}
+/** 文本属性（**字体族/BiDi/emoji 均不在本层**——L4 复用平台文本栈，Profile §L4） */
+export interface TextProps {
+    fontSize?: ResolvedLength;
+    fontWeight?: number | 'normal' | 'bold';
+    lineHeight?: ResolvedLength | number;
+    letterSpacing?: ResolvedLength;
+    color?: string;
+    textAlign?: 'left' | 'center' | 'right' | 'justify';
+    /** 截断行数（依赖平台文本度量——Profile L2 标 🟡） */
+    maxLines?: number;
+    textOverflow?: 'clip' | 'ellipsis';
+    whiteSpace?: 'normal' | 'nowrap' | 'pre-wrap';
+}
+/**
+ * 绘制提示（编译期推导，**禁止运行时判断**——Profile §12.4）。
+ * 每一条都对应一条已实测的绘制/内存策略：
+ * · `isMonochrome`：单色内容（纯色文本/纯色块）→ 可用紧凑 backing store 格式（**实测 −39%**）
+ * · `isPureBackground`：只有背景色、无其它绘制 → 走 backgroundColor 通道（**不分配 backing store**）
+ * · `staticSubtree`：整棵子树无动态绑定 → 可拍平 / 可光栅化缓存
+ * · `needsCompositingLayer`：L3 特性（z-index / fixed / filter / shadow / 3D）→ 各占一块 backing store
+ * · `shareableContent`：可共享图形的资源标识（同图多层共享内存，M2 消费）
+ */
+export interface PaintHint {
+    isMonochrome: boolean;
+    isPureBackground: boolean;
+    staticSubtree: boolean;
+    needsCompositingLayer: boolean;
+    shareableContent?: string;
+}
+/** 归一化后的属性集（= CSS Profile §4.5 的 ComputedStyle 的渲染子集） */
+export interface PProps {
+    layout: LayoutProps;
+    paint: PaintProps;
+    text?: TextProps;
+    paintHint: PaintHint;
+}
+/** 编译期判定的节点标志（供后端/代码生成直接消费，运行时零判断） */
+export interface PFlags {
+    /** 整棵子树无动态绑定（**含自身与所有后代**） */
+    isStatic: boolean;
+    /**
+     * 可拍平（编译期判定，见 D4 与 §12.3）——
+     * 判定条件：kind ∈ view/text/image ∧ 无事件 ∧ 无 transform ∧ 非动画目标 ∧ 非自定义组件根
+     *          ∧ 静态子树 ∧ 不创建合成层
+     */
+    flattenEligible: boolean;
+    /** 布局边界：自身尺寸变化不影响父级（可跳过向上传播重排） */
+    isLayoutBoundary: boolean;
+    hasEvent: boolean;
+    isNativeHost: boolean;
+}
+/** 渲染节点（稳定整数 id——编译期分配，非字符串，便于二进制序列化） */
+export interface PNode {
+    id: number;
+    kind: PKind;
+    /** 语义标签（诊断用——`layout.box` / `ui.text`；不参与绘制决策） */
+    semantic?: string;
+    props: PProps;
+    children: PNode[];
+    flags: PFlags;
+    /** 文本节点的静态字面量（动态文本走 bindings 的 text-content 槽） */
+    text?: string;
+    /** 源码定位（诊断/trace 用） */
+    source?: {
+        tag: string;
+        line?: number;
+    };
+}
+/** 动态绑定更新种类（运行时按种类走特化写值函数，避免运行时类型判断） */
+export type UpdateKind = 'attr' | 'style' | 'text-content' | 'list-data' | 'visibility';
+/** 动态绑定（编译期分配的槽位——运行时只「按槽位写值」，**不存在 VNode diff**，D1） */
+export interface DynamicBinding {
+    /** 槽位索引（编译期连续分配） */
+    slotId: number;
+    /** 目标节点 id */
+    nodeId: number;
+    /** 目标属性键（归一化名，如 `text.color` / `layout.width`） */
+    propKey: string;
+    /** 更新表达式标识（指向编译期生成的更新表达式） */
+    exprId: string;
+    updateKind: UpdateKind;
+    /**
+     * 更新指令操作码（**编译期确定，运行时无分支**）
+     *
+     * ★号值即线上格式的判别字节，与 `@proteus-vue/slot-runtime` 的 `OpCode` 同源
+     *   （**只允许一处定义**——号值不一致会让 TS 与 Rust 的字节流静默分叉）。
+     *   由 `inferOpCode(updateKind)` 推导，或在 raw 声明里显式给出（如 item 级 `LIST_UPDATE`）。
+     */
+    opCode: OpCode;
+    /**
+     * 更新分层（方案 §5）：`L1` 槽位直写 / `L0` VDOM 兜底
+     *
+     * ★缺省必须是 **L0**（保守）：编译期没证明安全的绑定，不许假设它安全——
+     *   误判为 L1 会导致**静默的 UI 不更新**（比慢 10 倍严重，方案 §12 第 3 条）。
+     */
+    tier: UpdateTier;
+    /**
+     * 编译期识别到的**响应式依赖标识**（L1 槽位订阅用；方案 §4）
+     *
+     * 空数组 = 尚未做依赖分析（V2 的编译期响应式转换会填充）。
+     * ★不接受「运行时才确定」的标识符——那属于准入条件 C2 未通过，应判 L0。
+     */
+    deps: string[];
+}
+/** 编译期诊断（Profile「超出 Profile 即编译期报错，不留到运行时静默降级」） */
+export interface PDiagnostic {
+    severity: 'error' | 'warn';
+    code: string;
+    message: string;
+    /** 源码定位（tag / 行号） */
+    nodeId?: number;
+    source?: {
+        tag: string;
+        line?: number;
+    };
+}
+/** 渲染 IR 树（M0 产物；M1/M2 将其序列化为 LayoutTemplate + PatchTable） */
+export interface PTree {
+    roots: PNode[];
+    bindings: DynamicBinding[];
+    diagnostics: PDiagnostic[];
+    /** 统计（trace / perf-ratchet 消费） */
+    stats: {
+        /** 节点总数 */
+        nodeCount: number;
+        /** 可拍平节点数（拍平率 = flattenable / nodeCount） */
+        flattenableCount: number;
+        /** 需合成层的节点数（预算监控） */
+        compositingCount: number;
+    };
+}
+import type { OpCode, UpdateTier } from '@proteus-vue/slot-runtime';

package/dist/schema.d.ts

@@ -15,7 +15,7 @@ export interface ComponentIR {
     degradation?: Record<string, 'supported' | 'fallback' | 'unsupported'>;
 }
 /** 语义枚举（与 plan component-ir.schema.json 一致）——<domain>.<kind> */
-export declare const SEMANTIC_ENUM: readonly ["layout.box", "layout.inline", "layout.stack", "layout.grid", "layout.fluid", "layout.adaptive", "layout.fit", "layout.spacer", "layout.divider", "layout.scroll", "layout.virtual-list", "layout.masonry", "layout.split", "layout.safe", "layout.sidebar", "layout.aspect", "layout.zone", "ui.text", "ui.heading", "ui.rich-text", "ui.icon", "ui.image", "ui.avatar", "ui.media", "ui.canvas", "ui.svg", "ui.input", "ui.textarea", "ui.select", "ui.checkbox", "ui.radio", "ui.switch", "ui.slider", "ui.picker", "ui.form", "ui.button", "ui.list", "ui.nav", "ui.loading", "ui.scale", "ui.skeleton", "ui.progress", "ui.label", "ui.selection", "ui.camera", "shell.page", "shell.nav", "shell.tabbar", "shell.segment", "shell.drawer", "shell.modal", "shell.popover", "shell.toast", "shell.action-sheet", "shell.mask", "shell.popup", "shell.toolbar", "shell.page-container", "shell.keyboard-accessory", "shell.webview", "shell.ad", "ui.map", "gesture.draggable", "gesture.scrollable", "engineering.router-link", "engineering.transition", "engineering.animate", "engineering.error-boundary", "engineering.share-element", "capability.location", "capability.qr-code", "capability.camera"];
+export declare const SEMANTIC_ENUM: readonly ["layout.box", "layout.inline", "layout.stack", "layout.grid", "layout.fluid", "layout.adaptive", "layout.fit", "layout.spacer", "layout.divider", "layout.scroll", "layout.virtual-list", "layout.masonry", "layout.split", "layout.safe", "layout.sidebar", "layout.aspect", "layout.zone", "layout.formfactor", "ui.text", "ui.heading", "ui.rich-text", "ui.icon", "ui.image", "ui.avatar", "ui.media", "ui.canvas", "ui.svg", "ui.input", "ui.textarea", "ui.select", "ui.checkbox", "ui.radio", "ui.switch", "ui.slider", "ui.picker", "ui.form", "ui.button", "ui.list", "ui.nav", "ui.loading", "ui.scale", "ui.skeleton", "ui.progress", "ui.label", "ui.selection", "ui.camera", "shell.page", "shell.nav", "shell.tabbar", "shell.segment", "shell.drawer", "shell.modal", "shell.popover", "shell.toast", "shell.action-sheet", "shell.mask", "shell.popup", "shell.toolbar", "shell.page-container", "shell.keyboard-accessory", "shell.webview", "shell.ad", "ui.map", "gesture.draggable", "gesture.scrollable", "engineering.router-link", "engineering.transition", "engineering.animate", "engineering.error-boundary", "engineering.share-element", "capability.location", "capability.qr-code", "capability.camera"];
 /** C-IR JSON Schema（等价于 plan component-ir.schema.json——TS 内嵌供校验/工具消费） */
 export declare const COMPONENT_IR_SCHEMA: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
@@ -30,7 +30,7 @@ export declare const COMPONENT_IR_SCHEMA: {
         };
         readonly semantic: {
             readonly type: "string";
-            readonly enum: readonly ["layout.box", "layout.inline", "layout.stack", "layout.grid", "layout.fluid", "layout.adaptive", "layout.fit", "layout.spacer", "layout.divider", "layout.scroll", "layout.virtual-list", "layout.masonry", "layout.split", "layout.safe", "layout.sidebar", "layout.aspect", "layout.zone", "ui.text", "ui.heading", "ui.rich-text", "ui.icon", "ui.image", "ui.avatar", "ui.media", "ui.canvas", "ui.svg", "ui.input", "ui.textarea", "ui.select", "ui.checkbox", "ui.radio", "ui.switch", "ui.slider", "ui.picker", "ui.form", "ui.button", "ui.list", "ui.nav", "ui.loading", "ui.scale", "ui.skeleton", "ui.progress", "ui.label", "ui.selection", "ui.camera", "shell.page", "shell.nav", "shell.tabbar", "shell.segment", "shell.drawer", "shell.modal", "shell.popover", "shell.toast", "shell.action-sheet", "shell.mask", "shell.popup", "shell.toolbar", "shell.page-container", "shell.keyboard-accessory", "shell.webview", "shell.ad", "ui.map", "gesture.draggable", "gesture.scrollable", "engineering.router-link", "engineering.transition", "engineering.animate", "engineering.error-boundary", "engineering.share-element", "capability.location", "capability.qr-code", "capability.camera"];
+            readonly enum: readonly ["layout.box", "layout.inline", "layout.stack", "layout.grid", "layout.fluid", "layout.adaptive", "layout.fit", "layout.spacer", "layout.divider", "layout.scroll", "layout.virtual-list", "layout.masonry", "layout.split", "layout.safe", "layout.sidebar", "layout.aspect", "layout.zone", "layout.formfactor", "ui.text", "ui.heading", "ui.rich-text", "ui.icon", "ui.image", "ui.avatar", "ui.media", "ui.canvas", "ui.svg", "ui.input", "ui.textarea", "ui.select", "ui.checkbox", "ui.radio", "ui.switch", "ui.slider", "ui.picker", "ui.form", "ui.button", "ui.list", "ui.nav", "ui.loading", "ui.scale", "ui.skeleton", "ui.progress", "ui.label", "ui.selection", "ui.camera", "shell.page", "shell.nav", "shell.tabbar", "shell.segment", "shell.drawer", "shell.modal", "shell.popover", "shell.toast", "shell.action-sheet", "shell.mask", "shell.popup", "shell.toolbar", "shell.page-container", "shell.keyboard-accessory", "shell.webview", "shell.ad", "ui.map", "gesture.draggable", "gesture.scrollable", "engineering.router-link", "engineering.transition", "engineering.animate", "engineering.error-boundary", "engineering.share-element", "capability.location", "capability.qr-code", "capability.camera"];
         };
         readonly props: {
             readonly type: "object";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteus-vue/component-ir",
-  "version": "0.3.0-beta.11",
+  "version": "0.3.0-beta.21",
   "description": "G-31 组件与 API 语义化（component-semantics-plan B1）：Component IR（C-IR）schema + 属性约束校验 + semantic 映射——组件=语义、属性=约束、Backend 消费 semantic 而非 tag（零依赖纯逻辑）",
   "type": "module",
   "license": "Apache-2.0",
@@ -19,7 +19,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@proteus-vue/contracts": "0.3.0-beta.11"
+    "@proteus-vue/contracts": "0.3.0-beta.11",
+    "@proteus-vue/slot-runtime": "0.3.0-beta.11"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json --emitDeclarationOnly && esbuild src/index.ts --bundle --format=esm --platform=neutral --outfile=dist/index.js"