feat(hangul): import, edit, and export HWP/HWPX

README.md

@@ -67,6 +67,7 @@ runtime.
 | React editor | `@contextualwisdomlab/cwl-editor` | Markdown/HTML WYSIWYG component and serializers |
 | Collaboration | `@contextualwisdomlab/cwl-editor/collaboration` | Provider-neutral Yjs collaborative editing |
 | Converter | `@contextualwisdomlab/cwl-editor/converter` | Framework-independent base64/data-URI utilities |
+| Hangul documents | `@contextualwisdomlab/cwl-editor/hangul` | Framework-independent HWP/HWPX import/export bridge with a host-injected engine |
 | Envelope identity | `@contextualwisdomlab/cwl-editor/envelope-identity` | Framework-independent bounded schema identity for host-owned migration routing |
 | Revision evidence | `@contextualwisdomlab/cwl-editor/revision-evidence` | Framework-independent canonical envelope, strong revision, and transition evidence |
 | Text-position selector | `@contextualwisdomlab/cwl-editor/text-position-selector` | React-free deterministic W3C `TextPositionSelector` projection core |

docs/HANGUL.md

@@ -0,0 +1,139 @@
+# HWP and HWPX authoring
+
+Inkspan's Hangul bridge opens HWP/HWPX bytes through a host-provided parser/serializer and projects supported content into the same TipTap/ProseMirror JSON edited by `CwlEditor`. HWPX is the recommended save target because it is the open XML/OWPML path standardized by KS X 6101; legacy HWP remains an explicit compatibility target when the selected engine supports it.
+
+## Authority boundary
+
+Inkspan owns:
+
+- the editable TipTap JSON projection;
+- deterministic conversion rules;
+- stable error semantics;
+- byte/resource limits;
+- explicit loss reporting;
+- deterministic public capability metadata for the bounded bridge.
+
+The host owns:
+
+- file pickers and drag/drop;
+- filesystem and object-storage access;
+- WASM or native-engine initialization;
+- passwords and protected-document UX;
+- publication/download behavior;
+- telemetry and persistence.
+
+The Hangul package never fetches external resources and never executes active content from a document.
+
+## Import flow
+
+```mermaid
+sequenceDiagram
+    participant Host
+    participant Bridge as Inkspan Hangul bridge
+    participant Engine as Host-provided HWP engine
+    participant Editor as CwlEditor
+
+    Host->>Bridge: openHangulDocument(bytes, { engine })
+    Bridge->>Engine: open(bytes)
+    Engine-->>Bridge: bounded document API
+    Bridge->>Engine: source format / sections / HTML projection
+    Bridge-->>Host: { documentJson, sourceFormat, warnings, lossy, capabilities }
+    Host->>Editor: setDocumentJson(documentJson)
+```
+
+The original bytes remain host-owned. Importing a file does not mutate it. The returned `capabilities` object is frozen, deterministic Inkspan metadata: it declares `importFormats`, `exportFormats`, `recommendedExportFormat`, and the currently round-trippable `supportedContent`. Hosts can use that metadata for UI and routing without probing the host engine or inferring support from failures.
+
+## Export flow
+
+```mermaid
+sequenceDiagram
+    participant Host
+    participant Editor as CwlEditor
+    participant Bridge as Inkspan Hangul bridge
+    participant Engine as Host-provided HWP engine
+
+    Host->>Editor: getDocumentJson()
+    Editor-->>Host: edited JSON
+    Host->>Bridge: exportHangulDocument(JSON, format)
+    Bridge->>Engine: create blank document
+    Bridge->>Engine: paste bounded deterministic HTML
+    Bridge->>Engine: exportHwpx() or exportHwp()
+    Engine-->>Bridge: bytes
+    Bridge-->>Host: { bytes, format, warnings }
+```
+
+## Minimal integration
+
+```ts
+import {
+  exportHangulDocument,
+  openHangulDocument,
+  type HangulDocumentEngine,
+} from '@contextualwisdomlab/cwl-editor/hangul';
+
+async function openIntoEditor(
+  source: Uint8Array,
+  engine: HangulDocumentEngine,
+  editor: { setDocumentJson(value: unknown): void },
+) {
+  const imported = await openHangulDocument(source, { engine });
+  editor.setDocumentJson(imported.documentJson);
+  return imported;
+}
+
+async function saveAsHwpx(
+  documentJson: Parameters<typeof exportHangulDocument>[0],
+  engine: HangulDocumentEngine,
+) {
+  return exportHangulDocument(documentJson, {
+    engine,
+    format: 'hwpx',
+  });
+}
+```
+
+## Compatibility contract
+
+The initial bridge deliberately supports a bounded semantic subset and rejects unsupported export nodes instead of silently deleting them. The compatibility matrix expands only when real HWP/HWPX fixtures demonstrate stable round-trip behavior. `capabilities.supportedContent` is the machine-consumable projection of the same currently implemented subset; this table remains the human-readable contract and limitation guide.
+
+Committed synthetic OWPML fixtures under `src/hangul/fixtures/` are the current known-document suite. `briefing-minutes.section.xml` must project to the expected heading, paragraph, and table cells when wrapped as HWPX or legacy HWP. `unsupported-shape.section.xml` must fail closed; Inkspan does not keep surrounding paragraphs while dropping a shape. After export, the same fixture engine reopens the bytes and compares semantic JSON. These fixtures are synthetic and contain no customer documents. To inspect a mismatch, open the exact source fixture and compare it against the committed expected paragraphs and tables.
+
+| Content | Import | Export | Notes |
+|---|---|---|---|
+| Paragraph text | Yes | Yes | Unicode preserved by JavaScript strings and the selected engine |
+| Headings 1-6 | Yes | Yes | Semantic heading level |
+| Bold | Yes | Yes | Common HTML projection |
+| Italic | Yes | Yes | Common HTML projection |
+| Strike | Yes | Yes | Common HTML projection |
+| Lists | Yes | Yes | Structural bullet and ordered lists; explicit start-number metadata is not modeled |
+| Block quotes | Yes | Yes | Nested supported block content is preserved |
+| Code blocks | Yes | Yes | Text content is preserved; language metadata is not modeled |
+| Basic tables | Yes | Yes | Header/cell topology is preserved; spans and layout styling are not modeled |
+| Links | Planned | Planned | Must use Inkspan safe-link policy |
+| Images | Planned | Planned | Must remain inline/host-approved; no external fetch |
+| Shapes/charts/equations | Rejected | Rejected | Fail closed; no silent drop |
+| Macros/OLE/active content | Not executed | Not generated | Outside the editor authority boundary |
+
+## Failure containment
+
+The host engine is untrusted at every call boundary, including cleanup. Open/create/operation failures are normalized to stable payload-redacted `HangulDocumentError` values. If engine cleanup fails after an otherwise successful public operation, Inkspan reports `ENGINE_CLEANUP_FAILED` without reading or stringifying the host-thrown value. If cleanup fails while Inkspan is already propagating a normalized primary import/export error, the primary error remains authoritative and the secondary cleanup failure is contained.
+
+## Security requirements
+
+Treat both formats as untrusted document containers. Production implementations must enforce bounded source and output bytes. The bridge also rejects host structural metadata above 4,096 sections, 1,000,000 paragraphs per section, or 16,777,216 UTF-16 code units per paragraph before traversing or passing those values back to the host engine. These are Inkspan safety ceilings, not HWP/HWPX format maxima.
+
+A native HWPX implementation must additionally bound ZIP entry count, expanded bytes, expansion ratio, XML depth, XML node count, text size, relationships, and embedded payloads. DTD and external entity resolution must be disabled. External relationships are metadata only unless the host separately authorizes a resource.
+
+Passwords, cookies, credentials, filesystem paths, and secret values must never enter warnings, error strings, result objects, or deterministic snapshots.
+
+## Standards and format sources
+
+HWPX follows OWPML document structure standardized as KS X 6101. The Korean standards catalogue records the standard as confirmed on 2024-10-30. Hancom publishes HWP 5.x and OWPML format material and recommends HWPX as the open machine-readable Hangul document format.
+
+### References (APA 7th)
+
+Korean Agency for Technology and Standards. (2024). *KS X 6101: Open Word-Processor Markup Language (OWPML) document structure*. e-Nara Standard Certification. https://www.standard.go.kr/KSCI/standardIntro/getStandardSearchView.do?ksNo=KSX6101
+
+Hancom Inc. (n.d.). *HWP/OWPML formats*. https://license.hancom.com/support/downloadCenter/hwpOwpml
+
+Hancom Inc. (n.d.). *HWPX format structure*. Hancom Tech. https://tech.hancom.com/hwpxformat/

docs/adr/0030-hangul-document-authoring-boundary.md

@@ -0,0 +1,76 @@
+# ADR 0030: Hangul document authoring boundary
+
+- Status: Proposed
+- Date: 2026-08-14
+- Decision owners: Inkspan maintainers
+
+## Context
+
+Inkspan needs to open, edit, and save Korean Hangul Word Processor documents without turning the editor package into a filesystem-, network-, or vendor-runtime-owning application. HWP 5.x is a published binary format. HWPX is the XML-based Hangul standard-document format built on OWPML, whose document structure is standardized as KS X 6101. The Korean standards catalogue records KS X 6101 as current after confirmation on 2024-10-30. Hancom also publishes HWP/OWPML format material and describes HWPX as an OWPML-based, machine-readable format.
+
+The editor already treats TipTap/ProseMirror JSON as the editable document authority. Introducing a second editable authority for HWP/HWPX would make autosave, collaboration, revision evidence, and host integration inconsistent.
+
+## Alternatives considered
+
+1. Parse HWP/HWPX directly inside the React editor. Rejected because binary/XML parsing, optional WASM initialization, document resources, and UI lifecycle become coupled.
+2. Convert every document through HTML and keep HTML as the editing authority. Rejected because HTML cannot represent every Hangul layout primitive and would make conversion loss implicit.
+3. Introduce a framework-neutral Hangul bridge with a host-injected parser/serializer engine and TipTap JSON as the editing authority. Selected.
+
+## Decision
+
+Inkspan exposes a framework-neutral Hangul bridge under a dedicated package boundary. The bridge accepts HWP/HWPX bytes through a host-injected engine, projects the supported semantic subset to TipTap JSON, and serializes edited JSON back through the engine. HWPX is the recommended export format because it is the open XML/OWPML path; HWP remains an explicit compatibility export.
+
+The host owns file selection, filesystem access, network access, WASM/module initialization, password UX, persistence, and download/publication. The bridge receives bytes and returns bytes. It never fetches external document resources.
+
+Unsupported structures are never silently asserted to be lossless. Import results carry warnings and a lossy flag. Export rejects editor structures that cannot be represented by the current bridge rather than dropping them silently.
+
+Host-returned structural metadata is untrusted work/index input. Before traversing or passing such metadata back into the host engine, Inkspan rejects values above 4,096 sections, 1,000,000 paragraphs per section, or 16,777,216 UTF-16 code units per paragraph. These are Inkspan safety ceilings, not HWP/HWPX format maxima; changing them is a resource-safety decision that requires corresponding regression evidence.
+
+## Consequences
+
+- Existing `CwlEditorHandle.setDocumentJson()` remains the single editing ingress.
+- HWP and HWPX share one product API while their parsing implementations remain replaceable.
+- Parser/serializer upgrades do not require React changes.
+- Full visual round-trip fidelity is not claimed until covered by real-document compatibility fixtures.
+- HWPX can later gain a first-party native OWPML implementation without changing the public bridge contract.
+- A forged engine cannot turn a small input into effectively unbounded section traversal or oversized paragraph indexes/offsets merely by returning safe-integer metadata.
+
+## Failure and recovery semantics
+
+Malformed input, unsupported source identity, resource-limit breaches, engine failures, and unsupported export structures fail closed with stable error codes. The original input is never mutated. Hosts may keep the original bytes and offer a fallback download or alternate viewer.
+
+## Security and privacy impact
+
+HWP/HWPX bytes are untrusted input. The bridge has no remote-resource fetch path and no active-content execution path. Source and output byte bounds are enforced before publication. Host structural counts and paragraph lengths are bounded before traversal, indexing, deletion, or HTML projection. Credentials, cookies, filesystem paths, and document passwords are not part of result objects or telemetry contracts.
+
+A future native HWPX parser must additionally bound ZIP entries, expansion ratio, XML depth, XML node count, text length, relationship targets, embedded objects, and external references. DTD and external-entity resolution must remain disabled.
+
+## Compatibility and migration
+
+The public contract identifies source and output as `hwp` or `hwpx`. HWPX is preferred for newly saved documents. Existing HWP users can explicitly request HWP export when their selected engine supports it. If a later native HWPX implementation replaces the initial engine adapter, compatibility is governed by the same JSON projection tests and real-document fixture suite.
+
+## Verification and acceptance evidence
+
+Acceptance requires all of the following on one exact PR head:
+
+- HWP and HWPX import tests;
+- edited JSON to HWPX and HWP export tests;
+- committed synthetic `briefing-minutes` and `unsupported-shape` fixtures that project known paragraphs/tables and fail closed on unsupported structures;
+- real documents reopened after export and compared against expected semantic content;
+- hostile/malformed input and resource-limit tests, including over-limit host section/paragraph metadata that fails before child traversal or host mutation;
+- package-consumer verification for ESM, CommonJS, and declarations;
+- production statement and branch coverage at repository policy thresholds;
+- public API docstring coverage at repository policy thresholds;
+- required CI, SAST, security, and independent review gates.
+
+Until that evidence is merged to protected `main`, this ADR remains Proposed.
+
+## Rollback or supersession
+
+The feature can be rolled back by removing the Hangul package subpath while retaining this ADR as historical evidence. A future design that makes native OWPML the canonical editable authority or grants the package filesystem/network authority requires a superseding ADR.
+
+## Standards and source traceability
+
+- Korean Agency for Technology and Standards. (2024). *KS X 6101: Open Word-Processor Markup Language (OWPML) document structure*. e-Nara Standard Certification. https://www.standard.go.kr/KSCI/standardIntro/getStandardSearchView.do?ksNo=KSX6101
+- Hancom Inc. (n.d.). *HWP/OWPML formats*. https://license.hancom.com/support/downloadCenter/hwpOwpml
+- Hancom Inc. (n.d.). *HWPX format structure*. Hancom Tech. https://tech.hancom.com/hwpxformat/

docs/adr/README.md

@@ -32,6 +32,7 @@ This index records durable architectural decisions. Protected-main implementatio
 | [0024](0024-bounded-docx-paragraph-alignment.md) | Accepted | Bounded paragraph alignment in deterministic DOCX output |
 | [0025](0025-bounded-docx-heading-alignment.md) | Accepted | Bounded heading alignment in deterministic DOCX output |
 | [0026](0026-bounded-docx-external-hyperlinks.md) | Accepted | Bounded external hyperlinks in deterministic DOCX rich text |
+| [0030](0030-hangul-document-authoring-boundary.md) | Proposed | Hangul document authoring boundary |
 
 ## Decision discipline
 

docs/hangul-workstream.md

@@ -0,0 +1,3 @@
+# HWP and HWPX workstream
+
+This branch tracks the isolated, non-release implementation for issue #319.

docs/package-distribution.md

@@ -1,10 +1,10 @@
 # Package distribution and consumer contract
 
 Inkspan publishes the React editor, provider-neutral collaboration adapter,
-framework-independent autosave/evidence/converter utilities, CSS, and offline
-font assets from one npm package. This document defines the supported package
-boundary for standalone applications, CWL organization services, and naruon
-integrations.
+framework-independent autosave/evidence/converter/Hangul utilities, CSS, and
+offline font assets from one npm package. This document defines the supported
+package boundary for standalone applications, CWL organization services, and
+naruon integrations.
 
 ## Public entrypoints
 
@@ -14,6 +14,7 @@ integrations.
 | `@contextualwisdomlab/cwl-editor/autosave` | Framework-independent autosave queue/session APIs for bounded local save ordering and host-owned durable concurrency |
 | `@contextualwisdomlab/cwl-editor/collaboration` | Optional Yjs collaboration surface with host-owned transport and lifecycle |
 | `@contextualwisdomlab/cwl-editor/converter` | Framework-independent base64 and data-URI utilities |
+| `@contextualwisdomlab/cwl-editor/hangul` | `implemented_on_active_pr` — framework-independent HWP/HWPX byte-to-document bridge with a host-injected parser/serializer engine; filesystem, network, persistence, credentials, and publication remain host-owned |
 | `@contextualwisdomlab/cwl-editor/envelope-identity` | Framework-independent identity-only envelope routing for bounded schema identity inspection; migration remains host-owned |
 | `@contextualwisdomlab/cwl-editor/revision-evidence` | Framework-independent revision evidence and document-transition evidence for local content equality/lineage claims |
 | `@contextualwisdomlab/cwl-editor/text-position-selector` | `implemented_on_protected_main` — React-free text-position projection core implementing W3C `TextPositionSelector`; interactive capture, revision binding, authorization, persistence, and re-anchoring remain outside this subpath |
@@ -57,12 +58,17 @@ embedded in the npm tarball.
   and collaboration entrypoints. It is declared in Inkspan's package
   dependencies so the consumer's package manager installs and resolves it; it
   is not merely a type-only dependency.
-- The framework-independent autosave, converter, envelope-identity,
+- The framework-independent autosave, converter, Hangul, envelope-identity,
   revision-evidence, text-position-selector, and Markdown entrypoints do not
   require React UI, a mounted editor, naruon, contextual-orchestrator, a
   database, provider credentials, or host transport. Their individual
   package-consumer gates additionally prevent framework dependencies from
   leaking into subpaths whose public contracts exclude them.
+- The Hangul subpath accepts and returns bytes through a host-injected document
+  engine. Inkspan owns the deterministic supported JSON projection, local
+  source/output resource ceilings, and stable failure contract; the host owns
+  file selection, filesystem and network access, engine/WASM initialization,
+  password UX, durable persistence, credentials, and artifact publication.
 - The Markdown subpath exposes `markdownToHtml`, `htmlToMarkdown`,
   `normalizeMarkdown`, `markdownToEmailHtml`, `markdownToPlainText`, and
   `htmlToPlainText` plus their option types. It bundles deterministic conversion
@@ -108,10 +114,10 @@ production library build. The verification chain:
 3. confirms required licenses, declarations, styles, and font assets ship;
 4. rejects internal source, tests, demos, Office files, coverage output, and
    workflow files from the npm tarball;
-5. imports the root, collaboration, converter, autosave, envelope-identity,
-   revision-evidence, text-position-selector, and Markdown surfaces through their
-   dedicated packed-consumer checks, including framework-free isolation where
-   that is part of the public contract;
+5. imports the root, collaboration, converter, Hangul, autosave,
+   envelope-identity, revision-evidence, text-position-selector, and Markdown
+   surfaces through their dedicated packed-consumer checks, including
+   framework-free isolation where that is part of the public contract;
 6. exercises supported ESM/CommonJS entrypoints and compiles strict TypeScript
    consumers against the published declaration surfaces;
 7. resolves public CSS and font subpaths; and