webtoon-assembly

Webtoon Assembly and QA Methodology (webtoon-assembly)

This is the final process that turns rendered panels into a "readable webtoon." It covers assembly (vertical scroll viewer) → lettering (speech bubbles) → QA/inspection → continuity management → final packaging. Do not tailor it to a specific episode; write it generalized so it applies to any episode. {NN} = 2-digit episode number.

Core principles (why we do it this way):

Order is narrative. The order panel_001 → panel_050+ is itself the reading flow, and the tension curve and twist timing ride on it. Break the order and the story breaks.
Mobile vertical scroll is the default medium. Readers scroll down with a finger. Desktop is also viewed at a centered mobile width.
Readability beats artwork. If speech bubbles cover faces/key artwork, readers drop off. The more dialogue-driven the webtoon, the more this is true.
QA is proof. Prove pass/fail not with "it looks good" but with measured values and cross-comparison.

1. Vertical scroll viewer assembly method (episode-compositor)

Why: Connect panels into a single vertical strip so they can be read without interruption using only finger scrolling.

The speech bubbles in this harness are in-image bakes. Since the speech bubbles and Korean dialogue are already drawn into the panel PNGs, assembly is a pure image strip that connects panels in order without text overlays. lettering.md is used not as overlay data but only as (a) spacing/rhythm hints between panels and (b) a basis for QA to compare against the baked text.

For the skeleton, use assets/viewer-template.html. It is a single HTML file with no external dependencies, so it can be opened anywhere for inspection. Do not write it from scratch; just fill in the template's META와 PANELS data array.

Procedure

_workspace/05_panels/ep{NN}/Collect the PNGs in ascending filename order (panel_001 → …) (those that passed panel-validator).
Fill in the template's PANELS array. One item = one panel (no speech bubble data):
```
{ src: "../../05_panels/ep{NN}/panel_001.png", alt: "panel 001", gap: 0 }
```
- srcis the relative path (06_assembly/ep{NN}/index.html) based on the output file (../../05_panels/...). Or you may copy the panels into the same folder and reference them.
- gapis the spacing (px) to the next panel: 0= seamless (continuous cut), positive = scene transition/time passage/silent cut ("thunk"). Determine it based on the rhythm hints in lettering.md and the shot list's SCENE BREAK.
Place panels fully at their original aspect ratio (so baked speech bubbles are not cropped).
Open it in a browser and visually check scrolling, seams, and speech bubble readability. If a baked speech bubble is broken, do not cover it with an overlay; request a re-render from panel-validator/panel-artist(no duplicate marking).

Structure/style rules (reflected in the template)

Responsive width (mobile-first): --max-w: 720px centered. Width fills 100% and height is auto.
Seams between panels: --panel-gapcontrolled by. 0px=seamless connection (continuous cuts of one scene), positive value=cell separation (scene transition/time passage). Use it according to the meaning.
lazy-load: <img loading="lazy" decoding="async">. Reduces initial loading and memory burden for episodes with 50+ panels.
Missing indication: when image loading fails, do not leave the cell empty; show a warning placeholder (img.onerror). Do not hide omissions so that review catches them.
Data/expression separation: panels and speech bubbles are data arrays, styles are CSS. When reassembling or editing, swap only the data.

Missing/order handling

If a number is missing (no panel_007), do not pull it together; mark the missing spot in place and request a re-render from panel-artist. If the order is off, the twist timing collapses.
0-byte/corrupted PNGs are also treated as missing.

2. Lettering section (for letterer → prompt-smith baking)

Why: in dialogue-heavy, high-tension webtoons, speech bubbles are the main channel carrying information, emotion, and twists. If placed wrong, it is unreadable even with good art. In this harness, speech bubbles are drawn together with the image (in-image baking), so the letterer designs with this section's rules ep{NN}_lettering.md(bake specification), and prompt-smith puts it into the codex prompt to render, and panel-validator checks the text accuracy of the rendered result against this file (episode-compositor does not overlay).

Speech bubble types (in the template, `type`)

dialogue (spoken lines): words spoken aloud. White background, black border, rounded corners, tail (tail) points to the speaker.
thought (inner thoughts): inner thoughts. Dashed border, italics. No tail (or cloud dots).
shout (shout): scream, yell, shock. Thick border, bold text, slight slant. Strong in twist/climax panels.
narration (narration): narration outside the speaker, time/place captions. Rectangular box, no tail. Do not overuse — minimizing narration is the principle, and if it can be conveyed through dialogue, convert it to dialogue.

Position rules

Reading order: arrange so that within a panel it reads naturally top→bottom, left→right. The bubble that speaks first is at the top/left.
Avoid faces/key art: do not cover character expressions or twist clues. Place in empty space (sky, floor, background).
Tail direction (tail): the tail points toward the speaker's mouth/head (left/right/up/down). Speaker attribution must be visible at a glance.
Edge safe margin: Keep x/y within 5–95% so speech bubbles are not cropped outside the panel.

Readability principles (dialogue-driven webtoon)

Font size: Body dialogue should be large enough (--bubble-fs baseline 16–18px). If it's small on a mobile screen, readers leave immediately.
Contrast: Ensure clear contrast between text color and bubble background (black text/white bubble, narration white text/dark box).
Amount per bubble: Break by breath units. Split long dialogue into multiple bubbles to create a rhythm of tension.
Line breaks: word-break: keep-allso Korean word units are not awkwardly cut off.
Lettering method: The default of this harness is in-image bake(draw speech bubbles and Hangul together during image generation). letterer writes the bake spec and prompt-smith includes it in the prompt. Do not use HTML overlay (to prevent double rendering with image text).
Hangul bake caution (biggest risk): Diffusion image generation frequently breaks Hangul. So (a) keep dialogue per bubble short (few word units), (b) write the script's original spelling exactly, and (c) pass it through panel-validator's C3 (text accuracy/readability) regeneration loop.

`ep{NN}_lettering.md` Recommended format (letterer output → prompt-smith bake)

### panel_001
- bubble_1: { speaker: 나레, type: narration, text: "비 오는 밤.", position: 상단 중앙, read_order: 1 }
- bubble_2: { speaker: 지호, type: dialogue, text: "…왜 또 너야?", position: 하단 좌측 여백(얼굴 안 가림), read_order: 2 }
### panel_004
- silent: true            # 무대사 침묵 컷(말풍선 없음)

textis the script's original text as-is (including spelling and punctuation) — prompt-smith bakes it in quotes and the validator compares it character by character.
positionis not coordinates but an area instruction (top/bottom/left/right/center + face avoidance). The basis for the prompt drawing the speech bubble position.

3. QA checklist (quality-reviewer)

Why: The earlier and more objectively defects are caught, the cheaper the rework. What can be counted is measured by script, and meaning is verified by cross-comparison. Incremental QA — verify immediately as each module is completed.

Two-stage verification division of labor: Panel-level primary verification (character/background/Hangul/prompt fidelity) is filtered by the visual team panel-validatorduring rendering via the generation-verification loop (ep{NN}_validation.md). quality-reviewer는 그 뒤 the assembled full episodeas the end gate for review, first identify the ACCEPT-FLAG panels in validation.md and focus on the episode flow, twists, continuity, and final acceptance of flagged panels.

Review items and PASS/FIX/REDO criteria

Item	Measurement/Judgment	PASS	FIX	REDO
Panel count 50+	Count PNGs	≥50	—	<50 (bit split rework)
Corrupted/0-byte/duplicate	Bytes, PNG header,md5 duplicate	All normal and unique	Few → re-render	Many corrupted/duplicate
Appearance consistency	Compare against refs/ referencesand visual inspection	Maintained	1–2 panels minor	Character identification broken
Background/location continuity	scene_id ↔ location cross-check	In-scene consistency	1–2 cell correction	Frequent abrupt background changes mid-scene
Speech bubbles · Korean text	Baked text ↔ script cross-check	Accuracy · readability	Minor typos/positioning	Extensive corruption · misreading
Dialogue flow	Reading continuity across adjacent panels	Naturalness	Local touch-ups	Flow break
Twist delivery	Script ↔ panel ↔ baked dialogue cross-check	Revealed	Clue reinforcement	Twist not delivered
Tension curve	Flow · cliffhanger	Upward trend + hook	Pacing fix	Curve collapse

PASS: Pass as-is. FIX: Resolved with local fixes (no re-render needed or minor). REDO: Fundamental defect requiring re-render/rewrite. Blurring the grade makes the rework loop inefficient.

Objective metric measurement (via script)

Panel count: _workspace/05_panels/ep{NN}/의 panel_*.png Count the number.
0 bytes: Find PNGs with file size 0.
Corruption: Check the header with PNG magic bytes (\x89PNG).
md5 duplicates: md5 -r panel_*.png | awk '{print $1}' | sort | uniq -d — Should be empty (an incident if different panels share the same image). It actually occurred in EP01, so it is mandatory. (Reference: references/qa-checks.md)

Interface cross-validation (top priority)

The most expensive failure is disconnection: when the script (03_episode/ep{NN}_script_final.md) and twist design (02_story/twist-plan.md) contain a twist but it does not appear in the actual panels/lettering. Always cross-check script ↔ lettering ↔ panels — whether the twist is expressed visually/in dialogue, and whether foreshadowing was planted in earlier panels.

Writing fix instructions

Specify target, problem, action, and owner. Example: "panel_023 speech bubble covers the speaker's face → move to upper-right margin (owner: letterer/episode-compositor)". Vague terms ("awkward") are forbidden.

Rework loop

FIX/REDO is sent to the responsible agent (layout → episode-compositor, art/appearance/corruption → panel-artist, speech bubbles → letterer, twist/dialogue → script-editor · twist-master). The loop runs up to 2 times, and if it is still REDO after that, escalate to the showrunner.

4. Continuity management (continuity-manager)

Why: As episodes accumulate, appearances, settings, and plot threads easily drift out of alignment. They must be accumulated in a single ledger so the next episode continues without contradiction. continuity.md는 Do not overwrite; append per episode(you need past states to catch contradictions).

Ledgers to track:

Character appearance ledger: Fixed traits per character (hair color/clothing/body type/identifying marks) + change history per episode ("X→Y in ep03").
Setting · worldbuilding ledger: Additions/changes to ability rules, place names, organizations, and timelines.
Plot·Relationships·Information State: Snapshot at the end of the episode, who knows what (information asymmetry).
Twist Setup Ledger (Table): Foreshadowing / Episode Planted / Planned Payoff / Payoff Status / Notes. Always keep unpaid-off setups on the surface — a planted setup has an obligation to be paid off.
Notes for Next Episode: Checklist from a consistency/payoff perspective (imperative).

The source of truth is 02_story/*(characters/world/series-arc/twist-plan)와 04_visual/* sheets. If the output conflicts with the source of truth, treat the output as wrong or request an update to the source of truth (no arbitrary judgment; record both sides).

5. Final Packaging (showrunner)

Why: The approved version must itself be openable and distributable. RELEASE includes what was included (manifest), the basis for approval, and the seed for the next episode.

Sign-off criteria: qa_report.md(quality within an episode) and continuity.md(continuity between episodes) must be simultaneously satisfied. If there is a REDO or unresolved contradiction, do not sign off and send it back.

_workspace/RELEASE/ep{NN}/ Structure:

RELEASE/ep{NN}/
  index.html          # 뷰어(상대경로가 깨지지 않게 panels/ 동봉 권장)
  panels/             # 패널 PNG 사본(또는 안정적 참조)
  qa_report.md        # 품질 합격 근거
  RELEASE_NOTES.md    # 사인오프 판정 · 포함 목록 · 다음 회차 시드

Next Episode Seed: Carrying over this episode's cliffhanger and unpaid-off setups, agree with continuity-manager on the starting point for the next episode, write it in RELEASE_NOTES.md, and hand it off to the scenario team (series-plotter·twist-master).

6. Output Paths (follow §3 Data Flow)

Assembly viewer: _workspace/06_assembly/ep{NN}/index.html (episode-compositor)
Review report: _workspace/06_assembly/ep{NN}/qa_report.md (quality-reviewer)
Continuity record: _workspace/06_assembly/continuity.md (continuity-manager, cumulative)
Final package: _workspace/RELEASE/ep{NN}/ (showrunner)

Input paths: panels _workspace/05_panels/ep{NN}/panel_*.png, lettering _workspace/04_visual/ep{NN}_lettering.md, finalized script _workspace/03_episode/ep{NN}_script_final.md, twist design _workspace/02_story/twist-plan.md, source of truth _workspace/02_story/*·_workspace/04_visual/*.

7. Follow-up Work (redo/reassemble/revise/supplement)

If the output already exists, do not recreate it wholesale; replace only the changed parts. Preserve the approved parts.
Reassembly: Replace only the data items of changed panels/balloons. Re-review: Re-verify only the reworked items and update the verdict. Continuity: Record only the changed items onward.
Assets: The working viewer skeleton is assets/viewer-template.html. The ready-to-use verification command is references/qa-checks.md.