feat(md-deck): support structured data-config with template layers

Allow md-deck layers to render markdown templates via {{var}}
substitution instead of only CSV props. Add config.ts to normalize
a JSON data-config attribute (size, grid, shape, layers) emitted by
the yaml code-block tag, taking precedence over legacy string props.

src/components/md-deck/CardLayer.tsx

@@ -89,7 +89,9 @@ export function CardLayer(props: CardLayerProps) {
                 "font-size": `${layer.fontSize || 3}mm`,
                 "text-align": getAlignStyle(layer.align),
               }}
-              innerHTML={renderLayerContent(props.cardData[layer.prop])}
+              innerHTML={renderLayerContent(
+                layer.template ?? props.cardData[layer.prop ?? ""],
+              )}
               onClick={(e) => handleLayerClick(index(), e)}
             />
             <Show when={isSelected() && isEditing()}>

src/components/md-deck/config.test.ts

@@ -0,0 +1,106 @@
+import { layersToConfigs, normalizeDeckConfig } from "./config";
+
+describe("layersToConfigs", () => {
+  test("parses compact string format (legacy)", () => {
+    const layers = layersToConfigs("title:1,1-5,1f8 body:1,5-8,8f3");
+    expect(layers).toHaveLength(2);
+    expect(layers[0]).toMatchObject({
+      prop: "title",
+      visible: true,
+      x1: 1,
+      y1: 1,
+      x2: 5,
+      y2: 1,
+      fontSize: 8,
+    });
+    expect(layers[1].prop).toBe("body");
+  });
+
+  test("parses structured list with prop layers", () => {
+    const layers = layersToConfigs([
+      { prop: "name", x1: 1, y1: 1, x2: 5, y2: 2, font: 12 },
+    ]);
+    expect(layers).toHaveLength(1);
+    expect(layers[0]).toMatchObject({
+      prop: "name",
+      template: undefined,
+      visible: true,
+      x1: 1,
+      y1: 1,
+      x2: 5,
+      y2: 2,
+      fontSize: 12,
+    });
+  });
+
+  test("parses structured list with template layers", () => {
+    const layers = layersToConfigs([
+      { template: "**{{name}}**", x1: 1, y1: 3, x2: 5, y2: 8, align: "l" },
+    ]);
+    expect(layers).toHaveLength(1);
+    expect(layers[0]).toMatchObject({
+      prop: undefined,
+      template: "**{{name}}**",
+      visible: true,
+      x1: 1,
+      y1: 3,
+      x2: 5,
+      y2: 8,
+      align: "l",
+    });
+  });
+
+  test("returns [] for absent/empty input", () => {
+    expect(layersToConfigs()).toEqual([]);
+    expect(layersToConfigs("")).toEqual([]);
+    expect(layersToConfigs([])).toEqual([]);
+  });
+});
+
+describe("normalizeDeckConfig", () => {
+  test("parses string dimensions", () => {
+    const cfg = normalizeDeckConfig({ size: "54x86", grid: "5x8" });
+    expect(cfg.sizeW).toBe(54);
+    expect(cfg.sizeH).toBe(86);
+    expect(cfg.gridW).toBe(5);
+    expect(cfg.gridH).toBe(8);
+  });
+
+  test("parses array dimensions", () => {
+    const cfg = normalizeDeckConfig({ size: [63, 88] });
+    expect(cfg.sizeW).toBe(63);
+    expect(cfg.sizeH).toBe(88);
+  });
+
+  test("coerces numeric strings for bleed/padding", () => {
+    const cfg = normalizeDeckConfig({ bleed: "2", padding: "3" });
+    expect(cfg.bleed).toBe(2);
+    expect(cfg.padding).toBe(3);
+  });
+
+  test("normalizes layers and back_layers", () => {
+    const cfg = normalizeDeckConfig({
+      layers: [
+        { prop: "name", x1: 1, y1: 1, x2: 5, y2: 1 },
+        { template: "{{body}}", x1: 1, y1: 2, x2: 5, y2: 8 },
+      ],
+      back_layers: "logo:1,1-2,2",
+    });
+    expect(cfg.frontLayers).toHaveLength(2);
+    expect(cfg.frontLayers[1].template).toBe("{{body}}");
+    expect(cfg.backLayers).toHaveLength(1);
+    expect(cfg.backLayers[0].prop).toBe("logo");
+  });
+
+  test("missing fields stay undefined", () => {
+    const cfg = normalizeDeckConfig({});
+    expect(cfg.sizeW).toBeUndefined();
+    expect(cfg.sizeH).toBeUndefined();
+    expect(cfg.gridW).toBeUndefined();
+    expect(cfg.gridH).toBeUndefined();
+    expect(cfg.bleed).toBeUndefined();
+    expect(cfg.padding).toBeUndefined();
+    expect(cfg.frontLayers).toEqual([]);
+    expect(cfg.backLayers).toEqual([]);
+  });
+});

src/components/md-deck/config.ts

@@ -0,0 +1,134 @@
+import type { CardShape, LayerConfig } from "./types";
+import { parseLayers } from "./hooks/layer-parser";
+
+/**
+ * YAML/JSON shape of an `md-deck` `data-config`.
+ *
+ * Mirrors the frontmatter `deck:` block and the `:md-deck` directive attrs,
+ * but allows `layers`/`back_layers` as structured lists where each layer is
+ * either a CSV `prop` or a markdown `template`.
+ */
+export interface DeckConfigYaml {
+  size?: string | [number, number];
+  grid?: string | [number, number];
+  bleed?: number | string;
+  padding?: number | string;
+  shape?: CardShape;
+  fixed?: boolean;
+  layers?: string | DeckLayerYaml[];
+  back_layers?: string | DeckLayerYaml[];
+}
+
+export interface DeckLayerYaml {
+  prop?: string;
+  template?: string;
+  x1?: number;
+  y1?: number;
+  x2?: number;
+  y2?: number;
+  font?: number;
+  fontSize?: number;
+  orientation?: "n" | "s" | "e" | "w";
+  align?: "l" | "c" | "r";
+  visible?: boolean;
+}
+
+export interface NormalizedDeckConfig {
+  sizeW?: number;
+  sizeH?: number;
+  gridW?: number;
+  gridH?: number;
+  bleed?: number;
+  padding?: number;
+  shape?: CardShape;
+  fixed?: boolean;
+  frontLayers: LayerConfig[];
+  backLayers: LayerConfig[];
+}
+
+/** Parse a "54x86" string or [54, 86] array into [w, h]. */
+function parseDimension(
+  v?: string | [number, number],
+): [number, number] | undefined {
+  if (!v) return undefined;
+  if (Array.isArray(v)) {
+    const [w, h] = v;
+    if (typeof w === "number" && typeof h === "number") return [w, h];
+    return undefined;
+  }
+  const parts = String(v)
+    .toLowerCase()
+    .split("x")
+    .map((n) => Number(n.trim()));
+  if (
+    parts.length === 2 &&
+    Number.isFinite(parts[0]) &&
+    Number.isFinite(parts[1])
+  ) {
+    return [parts[0], parts[1]];
+  }
+  return undefined;
+}
+
+/** Map a structured YAML layer to a LayerConfig. */
+function layerYamlToConfig(l: DeckLayerYaml): LayerConfig {
+  return {
+    prop: l.prop,
+    template: l.template,
+    visible: l.visible ?? true,
+    x1: l.x1 ?? 1,
+    y1: l.y1 ?? 1,
+    x2: l.x2 ?? 2,
+    y2: l.y2 ?? 2,
+    orientation: l.orientation,
+    fontSize: l.fontSize ?? l.font,
+    align: l.align,
+  };
+}
+
+/**
+ * Normalize a `layers`/`back_layers` value (compact string or structured list)
+ * into LayerConfig[]. Empty/absent → [].
+ */
+export function layersToConfigs(
+  layers?: string | DeckLayerYaml[],
+): LayerConfig[] {
+  if (!layers) return [];
+  if (typeof layers === "string") {
+    return parseLayers(layers).map((l) => ({
+      prop: l.prop,
+      visible: true,
+      x1: l.x1,
+      y1: l.y1,
+      x2: l.x2,
+      y2: l.y2,
+      orientation: l.orientation,
+      fontSize: l.fontSize,
+      align: l.align,
+    }));
+  }
+  return layers.map(layerYamlToConfig);
+}
+
+/**
+ * Normalize a parsed `data-config` object into concrete numeric config +
+ * ready-to-use layer lists. Missing fields are left undefined so callers can
+ * apply defaults.
+ */
+export function normalizeDeckConfig(cfg: DeckConfigYaml): NormalizedDeckConfig {
+  const size = parseDimension(cfg.size);
+  const grid = parseDimension(cfg.grid);
+  return {
+    sizeW: size?.[0],
+    sizeH: size?.[1],
+    gridW: grid?.[0],
+    gridH: grid?.[1],
+    bleed: typeof cfg.bleed === "string" ? Number(cfg.bleed) : cfg.bleed,
+    padding:
+      typeof cfg.padding === "string" ? Number(cfg.padding) : cfg.padding,
+    shape: cfg.shape,
+    fixed: cfg.fixed,
+    frontLayers: layersToConfigs(cfg.layers),
+    backLayers: layersToConfigs(cfg.back_layers),
+  };
+}

src/components/md-deck/editor-panel/LayerRow.tsx

@@ -120,7 +120,7 @@ export function LayerRow(props: LayerRowProps) {
         class="text-sm flex-1 truncate cursor-pointer hover:text-blue-600 select-none"
         onClick={props.onSelect}
       >
-        {props.layer.prop}
+        {props.layer.prop || (props.layer.template ? "(模板)" : "")}
       </span>
 
       <DropdownButton

src/components/md-deck/hooks/deckStore.ts

@@ -1,7 +1,7 @@
 import { createStore } from "solid-js/store";
 import { calculateDimensions } from "./dimensions";
 import { loadCSV, CSV } from "../../utils/csv-loader";
-import { formatLayers, initLayerConfigsForSide } from "./layer-parser";
+import { formatLayers } from "./layer-parser";
 import * as layerCrud from "./layer-crud";
 import type {
   CardData,
@@ -138,8 +138,8 @@ export interface DeckActions {
   loadCardsFromPath: (
     path: string,
     rawSrc: string,
-    layersStr?: string,
-    backLayersStr?: string,
+    frontLayers?: LayerConfig[],
+    backLayers?: LayerConfig[],
   ) => Promise<void>;
   setError: (error: string | null) => void;
   clearError: () => void;
@@ -442,8 +442,8 @@ export function createDeckStore(initialSrc: string = ""): DeckStore {
   const loadCardsFromPath = async (
     path: string,
     rawSrc: string,
-    layersStr: string = "",
-    backLayersStr: string = "",
+    frontLayers: LayerConfig[] = [],
+    backLayers: LayerConfig[] = [],
   ) => {
     if (!path) {
       setState({ error: "未指定 CSV 文件路径" });
@@ -466,12 +466,8 @@ export function createDeckStore(initialSrc: string = ""): DeckStore {
       setState({
         cards: data,
         activeTab: 0,
-        frontLayerConfigs: layerCrud.withKeys(
-          initLayerConfigsForSide(data, layersStr),
-        ),
-        backLayerConfigs: layerCrud.withKeys(
-          initLayerConfigsForSide(data, backLayersStr),
-        ),
+        frontLayerConfigs: layerCrud.withKeys(frontLayers),
+        backLayerConfigs: layerCrud.withKeys(backLayers),
         isLoading: false,
       });
       updateDimensions();

src/components/md-deck/hooks/layer-parser.ts

@@ -35,8 +35,10 @@ export function parseLayers(layersStr: string): Layer[] {
  * 格式化 layers 为字符串
  */
 export function formatLayers(layers: LayerConfig[]): string {
+  // Template-only layers have no prop and can't be represented in the
+  // compact string format, so they are skipped here.
   return layers
-    .filter((l) => l.visible)
+    .filter((l) => l.visible && l.prop)
     .map((l) => {
       let str = `${l.prop}:${l.x1},${l.y1}-${l.x2},${l.y2}`;
       if (l.fontSize) {

src/components/md-deck/index.tsx

@@ -2,9 +2,10 @@ import { customElement, noShadowDOM } from "solid-element";
 import { Show, onCleanup } from "solid-js";
 import { resolvePath } from "../utils/path";
 import { v4 as uuidv4 } from "uuid";
-import { createDeckStore } from "./hooks/deckStore";
+import { createDeckStore, DECK_DEFAULTS } from "./hooks/deckStore";
 import { registerDeck, unregisterDeck } from "./hooks/deck-registry";
-import type { CardShape } from "./types";
+import type { CardShape, LayerConfig } from "./types";
+import { normalizeDeckConfig, layersToConfigs } from "./config";
 import { DeckHeader } from "./DeckHeader";
 import { CardList } from "./CardList";
 import { DeckContent } from "./DeckContent";
@@ -68,49 +69,75 @@ customElement<DeckProps>(
     const deckId = `deck-${uuidv4()}`;
     registerDeck(deckId, store, resolvedSrc, csvPath);
 
+    // 读取 data-config（yaml/tag 代码块方式）：结构化配置优先
+    let config:
+      | ReturnType<typeof normalizeDeckConfig>
+      | undefined;
+    const dataConfigAttr = element?.getAttribute("data-config");
+    if (dataConfigAttr) {
+      try {
+        config = normalizeDeckConfig(JSON.parse(dataConfigAttr));
+      } catch (e) {
+        console.error("Invalid data-config on md-deck:", e);
+      }
+    }
+
     // 解析 size 属性（支持旧格式 "54x86" 和新格式）
-    if (props.size && props.size.includes("x")) {
+    if (config?.sizeW !== undefined && config.sizeH !== undefined) {
+      store.actions.setSizeW(config.sizeW);
+      store.actions.setSizeH(config.sizeH);
+    } else if (props.size && props.size.includes("x")) {
       const [w, h] = props.size.split("x").map(Number);
       store.actions.setSizeW(w);
       store.actions.setSizeH(h);
     } else {
-      store.actions.setSizeW(props.sizeW ?? 54);
-      store.actions.setSizeH(props.sizeH ?? 86);
+      store.actions.setSizeW(props.sizeW ?? DECK_DEFAULTS.SIZE_W);
+      store.actions.setSizeH(props.sizeH ?? DECK_DEFAULTS.SIZE_H);
     }
 
     // 解析 grid 属性（支持旧格式 "5x8" 和新格式）
-    if (props.grid && props.grid.includes("x")) {
+    if (config?.gridW !== undefined && config.gridH !== undefined) {
+      store.actions.setGridW(config.gridW);
+      store.actions.setGridH(config.gridH);
+    } else if (props.grid && props.grid.includes("x")) {
       const [w, h] = props.grid.split("x").map(Number);
       store.actions.setGridW(w);
       store.actions.setGridH(h);
     } else {
-      store.actions.setGridW(props.gridW ?? 5);
-      store.actions.setGridH(props.gridH ?? 8);
+      store.actions.setGridW(props.gridW ?? DECK_DEFAULTS.GRID_W);
+      store.actions.setGridH(props.gridH ?? DECK_DEFAULTS.GRID_H);
     }
 
     // 解析 bleed 和 padding（支持旧字符串格式和新数字格式）
-    if (typeof props.bleed === "string") {
+    if (config?.bleed !== undefined) {
+      store.actions.setBleed(config.bleed);
+    } else if (typeof props.bleed === "string") {
       store.actions.setBleed(Number(props.bleed));
     } else {
-      store.actions.setBleed(props.bleed ?? 1);
+      store.actions.setBleed(props.bleed ?? DECK_DEFAULTS.BLEED);
     }
 
-    if (typeof props.padding === "string") {
+    if (config?.padding !== undefined) {
+      store.actions.setPadding(config.padding);
+    } else if (typeof props.padding === "string") {
       store.actions.setPadding(Number(props.padding));
     } else {
-      store.actions.setPadding(props.padding ?? 2);
+      store.actions.setPadding(props.padding ?? DECK_DEFAULTS.PADDING);
     }
 
     // 设置形状
-    store.actions.setShape(props.shape ?? "rectangle");
+    store.actions.setShape(config?.shape ?? props.shape ?? "rectangle");
+
+    // 确定前后图层（data-config 优先，回退旧 layers 字符串）
+    const frontLayers: LayerConfig[] = config
+      ? config.frontLayers
+      : layersToConfigs((props.layers as string) || "");
+    const backLayers: LayerConfig[] = config
+      ? config.backLayers
+      : layersToConfigs((props.backLayers as string) || "");
 
     // 加载 CSV 数据
-    store.actions.loadCardsFromPath(
-      resolvedSrc,
-      csvPath,
-      (props.layers as string) || "",
-      (props.backLayers as string) || "",
-    );
+    store.actions.loadCardsFromPath(resolvedSrc, csvPath, frontLayers, backLayers);
 
     // 清理函数
     onCleanup(() => {

src/components/md-deck/types.ts

@@ -7,7 +7,10 @@ export type CardSide = "front" | "back";
 export type { CardShape } from "../../plotcutter/contour";
 
 export interface Layer {
-  prop: string;
+  /** CSV column the layer reads, when it renders a prop value. */
+  prop?: string;
+  /** Markdown template (with {{var}} substitution) when the layer renders a template. */
+  template?: string;
   x1: number;
   y1: number;
   x2: number;
@@ -18,12 +21,15 @@ export interface Layer {
 }
 
 export interface LayerConfig {
-  prop: string;
+  /** CSV column the layer reads, when it renders a prop value. */
+  prop?: string;
+  /** Markdown template (with {{var}} substitution) when the layer renders a template. */
+  template?: string;
   visible: boolean;
-  x1: number;
-  y1: number;
-  x2: number;
-  y2: number;
+  x1?: number;
+  y1?: number;
+  x2?: number;
+  y2?: number;
   orientation?: "n" | "s" | "e" | "w";
   fontSize?: number;
   align?: "l" | "c" | "r";