struct2ui 0.1.0__py3-none-any.whl

struct2ui/editor.py

@@ -0,0 +1,1171 @@
+"""Top-level widget: flow buttons + a content area driven by a Renderer.
+
+Responsibilities (intentionally narrow):
+  1. Load the speech/flow JSON file.
+  2. Build flow buttons.
+  3. On selection, build a schema tree and hand off to the appropriate renderer.
+
+Schema parsing lives in schema.py. UI rendering lives in the ui/ package.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, List
+
+from Qt import QtCore, QtGui, QtWidgets
+
+from .schema import (
+    SchemaRegistry, FlowValidator, merge_instance,
+    StructField, ArrayField,
+)
+from .ui import pick_renderer, collect_view_values
+from .exporters import (
+    emit_c, dumps_json, emit_bin, merge_abi, verify_sections,
+    parse_c_source, build_schema_dict,
+)
+
+
+class StructEditor(QtWidgets.QWidget):
+
+    # Button keys and their built-in defaults. Each entry: the fallback text
+    # label, the custom icon filename under icons/, and the Qt standard icon
+    # used when the custom file is missing. appearance overrides per key.
+    _BUTTON_DEFAULTS = {
+        'modules': ('Modules', 'widgets_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                    'SP_DirOpenIcon'),
+        'pipeline': ('Pipeline', 'flowchart_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                     'SP_FileIcon'),
+        'reload': ('Reload', 'refresh_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                   'SP_BrowserReload'),
+        'save': ('Save', 'save_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                 'SP_DialogSaveButton'),
+        'save_as': ('Save As', 'save_as_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                    'SP_DriveFDIcon'),
+        'export': ('Export', 'export_notes_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                   'SP_ArrowDown'),
+        'elf': ('ELF', 'elf.png',
+                'SP_FileDialogContentsView'),
+        'report': ('Report', 'report_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                   'SP_MessageBoxWarning'),
+        'c2j': ('C2J', 'c2j.png',
+                'SP_FileDialogDetailedView'),
+        'settings': ('Settings', 'settings_24dp_000000_FILL0_wght400_GRAD0_opsz24.png',
+                     'SP_FileDialogDetailedView'),
+    }
+
+    def __init__(self, flow_file: str, cfg_dir: str, parent=None,
+                 appearance: Dict[str, Dict[str, Any]] = None,
+                 settings_org: str = 'struct2ui',
+                 settings_app: str = 'StructEditor'):
+        super().__init__(parent)
+        # Per-button appearance config (for embedding as a standalone module).
+        # Shape: {key: {'mode': 'text'|'default'|'custom', 'icon': path,
+        # 'text': label}}. Unspecified keys fall back to _BUTTON_DEFAULTS
+        # (custom icon, then standard icon, then text).
+        self._appearance: Dict[str, Dict[str, Any]] = appearance or {}
+        self._icons_dir = os.path.join(
+            os.path.dirname(os.path.abspath(__file__)), 'icons')
+        # Remember the last paths the user loaded. The caller's
+        # arguments act as the seed/default; a previously saved value (if
+        # any) overrides them so each launch reopens what was last used.
+        self._settings = QtCore.QSettings(settings_org, settings_app)
+        self.speech_path = self._settings.value('flow_path', flow_file)
+        self.struct_dir = self._settings.value('cfg_dir', cfg_dir)
+        # Optional ELF the user picks for later .bin layout verification.
+        # Empty string means no ELF selected (verification stays off).
+        self.elf_path = self._settings.value('elf_path', '') or ''
+
+        # Flow data (populated by _reload via _load_flow).
+        self.registry: SchemaRegistry = None  # type: ignore[assignment]
+        self._group_key: str = ''
+        self._flow: List[str] = []
+        self._section_specs: Dict[str, Dict[str, Any]] = {}
+        # Raw loaded flow document; Save patches and writes it back.
+        self._raw_data: Dict[str, Any] = {}
+        # Label of the section currently shown in the content area (None when
+        # an error/summary panel is shown). current_values() reads it back.
+        self._active_label: str = ''
+        # ELF layout verification report (strictest policy). Rebuilt on every
+        # reload / pipeline change; consulted by the Report panel and before
+        # exporting .bin. Stays empty when no ELF is selected.
+        self._elf_report = None
+        # Step 4b: errors that pin to a specific stage in the pipeline.
+        # Filled in _reload(); consumed by show_section() so a stage with
+        # errors paints an error panel instead of its (possibly broken)
+        # parameter UI. Errors that are not stage-scoped (cfg_t keyword
+        # mistakes, S1/S2/S4 declaration issues) stay console-only here.
+        self._stage_errors: Dict[str, List[Any]] = {}
+
+        # C2J tool state: last picked .c/.h path and the parse result it
+        # produced. Lives outside _reload() because the C->JSON converter is a
+        # standalone side tool that does not touch the pipeline/schema flow.
+        self._c2j_path: str = ''
+
+        # ---- UI skeleton ------------------------------------------------- #
+        # Step 4a: top path bar lets the user point at any cfg_t directory
+        # and any flow JSON. Edits do not auto-apply; the user clicks
+        # Reload to rebuild schema + flow (matches the staged reload model
+        # we use elsewhere - one explicit user action, one full rebuild).
+        self.path_bar = self._build_path_bar()
+
+        self.buttons_bar = QtWidgets.QWidget(self)
+        self.buttons_layout = QtWidgets.QHBoxLayout(self.buttons_bar)
+        self.buttons_layout.setContentsMargins(0, 0, 0, 0)
+        self.buttons_layout.setSpacing(12)
+
+        self.content_area = QtWidgets.QScrollArea(self)
+        self.content_area.setWidgetResizable(True)
+        self._content_widget: QtWidgets.QWidget = QtWidgets.QWidget()
+        self.content_area.setWidget(self._content_widget)
+
+        main_layout = QtWidgets.QVBoxLayout(self)
+        main_layout.addWidget(self.path_bar)
+        main_layout.addWidget(self.buttons_bar)
+        main_layout.addWidget(self.content_area)
+
+        self._reload()
+
+    # ---- path bar (Step 4a) --------------------------------------------- #
+    def _build_path_bar(self) -> QtWidgets.QWidget:
+        bar = QtWidgets.QWidget(self)
+        layout = QtWidgets.QHBoxLayout(bar)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(6)
+
+        # All buttons on one row. Appearance (text / default icon / custom
+        # icon) is resolved per key via _make_button so a host application
+        # can override any of them through the `appearance` argument.
+        self.cfg_btn = self._make_button('modules', self._pick_cfg_dir)
+        self.flow_btn = self._make_button('pipeline', self._pick_flow_file)
+        reload_btn = self._make_button('reload', self._on_reload_clicked)
+        save_btn = self._make_button('save', self._on_save_clicked)
+        save_as_btn = self._make_button('save_as', self._on_save_as_clicked)
+        export_btn = self._make_button('export', self._on_export_clicked)
+        self.elf_btn = self._make_button('elf', self._pick_elf_file)
+        self.elf_btn.setCheckable(True)
+        self.report_btn = self._make_button('report', self._on_report_clicked)
+        self.c2j_btn = self._make_button('c2j', self._on_c2j_clicked)
+        self.settings_btn = self._make_button('settings', self._on_settings_clicked)
+
+        # Group 1: inputs (Modules / Pipeline / ELF) plus Reload, which
+        # applies the selected sources by rebuilding. Separator divides it
+        # from group 2: outputs (Save / Save As / Export). Separator then
+        # divides group 3: tools (C2J / Report).
+        layout.addWidget(self.cfg_btn)
+        layout.addWidget(self.flow_btn)
+        layout.addWidget(self.elf_btn)
+        layout.addWidget(reload_btn)
+        layout.addWidget(self._make_separator())
+        layout.addWidget(save_btn)
+        layout.addWidget(save_as_btn)
+        layout.addWidget(export_btn)
+        layout.addWidget(self._make_separator())
+        layout.addWidget(self.c2j_btn)
+        layout.addWidget(self.report_btn)
+        # Stretch pushes Settings to the far right of the button row.
+        layout.addStretch(1)
+        layout.addWidget(self.settings_btn)
+
+        self._refresh_path_tooltips()
+        return bar
+
+    def _make_separator(self) -> QtWidgets.QFrame:
+        line = QtWidgets.QFrame(self)
+        line.setFrameShape(QtWidgets.QFrame.VLine)
+        line.setFrameShadow(QtWidgets.QFrame.Sunken)
+        return line
+
+    def _make_button(self, key: str, on_click) -> QtWidgets.QPushButton:
+        """Build one path-bar button honouring per-key appearance config.
+
+        Resolution order for the visual:
+          mode 'text'    -> show the label text, no icon
+          mode 'custom'  -> use cfg['icon'] (or the bundled icons/ file)
+          mode 'default' -> use the Qt standard icon
+        Default mode is 'custom'; if the custom icon file is missing it
+        falls back to the standard icon, then to text. The label is always
+        kept as the accessible name / tooltip base.
+        """
+        label, icon_file, std_name = self._BUTTON_DEFAULTS[key]
+        cfg = self._appearance.get(key, {})
+        text = cfg.get('text', label)
+        mode = cfg.get('mode', 'custom')
+
+        btn = QtWidgets.QPushButton(self)
+        btn.clicked.connect(on_click)
+        btn.setToolTip(text)
+
+        if mode == 'text':
+            btn.setText(text)
+            return btn
+
+        if mode == 'custom':
+            icon_path = cfg.get('icon') or os.path.join(
+                self._icons_dir, icon_file)
+            if os.path.exists(icon_path):
+                btn.setIcon(QtGui.QIcon(icon_path))
+                return btn
+            mode = 'default'  # fall through to standard icon
+
+        std = getattr(QtWidgets.QStyle, std_name, None)
+        if std is not None:
+            btn.setIcon(self.style().standardIcon(std))
+        else:
+            btn.setText(text)  # last-resort fallback
+        return btn
+
+    def _refresh_path_tooltips(self) -> None:
+        modules_text = self._appearance.get('modules', {}).get('text', 'Modules')
+        pipeline_text = self._appearance.get('pipeline', {}).get('text', 'Pipeline')
+        self.cfg_btn.setToolTip(
+            f'{modules_text}: {self.struct_dir}' if self.struct_dir
+            else f'{modules_text}: (select modules directory)')
+        self.flow_btn.setToolTip(
+            f'{pipeline_text}: {self.speech_path}' if self.speech_path
+            else f'{pipeline_text}: (select pipeline JSON)')
+        self._refresh_elf_tooltip()
+
+    def _refresh_elf_tooltip(self) -> None:
+        elf_text = self._appearance.get('elf', {}).get('text', 'ELF')
+        if self.elf_path:
+            self.elf_btn.setToolTip(
+                f'{elf_text}: {self.elf_path}\n(click to change, or pick the '
+                'same file to clear)')
+        else:
+            self.elf_btn.setToolTip(
+                f'{elf_text}: (none - pick an ELF to enable .bin layout '
+                'verification)')
+        self.elf_btn.setChecked(bool(self.elf_path))
+
+    def _pick_cfg_dir(self) -> None:
+        start = self.struct_dir or os.getcwd()
+        chosen = QtWidgets.QFileDialog.getExistingDirectory(
+            self, 'Select modules directory', start)
+        if chosen:
+            self.struct_dir = chosen
+            self._save_paths()
+            self._refresh_path_tooltips()
+            self._reload()
+
+    def _pick_flow_file(self) -> None:
+        start = self.speech_path or os.getcwd()
+        chosen, _ = QtWidgets.QFileDialog.getOpenFileName(
+            self, 'Select pipeline JSON', start, 'JSON files (*.json)')
+        if chosen:
+            self.speech_path = chosen
+            self._save_paths()
+            self._refresh_path_tooltips()
+            self._reload()
+
+    def _pick_elf_file(self) -> None:
+        # Picking the currently-selected ELF again clears the selection,
+        # turning verification back off.
+        start = self.elf_path or os.getcwd()
+        chosen, _ = QtWidgets.QFileDialog.getOpenFileName(
+            self, 'Select ELF for layout verification', start,
+            'ELF files (*.elf *.axf *.out);;All files (*)')
+        if not chosen:
+            self._refresh_elf_tooltip()
+            return
+        self.elf_path = '' if chosen == self.elf_path else chosen
+        self._settings.setValue('elf_path', self.elf_path)
+        self._refresh_elf_tooltip()
+        # Re-run the full load so ELF verification re-runs and the landing
+        # panel reflects any new layout issues.
+        self._reload()
+
+    def _on_reload_clicked(self) -> None:
+        self._save_paths()
+        self._refresh_path_tooltips()
+        self._reload()
+
+    def _save_paths(self) -> None:
+        self._settings.setValue('cfg_dir', self.struct_dir)
+        self._settings.setValue('flow_path', self.speech_path)
+
+    def closeEvent(self, ev) -> None:  # Qt override
+        self._save_paths()
+        super().closeEvent(ev)
+
+    # ---- reload (build schema + flow + UI from current paths) ----------- #
+    def _reload(self) -> None:
+        # Schema registry (loads cfg_t/*.json once).
+        self.registry = SchemaRegistry(self.struct_dir)
+
+        # Cross-validate abc.json against the loaded schema (Step 2/3).
+        flow_report = FlowValidator(self.registry, self.speech_path).validate()
+        self.registry.report.extend(flow_report)
+
+        # Print load report to console (Step 1~3: console only).
+        print(self.registry.report.format(), end='')
+
+        # Reset flow data and rebuild UI from the new sources. Clearing
+        # _active_label first is essential: the upcoming _on_button_clicked
+        # would otherwise call _capture_active_section() against the previous
+        # pipeline's still-live widget and write its stale values into the
+        # freshly loaded document (overwriting same-named sections, so the
+        # new file appears not to load).
+        self._active_label = ''
+        self._group_key = ''
+        self._flow = []
+        self._section_specs = {}
+        self._raw_data = {}
+        self._stage_errors = {}
+        self._elf_report = None
+        self._load_flow()
+        self._index_stage_errors()
+        # Strictest ELF layout verification. Runs on every reload / pipeline
+        # change; skipped (left empty) when no ELF is selected.
+        self._verify_elf()
+        self._build_buttons()
+        # Step 4c: when the load report has any issue, land on a summary
+        # panel instead of auto-selecting the first stage. Lets the user
+        # see what's wrong before clicking into individual tabs. A clean
+        # load skips the summary and goes straight to the first stage.
+        report = self.registry.report
+        elf_failed = self._elf_report is not None and (
+            self._elf_report.has_errors or self._elf_report.has_warnings)
+        if report.has_errors or report.has_warnings or elf_failed:
+            self._show_report()
+        elif self._flow:
+            # Clean load: mirror a user click on the first stage so the
+            # button reflects the active tab. Going through the click
+            # handler keeps button-checked state and content in sync.
+            self._on_button_clicked(self._flow[0])
+        else:
+            self._set_content(QtWidgets.QWidget())
+
+    def _index_stage_errors(self) -> None:
+        """Bucket pipeline errors by stage name.
+
+        Only errors raised against the active pipeline file and whose path
+        starts with '<group_key> -> <stage>' are recognised as stage-scoped.
+        Cfg_t-side errors (declaration mistakes, S1/S2/S4) and pipeline
+        errors at the group/Flow level fall through and remain visible only
+        in the console report.
+        """
+        self._stage_errors = {label: [] for label in self._flow}
+        if not self._group_key:
+            return
+        prefix = f'{self._group_key} -> '
+        for issue in self.registry.report.errors:
+            if issue.file != self.speech_path:
+                continue
+            if not issue.path.startswith(prefix):
+                continue
+            tail = issue.path[len(prefix):]
+            stage = tail.split(' -> ', 1)[0]
+            if stage in self._stage_errors:
+                self._stage_errors[stage].append(issue)
+
+    def _other_errors(self) -> List[Any]:
+        """Errors not pinned to any stage tab.
+
+        These are cfg_t-side problems (keyword typos, S1/S2/S4 semantic
+        audit) and pipeline errors at the group/Flow level. They have no
+        stage tab to live in, so the summary panel (Step 5 B) shows them
+        in full instead of leaving them console-only.
+        """
+        pinned = {id(e) for errs in self._stage_errors.values() for e in errs}
+        return [e for e in self.registry.report.errors if id(e) not in pinned]
+
+    # ---- ELF layout verification ---------------------------------------- #
+    def _flow_sections(self) -> List[Any]:
+        """(label, type_name, None) for every stage used by the selected
+        pipeline file. Only structs referenced by the pipeline are returned;
+        the modules library (struct_dir) is never enumerated here. Unlike
+        _export_sections this does not touch live editors, so it is safe to
+        call during reload before the UI exists.
+        """
+        out: List[Any] = []
+        for label in self._flow:
+            spec = self._section_specs.get(label)
+            if not isinstance(spec, dict):
+                continue
+            type_name = spec.get('type') or ''
+            if type_name:
+                out.append((label, type_name, None))
+        return out
+
+    def _verify_elf(self) -> None:
+        """Cross-check the cfg structs *used by the pipeline file* against the
+        selected ELF's DWARF (strictest policy). Module-only mode (no pipeline
+        loaded) is not verified. No ELF -> no verification.
+        """
+        self._elf_report = None
+        if not self.elf_path or self.registry is None:
+            return
+        # Pipeline-only: nothing to check without a loaded flow.
+        sections = self._flow_sections()
+        if not sections:
+            return
+        abi = merge_abi(self._raw_data.get('abi'))
+        self._elf_report = verify_sections(
+            sections, self.registry, self.elf_path, abi)
+        print(self._elf_report.format(), end='')
+
+    # ---- flow loading ---------------------------------------------------- #
+    def _load_flow(self) -> None:
+        if not os.path.exists(self.speech_path):
+            return
+        try:
+            with open(self.speech_path, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+        except Exception:
+            return
+        if not isinstance(data, dict) or not data:
+            return
+        self._group_key = next(iter(data.keys()))
+        group = data.get(self._group_key, {})
+        if not isinstance(group, dict):
+            return
+        # Keep the raw loaded document so Save can write it back verbatim,
+        # patching only the 'items' of edited sections. This preserves group
+        # structure, render hints and any keys the UI does not render.
+        self._raw_data = data
+        self._flow = list(group.get('Flow', []) or [])
+        self._section_specs = {
+            label: spec for label, spec in group.items()
+            if label != 'Flow' and isinstance(spec, dict)
+        }
+
+    # ---- buttons --------------------------------------------------------- #
+    def _build_buttons(self) -> None:
+        while self.buttons_layout.count():
+            item = self.buttons_layout.takeAt(0)
+            w = item.widget()
+            if w is not None:
+                w.setParent(None)
+        for label in self._flow:
+            btn = QtWidgets.QPushButton(label)
+            btn.setCheckable(True)
+            btn.clicked.connect(lambda _checked=False, lb=label: self._on_button_clicked(lb))
+            self.buttons_layout.addWidget(btn)
+
+    def _on_button_clicked(self, label: str) -> None:
+        # Preserve edits made in the section we are leaving before its widgets
+        # are destroyed by show_section().
+        self._capture_active_section()
+        for i in range(self.buttons_layout.count()):
+            w = self.buttons_layout.itemAt(i).widget()
+            if isinstance(w, QtWidgets.QPushButton):
+                w.setChecked(w.text() == label)
+        self.show_section(label)
+
+    # ---- section rendering ---------------------------------------------- #
+    def show_section(self, label: str) -> None:
+        # Step 4b: if this stage has pipeline errors, paint the error panel
+        # in place of the parameter UI. The parameter renderer assumes the
+        # stage spec is well-formed; rendering it with broken inputs would
+        # either crash or silently hide the cause from the user.
+        stage_errors = self._stage_errors.get(label) or []
+        if stage_errors:
+            self._active_label = ''
+            self._set_content(self._make_error_panel(label, stage_errors))
+            return
+
+        spec = self._section_specs.get(label)
+        if not isinstance(spec, dict):
+            self._active_label = ''
+            self._set_content(QtWidgets.QWidget())
+            return
+        type_name = spec.get('type') or ''
+        provided = spec.get('items', {}) or {}
+
+        root = self.registry.build(type_name)
+        values = merge_instance(root, provided)
+        renderer = pick_renderer(root, override=spec.get('render'))
+        widget = renderer.render(root, values)
+        self._active_label = label
+        self._set_content(widget)
+
+    def current_values(self) -> Dict[str, Any]:
+        """Read the live editor values of the active section back into a dict.
+
+        Returns the section's values keyed by field name (matching the schema
+        of its `type`), or an empty dict when no parameter section is shown
+        (e.g. an error/summary panel is active). This is the read-back entry
+        point that downstream file-format export (UI -> JSON/.c/.bin) builds on.
+        """
+        values = collect_view_values(self._content_widget)
+        return values if isinstance(values, dict) else {}
+
+    # ---- save (UI -> JSON) ---------------------------------------------- #
+    def _capture_active_section(self) -> None:
+        """Read the live editors of the active section back into the raw
+        document, so navigating away or saving keeps the user's edits.
+
+        No-op when no parameter section is active (e.g. an error/summary
+        panel) or when the read-back yields nothing.
+        """
+        if not self._active_label:
+            return
+        values = collect_view_values(self._content_widget)
+        if not isinstance(values, dict):
+            return
+        spec = self._section_specs.get(self._active_label)
+        if isinstance(spec, dict):
+            spec['items'] = values
+        group = self._raw_data.get(self._group_key)
+        if isinstance(group, dict) and isinstance(
+                group.get(self._active_label), dict):
+            group[self._active_label]['items'] = values
+
+    def _on_save_clicked(self) -> None:
+        if not self._raw_data:
+            return
+        self._save_to(self.speech_path)
+
+    def _on_save_as_clicked(self) -> None:
+        if not self._raw_data:
+            return
+        start = self.speech_path or os.getcwd()
+        chosen, _ = QtWidgets.QFileDialog.getSaveFileName(
+            self, 'Save pipeline JSON as', start, 'JSON files (*.json)')
+        if chosen:
+            self._save_to(chosen)
+
+    def _multiline_wrap_map(self) -> Dict[tuple, int]:
+        """Map JSON path -> values-per-row for every widget=multiline scalar
+        array reachable from a pipeline stage. Path mirrors the saved document
+        layout: (group_key, stage_label, 'items', field, [nested...]).
+        """
+        wrap: Dict[tuple, int] = {}
+        if not self._group_key or self.registry is None:
+            return wrap
+
+        def row_size(f: ArrayField) -> int:
+            if f.meta.get('widget') != 'multiline':
+                return 0
+            shape = f.meta.get('shape')
+            if isinstance(shape, (list, tuple)) and shape:
+                return int(shape[-1])
+            return 0
+
+        def walk(node, prefix: tuple) -> None:
+            if isinstance(node, StructField):
+                for child in node.children:
+                    walk(child, prefix + (child.name,))
+            elif isinstance(node, ArrayField):
+                rs = row_size(node)
+                if rs > 0 and not isinstance(node.element, StructField):
+                    wrap[prefix] = rs
+                elif isinstance(node.element, StructField):
+                    for i in range(node.count):
+                        walk(node.element, prefix + (i,))
+
+        for label in self._flow:
+            spec = self._section_specs.get(label)
+            if not isinstance(spec, dict):
+                continue
+            type_name = spec.get('type') or ''
+            if not type_name:
+                continue
+            root = self.registry.build(type_name)
+            base = (self._group_key, label, 'items')
+            for child in root.children:
+                walk(child, base + (child.name,))
+        return wrap
+
+    def _save_to(self, path: str) -> None:
+        # Fold the active section's live values in before serialising.
+        self._capture_active_section()
+        wrap_map = self._multiline_wrap_map()
+        resolver = (lambda p: wrap_map.get(p, 0)) if wrap_map else None
+        try:
+            with open(path, 'w', encoding='utf-8') as f:
+                f.write(dumps_json(self._raw_data, resolver))
+        except Exception as exc:
+            QtWidgets.QMessageBox.critical(
+                self, 'Save failed', f'Could not write {path}:\n{exc}')
+            return
+        # Saving As redirects subsequent Save/Reload to the new file.
+        if path != self.speech_path:
+            self.speech_path = path
+            self._refresh_path_tooltips()
+            self._save_paths()
+        QtWidgets.QMessageBox.information(
+            self, 'Saved', f'Pipeline saved to:\n{path}')
+
+    # ---- export (UI -> .c / .bin) --------------------------------------- #
+    _EXPORT_FILTERS = {
+        'c': 'C source (*.c)',
+        'bin': 'Binary (*.bin)',
+    }
+
+    def _on_export_clicked(self) -> None:
+        # Remember the last chosen export type; default to .c. The remembered
+        # type pre-selects the matching filter so the next export defaults to
+        # what was used before.
+        last_type = self._settings.value('export_type', 'c')
+        if last_type not in self._EXPORT_FILTERS:
+            last_type = 'c'
+        filters = ';;'.join(self._EXPORT_FILTERS.values())
+        start = self.speech_path or os.getcwd()
+        if start:
+            start = os.path.splitext(start)[0] + '.' + last_type
+
+        chosen, selected_filter = QtWidgets.QFileDialog.getSaveFileName(
+            self, 'Export as', start, filters,
+            self._EXPORT_FILTERS[last_type])
+        if not chosen:
+            return
+
+        ext = os.path.splitext(chosen)[1].lstrip('.').lower()
+        export_type = ext if ext in self._EXPORT_FILTERS else (
+            'bin' if selected_filter == self._EXPORT_FILTERS['bin'] else 'c')
+        if not ext:
+            chosen = f'{chosen}.{export_type}'
+        self._settings.setValue('export_type', export_type)
+
+        # Strictest ELF check before a .bin export. The .bin is a raw image
+        # of the target struct memory, so a layout mismatch with the ELF is
+        # the case that matters most. We still write the file (per design),
+        # but jump to the Report panel afterwards so the mismatch is seen.
+        elf_failed = False
+        if export_type == 'bin' and self.elf_path:
+            self._verify_elf()
+            elf_failed = self._elf_report is not None and \
+                self._elf_report.has_errors
+
+        try:
+            content = self._render_export(export_type)
+        except Exception as exc:
+            QtWidgets.QMessageBox.critical(
+                self, 'Export failed', f'Could not build export:\n{exc}')
+            return
+        try:
+            if isinstance(content, bytes):
+                with open(chosen, 'wb') as f:
+                    f.write(content)
+            else:
+                with open(chosen, 'w', encoding='utf-8') as f:
+                    f.write(content)
+        except Exception as exc:
+            QtWidgets.QMessageBox.critical(
+                self, 'Export failed', f'Could not write {chosen}:\n{exc}')
+            return
+
+        if elf_failed:
+            n = len(self._elf_report.errors)
+            self._show_report()
+            QtWidgets.QMessageBox.warning(
+                self, 'Exported with ELF mismatch',
+                f'Exported ({export_type}) to:\n{chosen}\n\n'
+                f'WARNING: {n} ELF layout error'
+                f"{'s' if n != 1 else ''} detected. See the Report panel.")
+            return
+        QtWidgets.QMessageBox.information(
+            self, 'Exported', f'Exported ({export_type}) to:\n{chosen}')
+
+    def _export_sections(self) -> List[Any]:
+        """Collect every pipeline section as (label, type_name, values).
+
+        The active section's live editor values are folded back first so its
+        latest edits are included; all sections are then read uniformly from
+        the raw document.
+        """
+        self._capture_active_section()
+        sections: List[Any] = []
+        for label in self._flow:
+            spec = self._section_specs.get(label)
+            if not isinstance(spec, dict):
+                continue
+            type_name = spec.get('type') or ''
+            if not type_name:
+                continue
+            sections.append((label, type_name, spec.get('items', {}) or {}))
+        return sections
+
+    def _render_export(self, export_type: str):
+        sections = self._export_sections()
+        if export_type == 'bin':
+            abi = merge_abi(self._raw_data.get('abi'))
+            return emit_bin(sections, self.registry, abi)
+        return emit_c(sections, self.registry)
+
+    def _make_error_panel(self, label: str,
+                          issues: List[Any]) -> QtWidgets.QWidget:
+        panel = QtWidgets.QWidget()
+        layout = QtWidgets.QVBoxLayout(panel)
+        layout.setContentsMargins(8, 8, 8, 8)
+
+        header = QtWidgets.QLabel(
+            f"Stage '{label}' has {len(issues)} error"
+            f"{'s' if len(issues) != 1 else ''}:")
+        header.setStyleSheet('font-weight: bold; color: #b00020;')
+        layout.addWidget(header)
+
+        list_widget = QtWidgets.QListWidget()
+        list_widget.setWordWrap(True)
+        for issue in issues:
+            text_lines = [f'at {issue.path}', issue.message]
+            if issue.suggestion:
+                text_lines.append(issue.suggestion)
+            list_widget.addItem('\n'.join(text_lines))
+        layout.addWidget(list_widget)
+        return panel
+
+    def _make_summary_panel(self) -> QtWidgets.QWidget:
+        """Landing panel shown after load when the report has any issue.
+
+        Errors are summarised by stage so the user can pick which tab to
+        open; the per-stage details live in the error panel rendered by
+        show_section() (Step 4b). Warnings are listed in full because they
+        are not pinned to any tab.
+        """
+        report = self.registry.report
+        panel = QtWidgets.QWidget()
+        layout = QtWidgets.QVBoxLayout(panel)
+        layout.setContentsMargins(8, 8, 8, 8)
+        layout.setSpacing(8)
+
+        header = QtWidgets.QLabel('Configuration loaded with issues')
+        header.setStyleSheet('font-weight: bold; font-size: 14px;')
+        layout.addWidget(header)
+
+        if report.has_errors:
+            stages_with_errors = [
+                (s, len(errs)) for s, errs in self._stage_errors.items()
+                if errs
+            ]
+            other_errors = self._other_errors()
+
+            err_label = QtWidgets.QLabel(f'Errors: {len(report.errors)}')
+            err_label.setStyleSheet('font-weight: bold; color: #b00020;')
+            layout.addWidget(err_label)
+
+            if stages_with_errors:
+                err_list = QtWidgets.QListWidget()
+                err_list.setWordWrap(True)
+                for stage, count in stages_with_errors:
+                    noun = 'error' if count == 1 else 'errors'
+                    item = QtWidgets.QListWidgetItem(
+                        f"Stage '{stage}': {count} {noun} "
+                        f"(double-click to open)")
+                    item.setData(QtCore.Qt.UserRole, stage)
+                    err_list.addItem(item)
+                err_list.itemActivated.connect(
+                    self._on_summary_item_activated)
+                layout.addWidget(err_list)
+
+            # Step 5 (B): errors not pinned to any stage (cfg_t-side typos,
+            # S1/S2/S4 audit, group/Flow-level problems) have no tab to open,
+            # so list them in full here instead of pointing at the console.
+            if other_errors:
+                other_label = QtWidgets.QLabel(
+                    f'Other errors (not pinned to any stage): '
+                    f'{len(other_errors)}')
+                other_label.setStyleSheet(
+                    'font-weight: bold; color: #b00020;')
+                layout.addWidget(other_label)
+
+                other_list = QtWidgets.QListWidget()
+                other_list.setWordWrap(True)
+                for issue in other_errors:
+                    lines = [f'{issue.file}']
+                    if issue.path:
+                        lines.append(f'at {issue.path}')
+                    lines.append(issue.message)
+                    if issue.suggestion:
+                        lines.append(issue.suggestion)
+                    other_list.addItem('\n'.join(lines))
+                layout.addWidget(other_list)
+
+        if report.has_warnings:
+            warn_label = QtWidgets.QLabel(
+                f'Warnings: {len(report.warnings)}')
+            warn_label.setStyleSheet('font-weight: bold; color: #a05a00;')
+            layout.addWidget(warn_label)
+
+            warn_list = QtWidgets.QListWidget()
+            warn_list.setWordWrap(True)
+            for issue in report.warnings:
+                lines = [f'at {issue.path}', issue.message]
+                if issue.suggestion:
+                    lines.append(issue.suggestion)
+                warn_list.addItem('\n'.join(lines))
+            layout.addWidget(warn_list)
+
+        return panel
+
+    def _on_summary_item_activated(
+            self, item: QtWidgets.QListWidgetItem) -> None:
+        # Step 5 (A): summary rows for stages carry their stage name in
+        # UserRole; activating one opens that stage tab (and checks its
+        # button) by reusing the normal click handler. The "Other" row has
+        # no stage name, so it stays inert.
+        stage = item.data(QtCore.Qt.UserRole)
+        if stage in self._stage_errors:
+            self._on_button_clicked(stage)
+
+    # ---- C2J tool (standalone C -> cfg_t JSON converter) ---------------- #
+    def _on_c2j_clicked(self) -> None:
+        self._capture_active_section()
+        for i in range(self.buttons_layout.count()):
+            w = self.buttons_layout.itemAt(i).widget()
+            if isinstance(w, QtWidgets.QPushButton):
+                w.setChecked(False)
+        self._active_label = ''
+        self._set_content(self._make_c2j_panel())
+
+    def _make_c2j_panel(self) -> QtWidgets.QWidget:
+        """Standalone converter: pick a .c/.h file, parse its
+        typedef struct / enum / #define into the cfg_t schema shape, let the
+        user tune scalar extension attributes (min/max/step/unit/tip/value),
+        then export one .json for the whole file.
+
+        Intentionally isolated from the pipeline: it never reads or writes
+        self._raw_data / self.registry, so it cannot disturb the main flow.
+        """
+        panel = QtWidgets.QWidget()
+        layout = QtWidgets.QVBoxLayout(panel)
+        layout.setContentsMargins(8, 8, 8, 8)
+        layout.setSpacing(8)
+
+        header = QtWidgets.QLabel('C \u2192 JSON \u8f6c\u6362')
+        header.setStyleSheet('font-weight: bold; font-size: 14px;')
+        layout.addWidget(header)
+
+        pick_row = QtWidgets.QHBoxLayout()
+        pick_btn = QtWidgets.QPushButton('\u9009\u62e9 .c / .h \u6587\u4ef6\u2026')
+        pick_btn.clicked.connect(self._c2j_pick_file)
+        self._c2j_path_label = QtWidgets.QLabel(self._c2j_path or '\uff08\u672a\u9009\u62e9\u6587\u4ef6\uff09')
+        self._c2j_path_label.setWordWrap(True)
+        pick_row.addWidget(pick_btn)
+        pick_row.addWidget(self._c2j_path_label, 1)
+        layout.addLayout(pick_row)
+
+        layout.addWidget(self._make_separator())
+
+        # Field-edit table for scalar extension attributes. Populated by
+        # _c2j_load_file(); empty until a file is parsed.
+        self._c2j_table = QtWidgets.QTableWidget()
+        self._c2j_table.setColumnCount(8)
+        self._c2j_table.setHorizontalHeaderLabels(
+            ['struct', 'name', 'type', 'value', 'min', 'max', 'step', 'unit/tip'])
+        self._c2j_table.verticalHeader().setVisible(False)
+        # Match the array tables' grid and force an explicit header divider:
+        # when the table has no rows yet, some themes draw the header's bottom
+        # edge too faintly to see, so paint it via the section style.
+        self._c2j_table.setShowGrid(True)
+        self._c2j_table.setGridStyle(QtCore.Qt.SolidLine)
+        c2j_header = self._c2j_table.horizontalHeader()
+        c2j_header.setHighlightSections(False)
+        c2j_header.setStyleSheet(
+            'QHeaderView::section{border:0px;border-bottom:1px solid #b0b0b0;'
+            'border-right:1px solid #d0d0d0;}')
+        # Empty / narrow content: stretch columns to fill the page (no
+        # horizontal scrollbar). _c2j_fit_columns() switches to per-content
+        # widths once a file is loaded and the content is wider than the view.
+        c2j_header.setSectionResizeMode(QtWidgets.QHeaderView.Stretch)
+        layout.addWidget(self._c2j_table, 1)
+
+        self._c2j_warn_list = QtWidgets.QListWidget()
+        self._c2j_warn_list.setWordWrap(True)
+        self._c2j_warn_list.setMaximumHeight(120)
+        layout.addWidget(self._c2j_warn_list)
+
+        export_row = QtWidgets.QHBoxLayout()
+        export_row.addStretch(1)
+        self._c2j_export_btn = QtWidgets.QPushButton('\u5bfc\u51fa JSON\u2026')
+        self._c2j_export_btn.setEnabled(False)
+        self._c2j_export_btn.clicked.connect(self._c2j_export)
+        export_row.addWidget(self._c2j_export_btn)
+        layout.addLayout(export_row)
+
+        # Reparse the previously picked file so reopening the panel restores
+        # the table instead of showing it empty.
+        if self._c2j_path and os.path.isfile(self._c2j_path):
+            self._c2j_load_file(self._c2j_path)
+        return panel
+
+    def _c2j_pick_file(self) -> None:
+        start = os.path.dirname(self._c2j_path) if self._c2j_path else self.struct_dir
+        path, _ = QtWidgets.QFileDialog.getOpenFileName(
+            self, 'Select C source', start, 'C source (*.c *.h);;All files (*)')
+        if not path:
+            return
+        self._c2j_path = path
+        self._c2j_path_label.setText(path)
+        self._c2j_load_file(path)
+
+    def _c2j_load_file(self, path: str) -> None:
+        try:
+            with open(path, 'r', encoding='utf-8') as f:
+                text = f.read()
+        except OSError as e:
+            QtWidgets.QMessageBox.warning(self, 'C2J', f'cannot read file: {e}')
+            return
+
+        result = parse_c_source(text)
+        self._c2j_result = result
+
+        # One table row per scalar field across all parsed structs. Only
+        # scalars get editable extension attributes; enum / struct / array
+        # members are shown read-only (greyed) so the user sees the full shape
+        # but cannot type meaningless ranges into them.
+        rows: List[tuple] = []
+        for sname, block in result.schema.items():
+            if block.get('type') != 'struct':
+                continue
+            for field in block.get('items', []):
+                is_scalar = (
+                    'count' not in field
+                    and field['type'] not in result.schema
+                    and field['type'] != 'char'
+                )
+                rows.append((sname, field, is_scalar))
+
+        table = self._c2j_table
+        table.setRowCount(len(rows))
+        self._c2j_rows = rows
+        for r, (sname, field, is_scalar) in enumerate(rows):
+            self._c2j_set_ro(table, r, 0, sname)
+            self._c2j_set_ro(table, r, 1, field['name'])
+            self._c2j_set_ro(table, r, 2, field['type'])
+            if is_scalar:
+                for c in (3, 4, 5, 6, 7):
+                    table.setItem(r, c, QtWidgets.QTableWidgetItem(''))
+            else:
+                for c in (3, 4, 5, 6, 7):
+                    self._c2j_set_ro(table, r, c, '')
+        self._c2j_fit_columns()
+
+        self._c2j_warn_list.clear()
+        for w in result.warnings:
+            self._c2j_warn_list.addItem(w)
+
+        self._c2j_export_btn.setEnabled(result.has_content)
+
+    def _c2j_fit_columns(self) -> None:
+        """Pick a column-sizing strategy based on content width:
+
+          - content fits the viewport  -> Stretch (fill page, no scrollbar)
+          - content wider than viewport -> Interactive at content widths,
+            letting the horizontal scrollbar appear.
+        """
+        table = self._c2j_table
+        header = table.horizontalHeader()
+        header.setSectionResizeMode(QtWidgets.QHeaderView.ResizeToContents)
+        natural = sum(header.sectionSize(c) for c in range(table.columnCount()))
+        avail = table.viewport().width()
+        if avail <= 0 or natural <= avail:
+            header.setSectionResizeMode(QtWidgets.QHeaderView.Stretch)
+        else:
+            widths = [header.sectionSize(c) for c in range(table.columnCount())]
+            header.setSectionResizeMode(QtWidgets.QHeaderView.Interactive)
+            for c, w in enumerate(widths):
+                table.setColumnWidth(c, w)
+
+    @staticmethod
+    def _c2j_set_ro(table: QtWidgets.QTableWidget, row: int, col: int,
+                    text: str) -> None:
+        item = QtWidgets.QTableWidgetItem(text)
+        item.setFlags(item.flags() & ~QtCore.Qt.ItemIsEditable)
+        item.setForeground(QtGui.QColor('#666'))
+        table.setItem(row, col, item)
+
+    @staticmethod
+    def _c2j_parse_num(text: str):
+        text = (text or '').strip()
+        if not text:
+            return None
+        try:
+            return int(text)
+        except ValueError:
+            pass
+        try:
+            return float(text)
+        except ValueError:
+            return text
+
+    def _c2j_apply_edits(self) -> None:
+        """Fold the table's scalar-attribute edits back into the parsed field
+        dicts so the exported JSON carries them."""
+        table = self._c2j_table
+        for r, (_sname, field, is_scalar) in enumerate(self._c2j_rows):
+            if not is_scalar:
+                continue
+            value = self._c2j_parse_num(self._c2j_cell(table, r, 3))
+            vmin = self._c2j_parse_num(self._c2j_cell(table, r, 4))
+            vmax = self._c2j_parse_num(self._c2j_cell(table, r, 5))
+            step = self._c2j_parse_num(self._c2j_cell(table, r, 6))
+            unit = (self._c2j_cell(table, r, 7) or '').strip()
+            for key in ('value', 'min', 'max', 'step', 'unit', 'tip'):
+                field.pop(key, None)
+            if value is not None:
+                field['value'] = value
+            if vmin is not None:
+                field['min'] = vmin
+            if vmax is not None:
+                field['max'] = vmax
+            if step is not None:
+                field['step'] = step
+            if unit:
+                field['unit'] = unit
+
+    @staticmethod
+    def _c2j_cell(table: QtWidgets.QTableWidget, row: int, col: int) -> str:
+        item = table.item(row, col)
+        return item.text() if item is not None else ''
+
+    def _c2j_export(self) -> None:
+        if not getattr(self, '_c2j_result', None) or not self._c2j_result.has_content:
+            return
+        self._c2j_apply_edits()
+        out = build_schema_dict(self._c2j_result)
+
+        base = os.path.splitext(os.path.basename(self._c2j_path))[0]
+        default = os.path.join(self.struct_dir, base + '.json')
+        path, _ = QtWidgets.QFileDialog.getSaveFileName(
+            self, 'Export JSON', default, 'JSON (*.json);;All files (*)')
+        if not path:
+            return
+        try:
+            with open(path, 'w', encoding='utf-8') as f:
+                f.write(dumps_json(out))
+        except OSError as e:
+            QtWidgets.QMessageBox.warning(self, 'C2J', f'cannot write file: {e}')
+            return
+        QtWidgets.QMessageBox.information(self, 'C2J', f'\u5df2\u5bfc\u51fa\uff1a{path}')
+
+    # ---- settings panel (placeholder, reserved for future options) ------ #
+    def _on_settings_clicked(self) -> None:
+        self._capture_active_section()
+        for i in range(self.buttons_layout.count()):
+            w = self.buttons_layout.itemAt(i).widget()
+            if isinstance(w, QtWidgets.QPushButton):
+                w.setChecked(False)
+        self._active_label = ''
+        self._set_content(self._make_settings_panel())
+
+    def _make_settings_panel(self) -> QtWidgets.QWidget:
+        """Reserved settings page. No options yet; kept as an extension point
+        so future global preferences land here without touching the button
+        wiring again."""
+        panel = QtWidgets.QWidget()
+        layout = QtWidgets.QVBoxLayout(panel)
+        layout.setContentsMargins(8, 8, 8, 8)
+        layout.setSpacing(8)
+
+        header = QtWidgets.QLabel('Settings')
+        header.setStyleSheet('font-weight: bold; font-size: 14px;')
+        layout.addWidget(header)
+
+        placeholder = QtWidgets.QLabel('\u6682\u65e0\u8bbe\u7f6e\u9879\u3002')
+        placeholder.setStyleSheet('color: #666;')
+        layout.addWidget(placeholder)
+        layout.addStretch(1)
+        return panel
+
+    # ---- report panel (config issues + ELF layout verification) --------- #
+    def _on_report_clicked(self) -> None:
+        self._capture_active_section()
+        self._show_report()
+
+    def _show_report(self) -> None:
+        for i in range(self.buttons_layout.count()):
+            w = self.buttons_layout.itemAt(i).widget()
+            if isinstance(w, QtWidgets.QPushButton):
+                w.setChecked(False)
+        self._active_label = ''
+        self._set_content(self._make_report_panel())
+
+    def _make_report_panel(self) -> QtWidgets.QWidget:
+        """Unified overview: configuration load issues (cfg_t + pipeline)
+        followed by ELF layout verification results. Always renders, showing
+        an all-clear line for each section that has no problems.
+        """
+        panel = QtWidgets.QWidget()
+        layout = QtWidgets.QVBoxLayout(panel)
+        layout.setContentsMargins(8, 8, 8, 8)
+        layout.setSpacing(8)
+
+        report = self.registry.report
+        if report.has_errors or report.has_warnings:
+            layout.addWidget(self._make_summary_panel())
+        else:
+            ok = QtWidgets.QLabel('Configuration: no issues')
+            ok.setStyleSheet('font-weight: bold; color: #1b7f3b;')
+            layout.addWidget(ok)
+
+        layout.addWidget(self._make_separator())
+        layout.addWidget(self._make_elf_section())
+        layout.addStretch(1)
+        return panel
+
+    def _make_elf_section(self) -> QtWidgets.QWidget:
+        box = QtWidgets.QWidget()
+        layout = QtWidgets.QVBoxLayout(box)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(6)
+
+        title = QtWidgets.QLabel('ELF layout verification')
+        title.setStyleSheet('font-weight: bold; font-size: 14px;')
+        layout.addWidget(title)
+
+        if not self.elf_path:
+            note = QtWidgets.QLabel(
+                'No ELF selected - layout verification is off. '
+                'Pick an ELF to enable strict layout checks.')
+            note.setWordWrap(True)
+            note.setStyleSheet('color: #666;')
+            layout.addWidget(note)
+            return box
+
+        src = QtWidgets.QLabel(f'ELF: {self.elf_path}')
+        src.setWordWrap(True)
+        src.setStyleSheet('color: #666;')
+        layout.addWidget(src)
+
+        rep = self._elf_report
+        if rep is None or (not rep.has_errors and not rep.has_warnings):
+            ok = QtWidgets.QLabel('Layout matches the ELF (no issues)')
+            ok.setStyleSheet('font-weight: bold; color: #1b7f3b;')
+            layout.addWidget(ok)
+            return box
+
+        if rep.has_errors:
+            err_label = QtWidgets.QLabel(f'Errors: {len(rep.errors)}')
+            err_label.setStyleSheet('font-weight: bold; color: #b00020;')
+            layout.addWidget(err_label)
+            err_list = QtWidgets.QListWidget()
+            err_list.setWordWrap(True)
+            for issue in rep.errors:
+                lines = [f'{issue.file}']
+                if issue.path:
+                    lines.append(f'at {issue.path}')
+                lines.append(issue.message)
+                if issue.suggestion:
+                    lines.append(issue.suggestion)
+                err_list.addItem('\n'.join(lines))
+            layout.addWidget(err_list)
+
+        if rep.has_warnings:
+            warn_label = QtWidgets.QLabel(f'Warnings: {len(rep.warnings)}')
+            warn_label.setStyleSheet('font-weight: bold; color: #a05a00;')
+            layout.addWidget(warn_label)
+            warn_list = QtWidgets.QListWidget()
+            warn_list.setWordWrap(True)
+            for issue in rep.warnings:
+                lines = []
+                if issue.path:
+                    lines.append(f'at {issue.path}')
+                lines.append(issue.message)
+                if issue.suggestion:
+                    lines.append(issue.suggestion)
+                warn_list.addItem('\n'.join(lines))
+            layout.addWidget(warn_list)
+
+        return box
+
+    def _set_content(self, widget: QtWidgets.QWidget) -> None:
+        old = self._content_widget
+        self.content_area.takeWidget()
+        if old is not None:
+            old.deleteLater()
+        self._content_widget = widget
+        self.content_area.setWidget(widget)