@erclx/canon 5.51.0 → 5.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +1 -4
  3. package/claude/.claude-plugin/plugin.json +1 -1
  4. package/claude/skills/canon-cli/SKILL.md +0 -3
  5. package/claude/skills/context-fold/REQUIREMENT.md +0 -1
  6. package/claude/skills/design-taste/references/kinds.md +0 -1
  7. package/claude/skills/draw-figure/REQUIREMENT.md +2 -3
  8. package/claude/skills/draw-figure/SKILL.md +4 -5
  9. package/claude/skills/draw-figure/references/figures.md +0 -1
  10. package/claude/skills/draw-figure/references/hand-drawn.md +1 -1
  11. package/claude/skills/git-pr/references/pr.md +1 -1
  12. package/claude/skills/pick-by-eye/REQUIREMENT.md +0 -1
  13. package/claude/skills/pick-by-eye/SKILL.md +1 -1
  14. package/claude/skills/review-address/SKILL.md +1 -1
  15. package/claude/skills/review-address/references/post-review-findings.md +1 -1
  16. package/claude/skills/review-pr/references/post.md +2 -2
  17. package/claude/skills/target-check/SKILL.md +2 -0
  18. package/claude/skills/target-setup/SKILL.md +1 -1
  19. package/claude/skills/target-update/REQUIREMENT.md +33 -0
  20. package/claude/skills/target-update/SKILL.md +136 -0
  21. package/claude/skills/teach-craft/REQUIREMENT.md +30 -0
  22. package/claude/skills/teach-craft/SKILL.md +39 -0
  23. package/claude/skills/teach-craft/references/lesson-craft.md +52 -0
  24. package/claude/skills/{teach-workspace → teach-craft}/references/pedagogy.md +12 -4
  25. package/docs/agents/audits.md +0 -1
  26. package/docs/agents/migrate.md +2 -1
  27. package/docs/target/migrations.md +12 -1
  28. package/docs/target/projects.md +1 -1
  29. package/docs/target/sync.md +1 -1
  30. package/docs/workflow/parallel-features.md +1 -1
  31. package/docs/workflow/skill-map-on-request.md +10 -22
  32. package/docs/workflow/skill-map.md +13 -14
  33. package/package.json +1 -4
  34. package/scripts/core/regen-web-previews.ts +2 -67
  35. package/src/audits/catalog.ts +0 -1
  36. package/src/browser/engine.ts +3 -6
  37. package/src/capture/render.ts +1 -1
  38. package/src/claude/cases/authoring.ts +0 -12
  39. package/src/claude/cases/misc.ts +0 -17
  40. package/src/claude/cases/setup.ts +7 -0
  41. package/src/claude/cases/workflow.ts +2 -38
  42. package/src/claude/skills-audit.ts +0 -1
  43. package/src/cli/help.ts +0 -7
  44. package/src/cli.ts +0 -6
  45. package/src/commands/labels.ts +9 -7
  46. package/src/commands/records.ts +0 -1
  47. package/src/commands/serve.ts +2 -2
  48. package/src/design/components.ts +8 -1514
  49. package/src/design/css.ts +5 -6
  50. package/src/design/fonts.ts +3 -5
  51. package/src/driver/drive.ts +3 -4
  52. package/src/driver/steps.ts +2 -5
  53. package/src/inventory/walk.ts +1 -1
  54. package/src/markdown/scope.ts +4 -31
  55. package/src/migrate/status.ts +5 -1
  56. package/src/records/validate.ts +4 -176
  57. package/src/sandbox/equivalence.ts +0 -5
  58. package/tooling/claude/seeds/.claude/hooks/review-post-scan.sh +1 -1
  59. package/claude/skills/draft-and-pick/REQUIREMENT.md +0 -26
  60. package/claude/skills/draft-and-pick/SKILL.md +0 -11
  61. package/claude/skills/draft-doc/REQUIREMENT.md +0 -26
  62. package/claude/skills/draft-doc/SKILL.md +0 -11
  63. package/claude/skills/draft-figure/REQUIREMENT.md +0 -26
  64. package/claude/skills/draft-figure/SKILL.md +0 -11
  65. package/claude/skills/draft-identity/REQUIREMENT.md +0 -26
  66. package/claude/skills/draft-identity/SKILL.md +0 -11
  67. package/claude/skills/draft-ready/REQUIREMENT.md +0 -26
  68. package/claude/skills/draft-ready/SKILL.md +0 -11
  69. package/claude/skills/draft-screencast/REQUIREMENT.md +0 -26
  70. package/claude/skills/draft-screencast/SKILL.md +0 -11
  71. package/claude/skills/draft-slides/REQUIREMENT.md +0 -26
  72. package/claude/skills/draft-slides/SKILL.md +0 -11
  73. package/claude/skills/make-deck/REQUIREMENT.md +0 -36
  74. package/claude/skills/make-deck/SKILL.md +0 -80
  75. package/claude/skills/make-deck/references/deck.md +0 -183
  76. package/claude/skills/read-frames/REQUIREMENT.md +0 -30
  77. package/claude/skills/read-frames/SKILL.md +0 -55
  78. package/claude/skills/record-screencast/REQUIREMENT.md +0 -35
  79. package/claude/skills/record-screencast/SKILL.md +0 -99
  80. package/claude/skills/script-screencast/REQUIREMENT.md +0 -34
  81. package/claude/skills/script-screencast/SKILL.md +0 -70
  82. package/claude/skills/script-screencast/references/beats-template.md +0 -119
  83. package/claude/skills/teach-workspace/REQUIREMENT.md +0 -34
  84. package/claude/skills/teach-workspace/SKILL.md +0 -196
  85. package/claude/skills/teach-workspace/references/glossary.md +0 -90
  86. package/claude/skills/teach-workspace/references/lesson-build.md +0 -106
  87. package/claude/skills/teach-workspace/references/lesson-craft.md +0 -135
  88. package/claude/skills/teach-workspace/references/promotion-fold.md +0 -35
  89. package/claude/skills/teach-workspace/references/promotion.md +0 -116
  90. package/claude/skills/teach-workspace/references/revisit.md +0 -28
  91. package/claude/skills/teach-workspace/references/teach.md +0 -211
  92. package/claude/skills/video-craft/REQUIREMENT.md +0 -35
  93. package/claude/skills/video-craft/SKILL.md +0 -96
  94. package/claude/skills/video-craft/references/adopted.md +0 -110
  95. package/src/commands/demo.ts +0 -542
  96. package/src/commands/slides.ts +0 -184
  97. package/src/commands/teach.ts +0 -1401
  98. package/src/demo/beats.ts +0 -135
  99. package/src/demo/compile.ts +0 -350
  100. package/src/demo/container.ts +0 -219
  101. package/src/demo/cursors.ts +0 -55
  102. package/src/demo/drive.ts +0 -442
  103. package/src/demo/pointer.ts +0 -178
  104. package/src/demo/theme.ts +0 -112
  105. package/src/demo/timeline.ts +0 -64
  106. package/src/slides/convert/chart.ts +0 -165
  107. package/src/slides/convert/deck.ts +0 -244
  108. package/src/slides/convert/export.ts +0 -567
  109. package/src/slides/convert/master.ts +0 -198
  110. package/src/slides/convert/shapes.ts +0 -804
  111. package/src/slides/convert/svg.ts +0 -38
  112. package/src/slides/convert/walk.ts +0 -671
  113. package/src/slides/decks.ts +0 -110
  114. package/src/slides/open.ts +0 -18
  115. package/src/slides/package/fonts.ts +0 -301
  116. package/src/slides/package/motion.ts +0 -316
  117. package/src/slides/package/test-face.ts +0 -113
  118. package/src/teach/browser/compile.ts +0 -44
  119. package/src/teach/browser/dismiss.ts +0 -76
  120. package/src/teach/browser/focus-line.ts +0 -19
  121. package/src/teach/browser/glossary-filter.ts +0 -44
  122. package/src/teach/browser/head.ts +0 -30
  123. package/src/teach/browser/quiz.ts +0 -19
  124. package/src/teach/browser/reload.ts +0 -9
  125. package/src/teach/browser/sidebar.ts +0 -233
  126. package/src/teach/browser/theme.ts +0 -18
  127. package/src/teach/components/code.tsx +0 -24
  128. package/src/teach/components/heading.tsx +0 -11
  129. package/src/teach/components/list.tsx +0 -17
  130. package/src/teach/components/paragraph.tsx +0 -29
  131. package/src/teach/components/refs.tsx +0 -28
  132. package/src/teach/cross-references.ts +0 -78
  133. package/src/teach/fonts.ts +0 -16
  134. package/src/teach/highlight.ts +0 -71
  135. package/src/teach/html/jsx-dev-runtime.ts +0 -13
  136. package/src/teach/html/jsx-runtime.ts +0 -113
  137. package/src/teach/html/raw.ts +0 -28
  138. package/src/teach/lesson.ts +0 -178
  139. package/src/teach/nav.ts +0 -1337
  140. package/src/teach/render.ts +0 -240
  141. package/src/teach/workspace.ts +0 -1164
  142. package/src/teach/write-if-changed.ts +0 -17
@@ -1,211 +0,0 @@
1
- ---
2
- title: Teach reference
3
- description: Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace
4
- ---
5
-
6
- # Teach reference
7
-
8
- Applies to a learning workspace at `.canon/teach/<nn>-<topic>/`. One workspace holds one subject studied across sessions, and it carries both halves of what studying produces: the durable reference material a reader consults later, and the disposable lessons a learner works through once.
9
-
10
- The folder is gitignored. Its markdown half is written in a format the authoring gates read, so a page promoted out of it later needs no conversion.
11
-
12
- ## Contents
13
-
14
- - [Scope](#scope)
15
- - [What a working workspace looks like](#what-a-working-workspace-looks-like)
16
- - [Folder name](#folder-name)
17
- - [Layout](#layout)
18
- - [Frontmatter](#frontmatter)
19
- - [File naming](#file-naming)
20
- - [MISSION.md](#missionmd)
21
- - [Learning records](#learning-records)
22
- - [Revisit](#revisit)
23
- - [GLOSSARY.md](#glossarymd)
24
- - [RESOURCES.md](#resourcesmd)
25
- - [Conventions](#conventions)
26
- - [Anti-patterns](#anti-patterns)
27
- - [Template](#template)
28
-
29
- ## Scope
30
-
31
- Governs a learning workspace under `.canon/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission and learning-record formats.
32
-
33
- Does not govern:
34
-
35
- - **the `teach-workspace` skill**: the frontmatter, entry shape, and ordering of the glossary the workspace holds, which that skill's reference carries
36
- - **the surface driving the workspace**: what a lesson teaches, how it sequences difficulty, and what makes one worth returning to
37
- - **the routing test the destination surface states**: where a durable page goes once it leaves the workspace
38
- - **`groundwork.md`**: one question measured in depth before anyone can plan against it
39
- - **`intake.md`**: A dump of many findings filed by domain, each carrying its own verdict
40
- - **the `write-human` skill**: voice, rhythm, and sentence construction
41
- - **`markdown.md`**: headings, punctuation, word choice, and file references
42
- - **the surface driving it**: when a workspace opens at all, and the procedure that runs one
43
-
44
- ## What a working workspace looks like
45
-
46
- A workspace works when a session returning after weeks can resume from the folder alone:
47
-
48
- - Which subject is being learned, and what will the learner be able to do when the mission is finished?
49
- - Which sources stand behind the material, and which were found and never opened?
50
- - What has the learner already been through, and what did they get wrong?
51
- - Which pages here are durable reference material, and which are disposable?
52
-
53
- A workspace failing these is non-conforming even when it satisfies every shape rule below.
54
-
55
- ## Folder name
56
-
57
- - Name the folder `<nn>-<topic>`, a two-digit zero-padded ordinal followed by a kebab-case topic slug.
58
- - Take the ordinal from the highest one already present, incremented. A listing then sorts by when each workspace opened rather than alphabetically.
59
- - Use two digits on the folder and four inside it. A person opens far fewer workspaces than one workspace holds lessons.
60
- - Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
61
-
62
- ## Layout
63
-
64
- | Path | Holds | Required |
65
- | ----------------------- | ----------------------------------------------------------------------- | -------- |
66
- | `MISSION.md` | The subject, the learner's starting point, and success | Always |
67
- | `RESOURCES.md` | Sources read and sources found but not opened | Always |
68
- | `GLOSSARY.md` | Terms the subject defines, one entry each | Always |
69
- | `NOTES.md` | Session scratch that belongs to no other file | Optional |
70
- | `reference/<slug>.md` | Durable reference pages, the promotable half | Optional |
71
- | `reference/<slug>.html` | Each reference page rendered by `canon teach nav`, never edited by hand | Optional |
72
- | `learning-records/` | Numbered records of what the learner was taken through | Optional |
73
- | `lessons/` | Numbered lessons, generated and disposable | Optional |
74
- | `assets/` | Files several lessons share, including the stylesheet | Optional |
75
-
76
- Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, the markdown under `reference/`, and `learning-records/`.
77
-
78
- - A lesson is generated markup nothing downstream cites, so this standard fixes its filename and location and nothing about its contents
79
- - A rendered reference page is the same kind of output, rewritten from its markdown on every `nav` run
80
-
81
- ## Frontmatter
82
-
83
- Every markdown file carries `title` and `description`. `MISSION.md` carries one field the others do not.
84
-
85
- - `title` (required): what the file covers, in sentence case
86
- - `description` (required): one line naming what a reader gets from it
87
- - `date` (required, `MISSION.md` only): the day the workspace opened, as `YYYY-MM-DD`
88
-
89
- Date the workspace once rather than every file. A per-file date leaves every other file stale the first time one is edited, and the opening date never rots.
90
-
91
- ## File naming
92
-
93
- - Number a lesson and a learning record `0001` upward, as `<nnnn>-<slug>.html` and `<nnnn>-<slug>.md`. The number is read order and never changes.
94
- - Name a reference page for its subject alone, with no number. A reference page is looked up rather than worked through, so an ordinal on one implies an order no reader follows.
95
- - Keep one shared stylesheet under `assets/` and embed it in every lesson. A lesson restating its own styles makes a workspace read as a pile of one-offs rather than as one course.
96
-
97
- ## MISSION.md
98
-
99
- Fixes what the workspace is for. Everything else in the folder answers to it.
100
-
101
- - A one-line statement of the subject
102
- - A `## Starting point` section stating what the learner already knows, so difficulty has a floor to sit above
103
- - A `## Success looks like` section listing specific observable things the learner will be able to do
104
- - A `## Out of scope` section naming what this workspace deliberately does not cover
105
-
106
- Write each success line as something a learner can be asked to do rather than something they will understand. A line nobody can test is a line nothing can report progress against.
107
-
108
- ## Learning records
109
-
110
- One record per session the learner worked through, holding what happened rather than what was taught.
111
-
112
- - The lessons covered, by number
113
- - What the learner retrieved correctly without help
114
- - What they got wrong, and what the wrong answer was, including what an explanation the learner produced left out
115
- - A `## Revisit` section scheduling what comes back up
116
-
117
- Record the wrong answer rather than the fact of an error. A wrong answer names the misconception, and the count alone names nothing.
118
-
119
- A produced explanation and a selected option are both retrieval, so a gap in an explanation goes under what the learner got wrong rather than under a heading of its own. Name the concept and where the explanation broke. Splitting the two puts one input to the next session's placement across two sections, and the placement reads both or neither.
120
-
121
- ### The revisit section
122
-
123
- Write one bullet per item, in this shape and no other:
124
-
125
- ```markdown
126
- ## Revisit
127
-
128
- - **<what comes back up>**: due <YYYY-MM-DD>, rung <n>
129
- ```
130
-
131
- The rung is the item's place on the spacing ladder. It travels in the record rather than being counted from records naming the item, since a miss drops it back and a count only climbs.
132
-
133
- - A later record naming the item supersedes an earlier one, so revise by writing a new entry rather than editing the old record
134
- - Take the date and rung from what the driving surface reports. An entry outside this shape schedules nothing, silently.
135
-
136
- ## GLOSSARY.md
137
-
138
- Required at the root of every workspace, one entry per term the subject defines. The glossary reference the `canon:teach-workspace` skill carries fixes the entry shape, order, grouping, and which terms it holds.
139
-
140
- - That reference ships with the plugin rather than installing here, since a promoted glossary keeps its shape wherever it lands
141
- - With no plugin to read it from, say so and stop rather than working the shape from memory
142
- - Name the lesson or reference page a term first appears in, which a workspace always has
143
-
144
- ## RESOURCES.md
145
-
146
- Splits what was read from what was found.
147
-
148
- - List every source that stands behind the material, each with a link
149
- - List under a leads heading any source found and not opened, and never cite one
150
- - Say which claims in the workspace rest on which source
151
-
152
- An unread source is a lead because a link to a page nobody opened is worse than none. Listing it stops a later session searching again.
153
-
154
- ### Choosing sources
155
-
156
- Rest each general claim on the highest rung that covers it:
157
-
158
- 1. Documentation or a specification published by whoever owns the subject
159
- 2. A canonical work on the subject, such as the standard text, a reference book, or a primary paper
160
- 3. Other material, such as a tutorial, a course, or a post, and only for a claim the first two rungs do not cover
161
-
162
- A subject nobody owns, such as a mathematical topic or a craft, has no first rung, so its list starts at the second and is not missing anything. Record a third-rung source with the claim it covers and why no higher rung does, since that reason is what a later session checks the choice against.
163
-
164
- ### What never counts
165
-
166
- The learner's own projects and material specific to one employer or organization are never a source for a general claim. Either may appear in the workspace as a worked application labeled with whose it is, and neither stands in `RESOURCES.md` as proof of what the subject says.
167
-
168
- A source reachable only through a paywall or a summary stays a lead until it is opened. A review or summary of a book is a different source from the book, so list the summary as read on its own rung and the book as a lead.
169
-
170
- ## Conventions
171
-
172
- - Write the markdown half in the format the authoring gates read, so a page promoted later needs no conversion.
173
- - Keep a reference page free of the learner. A page carrying a second person or a quiz is a lesson wearing the wrong extension, and it cannot be promoted.
174
- - Revise a file the subject has moved under rather than appending a second version narrating the change.
175
-
176
- ## Anti-patterns
177
-
178
- - **The mission with no test.** Success stated as understanding rather than as a task leaves nothing able to say the mission is finished.
179
- - **The lesson filed as reference.** A page written to be worked through once sits in `lessons/`, and putting it in `reference/` puts disposable output in the half that gets promoted.
180
- - **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
181
- - **The revisit note with no date.** A line naming what to come back to and not when schedules nothing, so the next session picks from the last record alone, the state the section exists to end.
182
- - **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader hits, and a walker reads only one.
183
- - **The first search result as the source list.** A workspace resting on the first search hit teaches the weakest account of the subject, and nothing in the folder says a stronger one went unsought.
184
- - **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
185
-
186
- ## Template
187
-
188
- ```markdown
189
- ---
190
- title: <Subject>
191
- description: <one line naming what a learner gets from this workspace>
192
- date: <YYYY-MM-DD>
193
- ---
194
-
195
- # <Subject>
196
-
197
- <One line stating the subject.>
198
-
199
- ## Starting point
200
-
201
- <What the learner already knows.>
202
-
203
- ## Success looks like
204
-
205
- - <a specific thing the learner will be able to do>
206
- - <a specific thing the learner will be able to do>
207
-
208
- ## Out of scope
209
-
210
- - <what this workspace deliberately does not cover>
211
- ```
@@ -1,35 +0,0 @@
1
- ---
2
- name: video-craft
3
- description: Why a session composing a video of software needs sourced judgment on captions, zoom, pointer, and audio beyond what HyperFrames' own skills carry, and why every number in it has to trace to a source
4
- ---
5
-
6
- # Video craft requirement
7
-
8
- ## Gap
9
-
10
- Without this skill, a composed video of software gets general motion craft from HyperFrames and nothing on top. Nothing says what a caption says, which moment earns a zoom, how a recorded pointer behaves, or how far music sits under a voice. A render pushes in slowly, narrates the whole flow in one caption, and opens on a slogan card.
11
-
12
- Numbers from recall are the second gap. HyperFrames states its zoom duration with no source, and its default music bed sits closer under a voice than the accessibility guideline asks. A session taking either as given reproduces the defaults that read generic.
13
-
14
- ## Must
15
-
16
- - A caption names only what its frame shows, with its timing, line count, line length, and reading rate traced to published subtitle guidelines
17
- - A zoom lands on an action, aimed from the take's timeline with a sourced push duration, and one pointer clicks inside each recorded target
18
- - The choice of music or silence, the music's level under a voice, and a voiceover's pace each carry a sourced number
19
- - A checker finding is dismissed only after the frame it names is read
20
- - Every number traces to a source in `references/adopted.md`, a conflict between sources names its pick, and the body closes with the practice skill's three closing sections
21
-
22
- ## Must not
23
-
24
- - Restate a rule HyperFrames' own skills carry, such as ease variety, anchoring, click timing, a zoom's scale and dwell, safe margins, or the carve under a voice
25
- - State a number `references/adopted.md` does not trace to a source, or claim loading the skill improves a render before a with-and-without comparison
26
- - Fetch, generate, or install a media file or HyperFrames itself
27
- - Name this repository's demos, branches, or render files, since the body ships to targets holding none of them
28
- - Set pointer smoothing or hiding, which are recorder settings a composition cannot change
29
-
30
- ## Out of scope
31
-
32
- - General motion and composition rules, which `hyperframes-animation` and `hyperframes-creative` own
33
- - Sourcing media, which `media-use` owns
34
- - Recording the take, and loading this skill before it composes, which `record-screencast` owns
35
- - Vertical 9:16 framing, which no skill owns until a project asks for it
@@ -1,96 +0,0 @@
1
- ---
2
- name: video-craft
3
- description: Carries what makes a composed video of software read as designed rather than generic, being captions that name only what the frame shows, which moment earns a zoom and how fast it lands, how a real pointer behaves on a real interface, music or silence and how far under a voice the music sits, and reading a frame before dismissing a checker finding. Every number traces to a source. Use before composing or judging any video, whether a product demo, an explainer, a pull request walkthrough, or a launch clip, when a render reads generic or slow, or when asked "make this video look designed", "is this zoom too slow", "what should this caption say", "should this have music", or "the checker flagged a frame, is it real". Do NOT use for general motion such as easing, speed variety, and click timing, which HyperFrames' `hyperframes-animation` and `hyperframes-creative` carry, to fetch or generate a media file, which is `media-use`, or to record the take, which is `record-screencast`.
4
- metadata:
5
- family: build
6
- ---
7
-
8
- # Video craft
9
-
10
- A session composing a video with no stated direction reaches for defaults, such as a slow push-in, one ease on every move, a centered caption pill, and a slogan intro card. Together they read as generic. This skill carries the judgment specific to a video of software, which HyperFrames' own skills leave out.
11
-
12
- Load `hyperframes-creative` and `hyperframes-animation` first. They own general motion, being ease and speed variety, anchoring, and click timing, and this body names none of their rules.
13
-
14
- ## Scope and sources
15
-
16
- The guidance covers landscape 16:9 video, and vertical 9:16 framing is not covered yet. Read `${CLAUDE_SKILL_DIR}/references/adopted.md` for the source behind every number below, only when extending this guidance or arguing against a rule in it.
17
-
18
- ## Captions name what the frame shows
19
-
20
- - Write each caption about the frame on screen while it shows, never about the step before or the one after. A caption narrating the whole flow describes a frame the viewer is not looking at.
21
- - Name the visible change, such as the card landing or the field filling, rather than the feature's pitch. The pitch belongs in an intro card or the voiceover.
22
- - Start a caption on the first frame of the action it names, and keep it on screen for at least 5/6 of a second and at most 7 seconds.
23
- - Hold a caption to two lines of at most 42 characters, read at no more than 20 characters per second, or 17 for an audience of children. Cut words rather than shorten the hold.
24
- - Place a caption where it covers nothing the frame is about. Move it off the element the step acts on, rather than centering it by default. HyperFrames' studio skill owns the title-safe margins.
25
-
26
- ## A zoom is earned by an action
27
-
28
- - Zoom only on a click, fill, or hover whose result is too small to read at full frame. A navigate, a wait, or a hold has nothing to aim at.
29
- - Aim the zoom at the action's own place and moment. `canon demo run` writes a timeline beside the take with each step's start, end, and target box, so read the zoom off it, never summing holds.
30
- - Run a push that lands on an action no faster than the floor HyperFrames' `viewport-change` rule states, and never past 1 second
31
- - That rule's own range suits an ambient reveal with no action to land on, and reads slow on a push onto a click
32
- - Leave the scale and the dwell after a zoom settles to the `viewport-change` rule, which states both.
33
-
34
- ## A real pointer on a real interface
35
-
36
- - Keep the pointer the take recorded. Never draw a second, synthetic cursor over a real interface, since two pointers on one frame leave the viewer guessing which one acted.
37
- - Check that each click lands inside the target box the timeline records for it. A pointer arriving beside the button it claims to press reads as a fake.
38
-
39
- ## Music, silence, and a voice
40
-
41
- - Choose silence over a music bed that competes with a voiceover. A bed earns its place on a video with no voice, where it carries the pacing between beats.
42
- - Sit music at least 20 dB under the voice. Check `media-use`'s narrated bed default against that floor, since it has sat short of it.
43
- - The mechanism, a carve rather than a flat duck, is `hyperframes-audio`'s
44
- - Keep a captioned voiceover at or under 160 words a minute, since a faster voice forces captions past their reading limit. `hyperframes-creative`'s narration pace sits under that ceiling.
45
-
46
- ## Read the frame before dismissing a finding
47
-
48
- - Open the frame at the timestamp a checker names before calling its finding a false positive, whether the checker is `hyperframes check`, `canon demo frames`, or `read-frames`.
49
- - Report what the frame shows beside the dismissal. A dismissal with no frame read is a guess about the render, and the viewer sees the render.
50
-
51
- ## Excuses and rebuttals
52
-
53
- | Excuse | Rebuttal |
54
- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
55
- | A slow zoom feels cinematic | A push onto an action is interface motion. Past 1 second the viewer waits on the camera instead of watching the action land. |
56
- | The caption explains the whole feature, so it is more useful | A caption about anything but the frame on screen makes the viewer read one thing and watch another. |
57
- | The checker flagged a frame I already know is fine | Knowing is a memory of the composition, not of the render. Open the frame. |
58
- | Music makes it feel finished | Music under a voice that is not 20 dB down masks the words, and the words carry the explanation. |
59
- | A drawn cursor looks cleaner than the recorded one | The recorded pointer is the one that pressed the button. A drawn one is a claim about an action the take already shows. |
60
-
61
- ## Red flags
62
-
63
- - A push onto a click runs longer than 1 second.
64
- - Every move in the composition shares one duration.
65
- - A caption is centered on screen and covers the element the step acts on.
66
- - A caption names a step the frame is not showing.
67
-
68
- ### Timing and checks
69
-
70
- These flags catch a composition built from memory rather than from the take.
71
-
72
- - The zoom's start time was added up by hand while a timeline file sits beside the take.
73
- - Two pointers appear on one frame.
74
- - A checker finding was dismissed and no frame was opened.
75
-
76
- ## Before handing over
77
-
78
- - Every caption names what its frame shows, starts on its action's first frame, and holds within its time and length limits.
79
- - Every zoom aims at a click, fill, or hover read from the timeline, and lands within its duration.
80
- - One pointer is on screen, and each click lands inside its recorded box.
81
- - Music, when present, sits at least 20 dB under any voice, and a captioned voice stays at or under 160 words a minute.
82
- - Every checker finding was either fixed or dismissed with the frame it names read and reported.
83
-
84
- ## What this delegates
85
-
86
- - Easing, speed variety, anchoring, click timing, and every other general motion rule: `hyperframes-animation` and `hyperframes-creative`
87
- - Title-safe margins and timeline layout: `hyperframes-studio`
88
- - The carve that sits music under a voice: `hyperframes-audio`
89
-
90
- ### Media, capture, and reading
91
-
92
- The assets around the composition belong to other skills too.
93
-
94
- - Fetching or generating music, effects, voice, and imagery: `media-use`
95
- - Recording the take and writing its timeline: `record-screencast` through `canon demo run`
96
- - Reading a render frame by frame: `read-frames`
@@ -1,110 +0,0 @@
1
- ---
2
- title: Adopted and declined
3
- description: The source behind every number in the video-craft body, by field, which conflicts between sources were picked and why, and what was declined
4
- ---
5
-
6
- # Adopted and declined
7
-
8
- Each number in the body traces to a source here, read through the `search-craft` method: the field named first, its authorities derived from the kind of body it trusts, and each question searched scoped to those authorities and open beside it. A later session extending the skill adds to this file rather than re-arguing an item settled here.
9
-
10
- ## Captions
11
-
12
- Field: subtitling and captioning. Authorities: broadcasters' and streamers' published subtitle guidelines, and the captioning program that sets educational practice.
13
-
14
- | Rule | Source |
15
- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16
- | On screen for 5/6 of a second to 7 seconds | Netflix's [Timed Text Style Guide: General Requirements](https://partnerhelp.netflixstudios.com/hc/en-us/articles/215758617-Timed-Text-Style-Guide-General-Requirements), a minimum of 20 frames at 24 fps |
17
- | Two lines, 42 characters a line | Netflix's [English (USA) guide](https://partnerhelp.netflixstudios.com/hc/en-us/articles/217350977-English-USA-Timed-Text-Style-Guide) |
18
- | 20 characters per second, 17 for children | The same English (USA) guide, adult and children's programs respectively |
19
- | Never over what the frame is about | The DCMP [Captioning Tip Sheet](https://dcmp.org/learn/225-captioning-tip-sheet): "Placement must not interfere with existing visuals/graphics." |
20
-
21
- ### Start on the first frame of the action
22
-
23
- Netflix's [Subtitle Timing Guidelines](https://partnerhelp.netflixstudios.com/hc/en-us/articles/360051554394-Timed-Text-Style-Guide-Subtitle-Timing-Guidelines) put a subtitle's in-time on the first frame of its audio. A software video's caption names an action rather than a line of speech, so the body keys the in-time on the action's first frame.
24
-
25
- ### Captions name what the frame shows
26
-
27
- No source states this for a software video. It is the operator's read of an unguided render whose caption narrated the whole flow, kept because the timing rules above already assume a caption tied to one moment.
28
-
29
- ## Zoom
30
-
31
- Fields: interface motion design, and screen recording practice. Authorities: design systems that publish motion specs, and the reference documentation of a screen recording tool.
32
-
33
- ### A push onto an action stays under 1 second
34
-
35
- The floor is HyperFrames'. Its `viewport-change` rule states a zoom of 1.0 to 2.0 seconds with the reason beside it, "under 0.8s teleports, over 2.5s drags", and the body points at the rule rather than restating it.
36
-
37
- - Measured: an unguided render pushed in over 2.2 seconds and a second over 1.4 seconds, and the operator judged both slow, so the range's lower half already reads slow on a push onto a click
38
- - Published: Material Design 3's [easing and duration tokens](https://m3.material.io/styles/motion/easing-and-duration/tokens-specs) end at 1000 ms, the top of a band reserved for ambient transitions, so no input-driven transition there runs longer
39
-
40
- ### Zoom on a click
41
-
42
- Screen Studio's [auto zoom guide](https://screen.studio/guide/auto-zoom) keys its zoom on click positions and zooms nowhere a click did not occur.
43
-
44
- ### Conflict, and the pick
45
-
46
- HyperFrames' range and the measured renders disagree on the push onto an action. The body takes the overlap, HyperFrames' teleport floor below and 1 second above, which sits inside HyperFrames' range at its fast end.
47
-
48
- - HyperFrames' full range stays with an ambient reveal, matching Material's own split between input-driven and ambient motion
49
- - A tighter band was declined. Material puts large expressive transitions at 450 to 600 ms, and Nielsen Norman Group's [animation duration article](https://www.nngroup.com/articles/animation-duration/) calls 400 ms "very slow".
50
- - Both write for an interface a user waits on, which a video viewer is not, and that band sits below HyperFrames' teleport floor with nothing measured to show it reads right
51
-
52
- Narrow the band once a composed demo is compared against the unguided renders.
53
-
54
- ## Pointer
55
-
56
- The two pointer rules in the body carry no number. One pointer on a frame and a click landing inside its recorded box both follow from the take recording the real pointer and the timeline recording each target's box.
57
-
58
- ## Audio
59
-
60
- Fields: web accessibility, and audio post-production. Authorities: the W3C's accessibility guidelines, and the audio engineering society's streaming recommendation.
61
-
62
- ### Music at least 20 dB under the voice
63
-
64
- WCAG 2.1 [Success Criterion 1.4.7](https://www.w3.org/WAI/WCAG21/Understanding/low-or-no-background-audio.html) is the source, reading "The background sounds are at least 20 decibels lower than the foreground speech content, with the exception of occasional sounds that last for only one or two seconds."
65
-
66
- HyperFrames' `media-use` sets its narrated bed at a volume of 0.12, about 18 dB under a voice at full scale. The body takes WCAG's 20 dB, since it is the published floor and the bed default sits 2 dB short of it.
67
-
68
- ### Overall loudness is delegated
69
-
70
- The AES [TD1008](https://aes.org/wp-content/uploads/2024/01/20210924_TD1008_v3.13.pdf) streaming recommendation normalizes speech to -18 LUFS with a true peak no higher than -1 dBTP. `media-use` ships -14 and -16 LUFS targets for social and podcast delivery.
71
-
72
- The body states no overall target, since the right one depends on where the video is published and `media-use` owns that operation.
73
-
74
- ## Voiceover
75
-
76
- Field: captioning, for the reading ceiling a voiceover's captions inherit. Authority: the captioning program's presentation rate guidance.
77
-
78
- ### At or under 160 words a minute when captioned
79
-
80
- The DCMP [Captioning Key: Presentation Rate](https://dcmp.org/learn/601-captioning-key---presentation-rate) caps upper-level captions at 160 words a minute.
81
-
82
- - `hyperframes-creative`'s narration reference states 2.5 words a second, 150 a minute, under the ceiling, so the two do not conflict
83
- - An open search of voiceover practitioners put explainers at 140 to 160 words a minute, which agrees
84
- - Narration has no standards body for pace, and the scoped search found none, so the body sets only the ceiling and points at HyperFrames for pace
85
-
86
- ## Declined
87
-
88
- Each item below stays out of the body for the reason given.
89
-
90
- ### Restating HyperFrames' motion rules
91
-
92
- Ease variety, anchoring, click timing, the scale and dwell of a zoom, and title-safe margins are stated in HyperFrames' own skills, which update on their own cadence. A copy here goes stale on theirs.
93
-
94
- ### A loudness target in the body
95
-
96
- See Audio above.
97
-
98
- ### Pointer smoothing and hiding at rest
99
-
100
- Screen Studio's [cursor guide](https://screen.studio/guide/cursor) smooths the pointer and hides it when idle, and its [guide to disabling smooth movement](https://screen.studio/guide/disable-smooth-mouse-movement) turns smoothing off for a dropdown menu.
101
-
102
- Both are recorder settings. A take is composed with its pointer baked into the frames, so a session composing from it cannot change either, and they belong to whatever records the take.
103
-
104
- ### Zoom out before a cut, and a sound effect only on a meaningful click
105
-
106
- Neither has a source, and no operator read stands behind either, so both stay out until one does.
107
-
108
- ### Vertical 9:16 framing
109
-
110
- Every video measured when this skill was written was landscape. Add it when a project asks for vertical video, with its safe areas sourced from the platform's own creator documentation.