python-hwpx 3.1.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

hwpx/agent/commands.py

@@ -21,7 +21,7 @@ from pathlib import Path
 from typing import Any
 from xml.etree import ElementTree as ET
 
-from lxml import etree as LET
+from lxml import etree as LET  # type: ignore[reportAttributeAccessIssue]  # lxml has no complete bundled typing
 
 from hwpx.document import HwpxDocument
 from hwpx.oxml import HwpxOxmlTable
@@ -38,6 +38,12 @@ from .model import (
     validate_agent_batch,
 )
 from .path import parse_path
+from .story import (
+    HEADER_STORY_EDITABLE_PROPERTIES,
+    HEADER_STORY_KIND,
+    HeaderStoryBinding,
+    try_parse_header_story_path,
+)
 
 _EMPTY_REVISION = "sha256:" + hashlib.sha256(b"").hexdigest()
 _HWP_UNITS_PER_MM = 7200 / 25.4
@@ -242,6 +248,21 @@ def _validate_property_values(kind: str, properties: Mapping[str, Any], *, creat
             raise AgentContractError("unknown_property", f"untyped property: {target}", target=target)
 
 
+def _validate_header_story_properties(properties: Mapping[str, Any]) -> None:
+    unknown = sorted(set(properties) - HEADER_STORY_EDITABLE_PROPERTIES)
+    if unknown:
+        raise AgentContractError(
+            "unknown_property",
+            f"header does not support properties: {unknown}",
+            target=f"header.{unknown[0]}",
+        )
+    if "text" not in properties:
+        raise AgentContractError(
+            "invalid_syntax", "existing header set requires text", target="header.text"
+        )
+    _require_string(properties["text"], "header.text")
+
+
 def _preflight(batch: Mapping[str, Any]) -> None:
     """Reject the complete static command matrix before the first mutation."""
 
@@ -254,6 +275,9 @@ def _preflight(batch: Mapping[str, Any]) -> None:
                 return alias_kinds[command_id][field]
             except KeyError as exc:  # validate_agent_batch already checks ordering
                 raise AgentContractError("not_found", f"unknown command alias: {value}") from exc
+        story = try_parse_header_story_path(value)
+        if story is not None:
+            return story.kind
         parsed = parse_path(value)
         return parsed.segments[-1].kind if parsed.segments else "document"
 
@@ -264,6 +288,9 @@ def _preflight(batch: Mapping[str, Any]) -> None:
                 return alias_kinds[command_id]["parentPath" if field == "path" else field]
             except KeyError:
                 return "document"
+        story = try_parse_header_story_path(value)
+        if story is not None:
+            return "section"
         parsed = parse_path(value)
         return parsed.segments[-2].kind if len(parsed.segments) > 1 else "document"
 
@@ -298,6 +325,19 @@ def _preflight(batch: Mapping[str, Any]) -> None:
             }
             continue
         source_kind = reference_kind(command["path"])
+        if source_kind == HEADER_STORY_KIND:
+            if op != "set":
+                raise AgentContractError(
+                    "unsupported_operation",
+                    f"{op} is unsupported for {source_kind}",
+                    target=command["commandId"],
+                )
+            _validate_header_story_properties(command["properties"])
+            alias_kinds[command["commandId"]] = {
+                "path": source_kind,
+                "parentPath": "section",
+            }
+            continue
         if op not in NODE_PROPERTY_CATALOG_V1[source_kind]["operations"]:
             raise AgentContractError(
                 "unsupported_operation",
@@ -309,11 +349,11 @@ def _preflight(batch: Mapping[str, Any]) -> None:
         destination_kind = parent_kind(command["path"])
         if op in {"move", "copy"}:
             destination_kind = reference_kind(command["parent"])
-            expected_parent = _MOVE_COPY_PARENTS.get(source_kind)
-            if destination_kind != expected_parent:
+            move_parent = _MOVE_COPY_PARENTS.get(source_kind)
+            if destination_kind != move_parent:
                 raise AgentContractError(
                     "incompatible_parent",
-                    f"{source_kind} requires a {expected_parent} parent, not {destination_kind}",
+                    f"{source_kind} requires a {move_parent} parent, not {destination_kind}",
                     target=command["commandId"],
                 )
         alias_kinds[command["commandId"]] = {
@@ -570,6 +610,42 @@ def _mark_containing_section(document: HwpxDocument, target: Any) -> None:
     raise AgentContractError("not_found", "mutated element is detached")
 
 
+def _apply_header_story_set(
+    binding: HeaderStoryBinding, properties: Mapping[str, Any]
+) -> dict[str, Any]:
+    """Apply the bounded existing-header mutation through its OXML owner."""
+
+    _validate_header_story_properties(properties)
+    try:
+        binding.native.set_simple_text_preserving(properties["text"])
+    except AgentContractError:
+        raise
+    except ValueError as exc:
+        # The OXML owner uses ValueError for rich/control-bearing or otherwise
+        # structurally unsafe headers.  Do not let it degrade to the generic
+        # invariant envelope or fall back to the destructive whole-story setter.
+        message = str(exc) or "header content cannot be edited losslessly"
+        lowered = message.lower()
+        code = (
+            "ambiguous_target"
+            if "ambiguous" in lowered
+            else "not_found"
+            if "not found" in lowered
+            else "unsupported_content"
+        )
+        raise AgentContractError(
+            code,
+            message,
+            target=binding.path,
+        ) from exc
+    return {
+        "text": {
+            "before": binding.text,
+            "after": properties["text"],
+        }
+    }
+
+
 def _apply_set(document: HwpxDocument, record: NodeRecord, properties: Mapping[str, Any]) -> dict[str, Any]:
     _ensure_operation(record, "set")
     _validate_property_values(record.kind, properties, creating=False)
@@ -711,7 +787,10 @@ def _add(
         if "pageHeightMm" in properties:
             size_kwargs["height"] = round(properties["pageHeightMm"] * _HWP_UNITS_PER_MM)
         if size_kwargs:
-            created.properties.set_page_size(**size_kwargs)
+            created.properties.set_page_size(
+                width=size_kwargs.get("width"),
+                height=size_kwargs.get("height"),
+            )
         return created
     if kind == "paragraph":
         created = parent.native.add_paragraph(str(properties.get("text", "")))
@@ -1081,6 +1160,47 @@ def _member_diff(before: bytes, after: bytes) -> dict[str, Any]:
         return {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
 
 
+def _verify_header_story_candidates(
+    candidate_data: bytes,
+    candidate_revision: str,
+    expectations: Mapping[str, Mapping[str, str]],
+) -> dict[str, Any]:
+    receipts: list[dict[str, Any]] = []
+    if expectations:
+        with HwpxDocument.open(candidate_data) as reopened:
+            view = HwpxAgentDocument.from_document(
+                reopened, revision=candidate_revision
+            )
+            for expectation in expectations.values():
+                path = expectation["path"]
+                binding = view._resolve_header_story(path)
+                if (
+                    binding.stable_id != expectation["stableId"]
+                    or binding.page_type != expectation["pageType"]
+                    or binding.text != expectation["text"]
+                ):
+                    raise AgentContractError(
+                        "verification_failed",
+                        "reopened header story does not match the committed binding",
+                        target=path,
+                    )
+                receipts.append(
+                    {
+                        "commandId": expectation["commandId"],
+                        "path": binding.path,
+                        "stableId": binding.stable_id,
+                        "pageType": binding.page_type,
+                        "textMatched": True,
+                    }
+                )
+    return {
+        "schemaVersion": "hwpx.agent-story-preservation/v1",
+        "ok": True,
+        "storyCount": len(receipts),
+        "stories": receipts,
+    }
+
+
 def _request_hash(batch: Mapping[str, Any]) -> str:
     payload = json.dumps(
         batch,
@@ -1192,6 +1312,7 @@ def apply_document_commands(
         aliases: dict[str, dict[str, str]] = {}
         identity_changes: list[Mapping[str, str]] = []
         semantic_changes: list[Mapping[str, Any]] = []
+        story_expectations: dict[str, Mapping[str, str]] = {}
         _call_fault(fault_injector, "before_open")
         with HwpxDocument.open(input_data) as document:
             view = HwpxAgentDocument.from_document(document, revision=input_revision)
@@ -1203,11 +1324,24 @@ def apply_document_commands(
                 parent_path: str | None = None
                 changed: dict[str, Any] = {}
                 generated: list[dict[str, str]] = []
+                target_native: Any | None = None
+                story_before: HeaderStoryBinding | None = None
                 if op == "set":
                     resolved_path = _resolve_alias(command["path"], aliases)
-                    record = view.resolve_record(resolved_path, expected_revision=input_revision)
-                    changed = _apply_set(document, record, command["properties"])
-                    target_native = record.native
+                    story_path = try_parse_header_story_path(resolved_path)
+                    if story_path is not None:
+                        story_before = view._resolve_header_story(
+                            story_path, expected_revision=input_revision
+                        )
+                        changed = _apply_header_story_set(
+                            story_before, command["properties"]
+                        )
+                    else:
+                        record = view.resolve_record(
+                            resolved_path, expected_revision=input_revision
+                        )
+                        changed = _apply_set(document, record, command["properties"])
+                        target_native = record.native
                 elif op == "add":
                     parent_path = _resolve_alias(command["parent"], aliases)
                     parent = view.resolve_record(parent_path, expected_revision=input_revision)
@@ -1244,7 +1378,26 @@ def apply_document_commands(
 
                 _call_fault(fault_injector, "after_command", index)
                 view = HwpxAgentDocument.from_document(document, revision=input_revision)
-                if op == "set" and resolved_path is not None:
+                result_stable_id: str | None = None
+                if story_before is not None and resolved_path is not None:
+                    target_story = view._resolve_header_story(resolved_path)
+                    if target_story.stable_id != story_before.stable_id:
+                        raise AgentContractError(
+                            "invariant_violation",
+                            "header story identity changed during text edit",
+                            target=resolved_path,
+                        )
+                    result_path = target_story.path
+                    result_parent = target_story.parent_path
+                    result_stable_id = target_story.stable_id
+                    story_expectations[target_story.binding_key] = {
+                        "commandId": command_id,
+                        "path": target_story.path,
+                        "stableId": target_story.stable_id,
+                        "pageType": target_story.page_type,
+                        "text": command["properties"]["text"],
+                    }
+                elif op == "set" and resolved_path is not None:
                     # Some native bindings (notably form fields) are request-local
                     # match dictionaries.  A property edit is non-structural, so
                     # its canonical path is the durable post-edit lookup key.
@@ -1269,6 +1422,11 @@ def apply_document_commands(
                     "generatedIdentities": generated,
                     "warnings": [],
                 }
+                if result_stable_id is not None:
+                    # Command results are already an untyped JSON mapping.  This
+                    # story-only receipt carries the actual stable identity
+                    # without changing AgentBatchResult or the ToolSpec schema.
+                    result["stableId"] = result_stable_id
                 command_results.append(result)
                 semantic_changes.append(
                     {
@@ -1285,6 +1443,12 @@ def apply_document_commands(
             _call_fault(fault_injector, "after_serialize")
 
             candidate_revision = _revision(candidate_data)
+            if story_expectations:
+                verification["storyPreservation"] = _verify_header_story_candidates(
+                    candidate_data,
+                    candidate_revision,
+                    story_expectations,
+                )
             semantic_diff = {
                 "schemaVersion": "hwpx.agent-semantic-diff/v1",
                 "inputRevision": input_revision,

hwpx/agent/document.py

@@ -8,7 +8,7 @@ from collections import Counter, defaultdict
 from dataclasses import dataclass, field
 from os import PathLike
 from pathlib import Path
-from typing import Any
+from typing import Any, Sequence, cast
 
 from hwpx.document import HwpxDocument
 from hwpx.oxml import HwpxOxmlShape
@@ -22,7 +22,14 @@ from .model import (
     NODE_PROPERTY_CATALOG_V1,
 )
 from .path import SemanticPath, canonicalize_path, identified_segment, indexed_segment
+from .query import QueryRecord as _QueryRecord
 from .query import QueryResult, evaluate_selector, parse_selector
+from .story import (
+    HeaderStoryBinding,
+    HeaderStoryPath,
+    parse_header_story_path,
+    resolve_header_story,
+)
 
 _HWP_UNITS_PER_MM = 7200 / 25.4
 _SHAPE_KINDS = frozenset({"line", "rect", "ellipse", "arc", "polygon", "curve", "connectLine"})
@@ -129,7 +136,7 @@ class HwpxAgentDocument:
     def __enter__(self) -> "HwpxAgentDocument":
         return self
 
-    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:  # type: ignore[exit-return]  # frozen public signature
         self.close()
         return False
 
@@ -689,6 +696,25 @@ class HwpxAgentDocument:
             raise AgentContractError("volatile_target", "target has a positional path", target=canonical)
         return record
 
+    def _resolve_header_story(
+        self,
+        path: str | HeaderStoryPath,
+        *,
+        expected_revision: str | None = None,
+    ) -> HeaderStoryBinding:
+        """Resolve the private command-only existing-header seam.
+
+        Header stories deliberately remain absent from ``records``, ``get``,
+        and ``query`` so the frozen public projection/catalog does not drift.
+        """
+
+        parsed = parse_header_story_path(path) if isinstance(path, str) else path
+        if expected_revision is not None and expected_revision != self.revision:
+            raise AgentContractError(
+                "stale_revision", "document revision does not match", target=parsed.canonical
+            )
+        return resolve_header_story(self.document, parsed)
+
     def _public_node(self, record: NodeRecord, *, depth: int, child_limit: int) -> AgentNode:
         supported_total = len(record.child_paths)
         selected_paths = record.child_paths[:child_limit] if depth > 0 else []
@@ -751,7 +777,8 @@ class HwpxAgentDocument:
         if expected_revision is not None and expected_revision != self.revision:
             raise AgentContractError("stale_revision", "document revision does not match", target="selector")
         parsed = parse_selector(selector)
-        matches, truncated = evaluate_selector(self.records, parsed, limit=limit)
+        query_records = cast(Sequence[_QueryRecord], self.records)
+        matches, truncated = evaluate_selector(query_records, parsed, limit=limit)
         if not 0 <= node_depth <= MAX_VIEW_DEPTH:
             raise AgentContractError("resource_limit", "nodeDepth is out of bounds", target="nodeDepth")
         if not 1 <= child_limit <= MAX_CHILDREN_PER_NODE:
@@ -760,7 +787,12 @@ class HwpxAgentDocument:
             selector=selector,
             revision=self.revision,
             nodes=tuple(
-                self._public_node(record, depth=node_depth, child_limit=child_limit) for record in matches
+                self._public_node(
+                    cast(NodeRecord, record),
+                    depth=node_depth,
+                    child_limit=child_limit,
+                )
+                for record in matches
             ),
             truncated=truncated,
         )

hwpx/agent/story.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Private, contract-neutral bindings for existing non-body stories.
+
+The public semantic path grammar intentionally remains frozen at the Feature
+024 catalog.  This module recognizes one narrower command-only seam: an
+existing section header selected by its native id or page type.  It does not
+project headers into the public view, accept package paths, or expose XML.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from .model import AgentContractError
+from .path import MAX_PATH_CHARS
+
+HEADER_STORY_KIND = "header"
+HEADER_STORY_EDITABLE_PROPERTIES = frozenset({"text"})
+HEADER_PAGE_TYPES = frozenset({"BOTH", "EVEN", "ODD"})
+
+_HEADER_STORY_RE = re.compile(
+    r"^/section\[(?P<section>0*[1-9][0-9]*)\]/header\["
+    r"@(?P<attribute>id|page-type)=(?P<value>\"(?:[^\"\\]|\\.)*\")\]$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class HeaderStoryPath:
+    """Parsed command-only path for one existing section header."""
+
+    section_index: int
+    attribute: str
+    value: str
+
+    @property
+    def kind(self) -> str:
+        return HEADER_STORY_KIND
+
+    @property
+    def canonical(self) -> str:
+        value = json.dumps(self.value, ensure_ascii=False, separators=(",", ":"))
+        return (
+            f"/section[{self.section_index}]/"
+            f"header[@{self.attribute}={value}]"
+        )
+
+    @property
+    def parent_path(self) -> str:
+        return f"/section[{self.section_index}]"
+
+
+@dataclass(frozen=True, slots=True)
+class HeaderStoryBinding:
+    """Request-local native binding for an existing logical header."""
+
+    path: str
+    parent_path: str
+    stable_id: str
+    native_id: str
+    page_type: str
+    section_index: int
+    native: Any
+    text: str
+
+    @property
+    def kind(self) -> str:
+        return HEADER_STORY_KIND
+
+    @property
+    def binding_key(self) -> str:
+        # Native ids are not promised to be document-global.  Section scope is
+        # part of the logical binding even though the receipt exposes the same
+        # kind:id stable-id convention used by projected semantic nodes.
+        return f"{self.section_index}:{self.native_id}"
+
+
+def try_parse_header_story_path(value: object) -> HeaderStoryPath | None:
+    """Return a private header path, or ``None`` for the public path parser.
+
+    Only exact supported forms are intercepted.  Unsupported forms such as
+    ``header[1]`` deliberately continue through :func:`parse_path` and retain
+    the frozen ``unknown_kind`` behavior.
+    """
+
+    if not isinstance(value, str) or "/header[@" not in value:
+        return None
+    if len(value) > MAX_PATH_CHARS:
+        raise AgentContractError("resource_limit", "path is too long", target="path")
+    match = _HEADER_STORY_RE.fullmatch(value)
+    if match is None:
+        return None
+    try:
+        decoded = json.loads(match.group("value"))
+    except (TypeError, ValueError, json.JSONDecodeError) as exc:
+        raise AgentContractError(
+            "invalid_syntax", "invalid header story path string", target="path"
+        ) from exc
+    if not isinstance(decoded, str) or not decoded or len(decoded) > 256:
+        raise AgentContractError(
+            "resource_limit", "header story selector is invalid", target="path"
+        )
+    attribute = match.group("attribute")
+    if attribute == "page-type" and decoded not in HEADER_PAGE_TYPES:
+        raise AgentContractError(
+            "invalid_syntax",
+            "header page type must be BOTH, EVEN, or ODD",
+            target="path",
+        )
+    return HeaderStoryPath(
+        section_index=int(match.group("section")),
+        attribute=attribute,
+        value=decoded,
+    )
+
+
+def parse_header_story_path(value: str) -> HeaderStoryPath:
+    """Parse an exact private header path for focused internal tests."""
+
+    parsed = try_parse_header_story_path(value)
+    if parsed is None:
+        raise AgentContractError(
+            "invalid_syntax", "unsupported header story path", target="path"
+        )
+    return parsed
+
+
+def resolve_header_story(document: Any, path: HeaderStoryPath) -> HeaderStoryBinding:
+    """Resolve one unique direct logical header without scanning descendants."""
+
+    try:
+        sections = document.sections
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "document section structure is unavailable", target=path.canonical
+        ) from exc
+    if path.section_index > len(sections):
+        raise AgentContractError(
+            "not_found", "header story section does not exist", target=path.canonical
+        )
+    section = sections[path.section_index - 1]
+    try:
+        headers = tuple(section.properties.headers)
+        if path.attribute == "id":
+            matches = [header for header in headers if header.id == path.value]
+        else:
+            matches = [
+                header for header in headers if header.apply_page_type == path.value
+            ]
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "section header structure is invalid", target=path.canonical
+        ) from exc
+
+    if not matches:
+        raise AgentContractError(
+            "not_found", f"existing header story not found: {path.canonical}", target=path.canonical
+        )
+    if len(matches) > 1:
+        raise AgentContractError(
+            "ambiguous_target",
+            f"header story selector is not unique: {path.canonical}",
+            target=path.canonical,
+        )
+
+    header = matches[0]
+    try:
+        native_id = header.id
+        page_type = header.apply_page_type
+        text = header.text
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise AgentContractError(
+            "unsupported_content", "header story cannot be read safely", target=path.canonical
+        ) from exc
+    if not native_id or len(native_id) > 256:
+        raise AgentContractError(
+            "unsupported_content", "header story has no bounded native identity", target=path.canonical
+        )
+    if page_type not in HEADER_PAGE_TYPES:
+        raise AgentContractError(
+            "unsupported_content", "header story has an unsupported page type", target=path.canonical
+        )
+
+    return HeaderStoryBinding(
+        path=path.canonical,
+        parent_path=path.parent_path,
+        stable_id=f"header:{native_id}",
+        native_id=native_id,
+        page_type=page_type,
+        section_index=path.section_index,
+        native=header,
+        text=text,
+    )
+
+
+__all__ = [
+    "HEADER_PAGE_TYPES",
+    "HEADER_STORY_EDITABLE_PROPERTIES",
+    "HEADER_STORY_KIND",
+    "HeaderStoryBinding",
+    "HeaderStoryPath",
+    "parse_header_story_path",
+    "resolve_header_story",
+    "try_parse_header_story_path",
+]

hwpx/document.py

@@ -13,7 +13,7 @@ import uuid
 
 from os import PathLike
 from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, Any, BinaryIO, Iterator, Mapping, Sequence, overload
+from typing import TYPE_CHECKING, Any, BinaryIO, Iterator, Mapping, Sequence, cast, overload
 
 
 from .oxml import (
@@ -65,7 +65,12 @@ if TYPE_CHECKING:
     from .form_fit.policy import FitPolicy
     from .form_fit.report import FitResult
     from .tools.validator import ValidationReport
-    from .tools.table_navigation import TableFillResult, TableLabelSearchResult, TableMapResult
+    from .tools.table_navigation import (
+        SearchDirection,
+        TableFillResult,
+        TableLabelSearchResult,
+        TableMapResult,
+    )
 
 
 def _append_element(
@@ -343,7 +348,9 @@ class HwpxDocument:
             stream = io.BytesIO(source)
             open_source = stream
             internal_resources.append(stream)
-        package = HwpxPackage.open(open_source)
+        # HwpxPackage/ZipFile accepts os.PathLike at runtime; its narrower
+        # compatibility annotation intentionally remains frozen.
+        package = HwpxPackage.open(cast(Any, open_source))
         root = HwpxOxmlDocument.from_package(package)
         return cls(package, root, managed_resources=tuple(internal_resources))
 
@@ -368,7 +375,7 @@ class HwpxDocument:
 
         return self
 
-    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:  # type: ignore[exit-return]  # frozen public signature
         """예외 발생 여부와 무관하게 내부 자원을 안전하게 정리합니다."""
 
         self.close()
@@ -1072,7 +1079,7 @@ class HwpxDocument:
             run_attributes=run_attributes,
             include_run=include_run,
             inherit_style=inherit_style,
-            **extra_attrs,
+            **cast(Any, extra_attrs),
         )
 
     def add_table(
@@ -1105,7 +1112,7 @@ class HwpxDocument:
             style_id_ref=style_id_ref,
             char_pr_id_ref=char_pr_id_ref,
             include_run=False,
-            **extra_attrs,
+            **cast(Any, extra_attrs),
         )
         return paragraph.add_table(
             rows,
@@ -1163,7 +1170,7 @@ class HwpxDocument:
             style_id_ref=style_id_ref,
             char_pr_id_ref=char_pr_id_ref,
             include_run=False,
-            **extra_attrs,
+            **cast(Any, extra_attrs),
         )
         return paragraph.add_picture(
             binary_item_id_ref,
@@ -1288,7 +1295,11 @@ class HwpxDocument:
 
         from .tools.table_navigation import find_cell_by_label
 
-        return find_cell_by_label(self, label_text, direction=direction)
+        return find_cell_by_label(
+            self,
+            label_text,
+            direction=cast("SearchDirection", direction),
+        )
 
     def _find_field_end_position(
         self,
@@ -1664,7 +1675,7 @@ class HwpxDocument:
         return FitEngine().fit(value, slot, fit_policy, field_id=field_id)
 
     def _font_pt_for_ref(self, char_pr_id_ref: object) -> float:
-        style = self.char_property(char_pr_id_ref)
+        style = self.char_property(cast(Any, char_pr_id_ref))
         if style is not None:
             height = style.attributes.get("height")
             if height:
@@ -1729,7 +1740,7 @@ class HwpxDocument:
             style_id_ref=style_id_ref,
             char_pr_id_ref=char_pr_id_ref,
             include_run=False,
-            **extra_attrs,
+            **cast(Any, extra_attrs),
         )
         return paragraph.add_shape(
             shape_type,
@@ -1761,7 +1772,7 @@ class HwpxDocument:
             style_id_ref=style_id_ref,
             char_pr_id_ref=char_pr_id_ref,
             include_run=False,
-            **extra_attrs,
+            **cast(Any, extra_attrs),
         )
         return paragraph.add_control(
             attributes=attributes,