hyperframes-overview-edit

Overview Text Edit Module (required submodule)

Role of this skill

This skill is a hyperframes-overviewrequired submodule of. Every HyperFrames overview.html must always have inline text editing functionality.

This skill:

1. Checklist/snippet source for including the feature without omission when creating/modifying an overview
2. Parser rules for the agent to apply live server saving and static fallback patching to the file

It governs both purposes.

When to use this skill

• When creating a new overview.html → together with the parent hyperframes-overview, always insert the 3 snippets (procedure below)
• When modifying/reviewing an existing overview.html → first check whether any feature is missing (verification below)
• When the user pastes a patch starting with # Overview edits — ... → references/patch-parser.md refer to it and apply it to the file

Quick verification of omissions

# 기능이 빠진 overview.html 파일 찾기
grep -L "class=\"edit-btn\"" topics/*/overview.html

The output file is missing the Edit feature → add it with this skill's snippet.

3 steps to apply

Step 1: Insert CSS

references/css.html Paste the contents of .aim-toast .toast-sel { ... } immediately after the rule. (</style> Not immediately before, but before the card styles appear. After the Aim feature block.)

Step 2: Add the Edit button

.header-right 안 <button class="aim-btn"> One line immediately before:

<button class="edit-btn" id="nav-edit" aria-label="text edit">Edit</button>

Step 3: Insert JS (choose variant)

Insert the Text Edit mode block immediately before the IIFE's final })() . Choose one of the 2 types depending on the overview's card/slide anchor attribute:

Overview type	Anchor attribute	JS snippet
Card news (1080×1080·1080×1350)	data-card	references/js-card.html
16:9 slide (1920×1080)	data-slide	references/js-slide.html

The two variants differ only in the query selector and the "Card" vs "Slide" label in the patch. The rest of the code is identical.

Serving mode: Live vs Static

There are two serving modes.

1. Live mode (recommended) — serve-live.sh

POST /save A Python server with an endpoint. When the Done button is clicked, the browser POSTs the patch to fetch('/save', ...) → the server immediately applies it to the index.html + overview.html 을 file.

bash .codex/skills/hyperframes-overview-edit/serve-live.sh topics/<주제> <포트>

• No need for the user to paste the patch into the chat window
• Toast: "✓ N items applied (file modified directly) — the right screen and left thumbnail are updated together"
• Edits are saved even if the agent does not participate in the conversation (however, rendering still requires user approval)

2. Static mode (fallback) — serve.sh

The existing hyperframes-overview/serve.sh has no POST endpoint. In this case the browser's fetch fails → it automatically falls back to clipboard copy mode.

• Toast: "✎ N changes copied to clipboard — paste into the chat to request agent apply"
• User pastes the patch into the chat → the agent applies it references/patch-parser.md accordingly

Browser-side code always tries live firstand falls back to clipboard on failure. Both modes are supported transparently.

Patch format

When the user clicks the Done button, the format below is copied to the clipboard (static), or sent to the live server's /save endpoint:

# Overview edits — <topic-id> (N change(s))

## Card 3 (question)
- .q-text
  OLD: 기존 텍스트 (innerHTML, 인라인 태그 포함 가능)
  NEW: 수정된 텍스트

## Card 5 (stat)
- .stat-label
  OLD: ...
  NEW: ...

16:9 slide variant는 ## Card N instead of ## Slide N , use the header.

Agent-side patch application procedure

When the user pastes markdown in the above format into the chat, agent는 references/patch-parser.mdaccording to the rules in apply it to the file. Summary:

1. Header # Overview edits — <topic> identify topic from → topics/<topic>/ determine path as
2. 각 ## Card N (skill) / ## Slide N (skill) for each section:
   • index.html: <div id="c-N" or <div id="s-N" find block → Edit OLD to NEW in the element with the specified CSS class
   • overview.html: same card's [data-card="N"] or [data-slide="N"] same Edit in block
3. After applying to both files, report a summary to the user ("N applied, 2 files modified")
4. Do not run render automatically — wait for user approval per AGENTS.md's overview-first rule

Limitations and cautions

• Only text-only leaves are editable — IMG, aria-hidden, elements with block children (div/ul/ol/section) are locked
• Preserve inline tags — <em>, <strong>, <br>, <span> etc. are diffed at the innerHTML level, so they are preserved during editing
• Temporary save within session — click Done before refreshing to copy the patch
• Thumbnail sync — when Done is clicked, immediately regenerate the left strip thumbnail clone of the changed card/slide from the latest DOM on the right. Keep it so there is no need to refresh before PDF/export.
• Thumbnail render match — keep the left thumbnail, but it must use the same display model as the right editing view. For 16:9 slides, .thumb .scene { display: flex; }, for card news, .thumb .card { display: flex; } specify. If this rule is missing, even with the same DOM clone the flex layout differs, making the thumbnail and editing view look different.
• PDF/export criteria — browser PDF/print/export is based on the original card/slide of the right #detail-frame , not the left strip clone. The overview template must include CSS that hides @media print 로 .strip, .main-header, the Aim/Edit UI, and outputs only the original inside .detail-frame page by page.

Integration test

After HTTP-serving the newly created overview, in the browser:

• whether the top-right Edit button appears to the left of the Aim button
• whether clicking shows blue dashed outlines on text elements (darker on hover, solid on focus)
• After fixing one word and pressing Done, does the toast "✓ N items reflected" appear on the live server, and "✎ N changes copied to clipboard" on the static server?
• After Done, does the collapsed thumbnail on the left update immediately with the same layout/text as the editing screen on the right?
• Does the PDF/print result include only the original slide/card pages without the left strip?
• In the static server fallback, does the pasted patch exactly match the above format?

All 6 must pass for the feature to be OK.

Related skills

• hyperframes-overview — overview generator for 16:9 slide decks (pairs with this skill)
• hyperframes-card-news — card news overview generator (pairs with this skill)
• AGENTS.md — document how to use this feature in the "Review Workflow — Overview First, Render Second" section