@litfamily/litgravity 0.1.1 → 0.1.2

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 (246) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +17 -3
  3. package/README_ko-KR.md +17 -3
  4. package/package.json +1 -1
  5. package/plugin/hooks/lib/lanes.mjs +65 -0
  6. package/plugin/hooks/lib/motion.mjs +34 -5
  7. package/plugin/hooks/lib/reentry.mjs +7 -0
  8. package/plugin/hooks/lib/rewind/brief.mjs +332 -0
  9. package/plugin/hooks/lib/rewind/collect.mjs +328 -0
  10. package/plugin/hooks/lib/rewind/gauge.mjs +55 -0
  11. package/plugin/hooks/lib/rewind/next-step.mjs +77 -0
  12. package/plugin/hooks/lib/rewind/redact.mjs +60 -0
  13. package/plugin/hooks/lib/rewind/transcripts.mjs +211 -0
  14. package/plugin/hooks/lib/routes.mjs +79 -5
  15. package/plugin/hooks/lib/workflow-stack.mjs +213 -0
  16. package/plugin/hooks/post-tool-use.mjs +37 -1
  17. package/plugin/hooks/pre-invocation.mjs +91 -2
  18. package/plugin/hooks/session-start.mjs +26 -3
  19. package/plugin/hooks/stop.mjs +22 -2
  20. package/plugin/hud/looks.mjs +29 -0
  21. package/plugin/hud/render.mjs +234 -12
  22. package/plugin/plugin.json +1 -1
  23. package/plugin/skills/frontend-ui-ux/SKILL.md +12 -1
  24. package/plugin/skills/frontend-ui-ux/kit/components.css +417 -0
  25. package/plugin/skills/frontend-ui-ux/kit/fonts.json +22 -0
  26. package/plugin/skills/frontend-ui-ux/kit/layouts/landing.html +164 -0
  27. package/plugin/skills/frontend-ui-ux/kit/layouts/settings.html +114 -0
  28. package/plugin/skills/frontend-ui-ux/kit/layouts/workspace.html +115 -0
  29. package/plugin/skills/frontend-ui-ux/kit/styles/computational-brutalism.json +227 -0
  30. package/plugin/skills/frontend-ui-ux/kit/styles/field-notes.json +205 -0
  31. package/plugin/skills/frontend-ui-ux/kit/styles/graphite.json +200 -0
  32. package/plugin/skills/frontend-ui-ux/kit/styles/meadow.json +199 -0
  33. package/plugin/skills/frontend-ui-ux/kit/styles/neo-brutalism.json +222 -0
  34. package/plugin/skills/frontend-ui-ux/kit/ui.js +226 -0
  35. package/plugin/skills/frontend-ui-ux/references/house-styles.md +234 -0
  36. package/plugin/skills/frontend-ui-ux/scripts/design-lock.mjs +400 -0
  37. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-lock.mjs +196 -0
  38. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-page.mjs +30 -9
  39. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-rules.mjs +20 -8
  40. package/plugin/skills/frontend-ui-ux/scripts/interface-probe.mjs +42 -9
  41. package/plugin/skills/frontend-ui-ux/scripts/pixel-art.mjs +60 -0
  42. package/plugin/skills/lit-adhd/SKILL.md +157 -0
  43. package/plugin/skills/lit-adhd/references/card-examples.md +101 -0
  44. package/plugin/skills/lit-adhd/references/status-taxonomy.md +32 -0
  45. package/plugin/skills/lit-adhd/scripts/rewind.mjs +5 -0
  46. package/plugin/skills/lit-diagram-drawer/SKILL.md +5 -3
  47. package/plugin/skills/lit-diagram-drawer/references/drawing-rules.md +1 -1
  48. package/plugin/skills/lit-diagram-drawer/references/style-guide.md +21 -12
  49. package/plugin/skills/lit-diagram-drawer/references/type-architecture.md +3 -3
  50. package/plugin/skills/lit-diagram-drawer/references/type-dependency.md +1 -1
  51. package/plugin/skills/lit-diagram-drawer/references/type-tree.md +3 -3
  52. package/plugin/skills/lit-diagram-drawer/references/type-wardley.md +1 -1
  53. package/plugin/skills/lit-diagram-drawer/scripts/diagram-craft-rules.mjs +1 -2
  54. package/plugin/skills/lit-diagram-drawer/scripts/visual-quality.mjs +1 -2
  55. package/plugin/skills/lit-docx/SKILL.md +3 -3
  56. package/plugin/skills/lit-handoff/SKILL.md +1 -0
  57. package/plugin/skills/lit-hijack/SKILL.md +263 -0
  58. package/plugin/skills/lit-hijack/references/capture-and-provenance.md +100 -0
  59. package/plugin/skills/lit-hijack/references/clean-room-build.md +75 -0
  60. package/plugin/skills/lit-hijack/references/distil-and-licence.md +67 -0
  61. package/plugin/skills/lit-hijack/references/gap-and-port-design.md +100 -0
  62. package/plugin/skills/lit-hijack/references/parity-and-report.md +85 -0
  63. package/plugin/skills/lit-hijack/scripts/hijack.mjs +953 -0
  64. package/plugin/skills/lit-plan/SKILL.md +1 -1
  65. package/plugin/skills/lit-pptx/SKILL.md +8 -8
  66. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Bold.ttf +0 -0
  67. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Regular.ttf +0 -0
  68. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/OFL.txt +93 -0
  69. package/plugin/skills/lit-pptx/fonts/provenance.json +32 -1
  70. package/plugin/skills/lit-pptx/references/agents/analyst.md +34 -56
  71. package/plugin/skills/lit-pptx/references/agents/antithesis.md +49 -67
  72. package/plugin/skills/lit-pptx/references/agents/architect.md +38 -51
  73. package/plugin/skills/lit-pptx/references/agents/critic.md +25 -41
  74. package/plugin/skills/lit-pptx/references/agents/synthesizer.md +37 -46
  75. package/plugin/skills/lit-pptx/references/agents/thesis.md +29 -49
  76. package/plugin/skills/lit-pptx/references/anti-slop-checklist.md +119 -145
  77. package/plugin/skills/lit-pptx/references/authoring-guide.md +187 -278
  78. package/plugin/skills/lit-pptx/references/consensus-protocol.md +99 -97
  79. package/plugin/skills/lit-pptx/references/data-display-cookbook.md +36 -137
  80. package/plugin/skills/lit-pptx/references/density-and-fill.md +147 -216
  81. package/plugin/skills/lit-pptx/references/design-system-azure.md +56 -85
  82. package/plugin/skills/lit-pptx/references/direction-step.md +134 -176
  83. package/plugin/skills/lit-pptx/references/examples/01-pitch-signal-ko.md +114 -115
  84. package/plugin/skills/lit-pptx/references/examples/02-pitch-studio-ko.md +66 -66
  85. package/plugin/skills/lit-pptx/references/examples/03-business-review-ledger-ko.md +63 -63
  86. package/plugin/skills/lit-pptx/references/examples/04-business-review-night-en.md +96 -96
  87. package/plugin/skills/lit-pptx/references/examples/05-research-talk-paper-en.md +81 -81
  88. package/plugin/skills/lit-pptx/references/examples/06-lecture-chalk-ko.md +103 -103
  89. package/plugin/skills/lit-pptx/references/examples/07-data-review-night-en.md +100 -98
  90. package/plugin/skills/lit-pptx/references/examples/08-image-led-atlas-ko.md +76 -76
  91. package/plugin/skills/lit-pptx/references/examples/09-briefing-gazette-ko.md +96 -96
  92. package/plugin/skills/lit-pptx/references/examples/10-status-update-ledger-ko.md +80 -80
  93. package/plugin/skills/lit-pptx/references/examples/11-portfolio-studio-en.md +72 -72
  94. package/plugin/skills/lit-pptx/references/examples/12-research-tutorial-chalk-en.md +95 -95
  95. package/plugin/skills/lit-pptx/references/examples/13-engineering-review-computational-brutalism-ko.md +173 -0
  96. package/plugin/skills/lit-pptx/references/examples/14-launch-pitch-neo-brutalism-ko.md +154 -0
  97. package/plugin/skills/lit-pptx/references/examples/15-design-lecture-bauhaus-ko.md +139 -0
  98. package/plugin/skills/lit-pptx/references/examples/16-community-programme-riso-ko.md +158 -0
  99. package/plugin/skills/lit-pptx/references/examples/17-public-data-briefing-newsroom-ko.md +179 -0
  100. package/plugin/skills/lit-pptx/references/interview-protocol.md +83 -102
  101. package/plugin/skills/lit-pptx/references/layout-families.md +161 -265
  102. package/plugin/skills/lit-pptx/references/stages/autopilot.md +30 -70
  103. package/plugin/skills/lit-pptx/references/stages/interview.md +36 -68
  104. package/plugin/skills/lit-pptx/references/stages/plan.md +26 -67
  105. package/plugin/skills/lit-pptx/references/title-treatments.md +93 -145
  106. package/plugin/skills/lit-pptx/references/tonalities/atlas.md +95 -108
  107. package/plugin/skills/lit-pptx/references/tonalities/bauhaus.md +140 -0
  108. package/plugin/skills/lit-pptx/references/tonalities/chalk.md +107 -122
  109. package/plugin/skills/lit-pptx/references/tonalities/computational-brutalism.md +150 -0
  110. package/plugin/skills/lit-pptx/references/tonalities/gazette.md +87 -111
  111. package/plugin/skills/lit-pptx/references/tonalities/ledger.md +96 -125
  112. package/plugin/skills/lit-pptx/references/tonalities/neo-brutalism.md +161 -0
  113. package/plugin/skills/lit-pptx/references/tonalities/newsroom.md +144 -0
  114. package/plugin/skills/lit-pptx/references/tonalities/night.md +104 -131
  115. package/plugin/skills/lit-pptx/references/tonalities/paper.md +114 -130
  116. package/plugin/skills/lit-pptx/references/tonalities/riso.md +137 -0
  117. package/plugin/skills/lit-pptx/references/tonalities/signal.md +96 -103
  118. package/plugin/skills/lit-pptx/references/tonalities/studio.md +81 -112
  119. package/plugin/skills/lit-pptx/scripts/compile-deck.js +4 -6
  120. package/plugin/skills/lit-pptx/scripts/craft_extras.py +135 -91
  121. package/plugin/skills/lit-pptx/scripts/deck_craft.py +1 -1
  122. package/plugin/skills/lit-pptx/scripts/embed_fonts.py +13 -1
  123. package/plugin/skills/lit-pptx/scripts/layout_inventory.py +1 -1
  124. package/plugin/skills/lit-pptx/scripts/learn_template.py +1 -1
  125. package/plugin/skills/lit-pptx/scripts/lib/grid-resolver.js +101 -110
  126. package/plugin/skills/lit-pptx/scripts/lib/layout-resolver.js +9 -15
  127. package/plugin/skills/lit-pptx/scripts/lib/render-pack.js +370 -563
  128. package/plugin/skills/lit-pptx/scripts/lib/slide-grid.js +104 -0
  129. package/plugin/skills/lit-pptx/scripts/lib/template-registry.js +57 -6
  130. package/plugin/skills/lit-pptx/scripts/qa_deck.py +6 -6
  131. package/plugin/skills/lit-pptx/scripts/render_pages.py +31 -0
  132. package/plugin/skills/lit-pptx/scripts/validate_pptx.py +1 -1
  133. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v1.md +167 -191
  134. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v2.md +117 -166
  135. package/plugin/skills/lit-pptx/specs/template-enrollment-contract.md +307 -330
  136. package/plugin/skills/lit-pptx/templates/tonalities/atlas/pack.yaml +1 -1
  137. package/plugin/skills/lit-pptx/templates/tonalities/bauhaus/pack.yaml +98 -0
  138. package/plugin/skills/lit-pptx/templates/tonalities/chalk/pack.yaml +1 -1
  139. package/plugin/skills/lit-pptx/templates/tonalities/computational-brutalism/pack.yaml +99 -0
  140. package/plugin/skills/lit-pptx/templates/tonalities/gazette/pack.yaml +1 -1
  141. package/plugin/skills/lit-pptx/templates/tonalities/ledger/pack.yaml +1 -1
  142. package/plugin/skills/lit-pptx/templates/tonalities/neo-brutalism/pack.yaml +107 -0
  143. package/plugin/skills/lit-pptx/templates/tonalities/newsroom/pack.yaml +99 -0
  144. package/plugin/skills/lit-pptx/templates/tonalities/night/pack.yaml +1 -1
  145. package/plugin/skills/lit-pptx/templates/tonalities/paper/pack.yaml +1 -1
  146. package/plugin/skills/lit-pptx/templates/tonalities/riso/pack.yaml +99 -0
  147. package/plugin/skills/lit-pptx/templates/tonalities/signal/pack.yaml +2 -2
  148. package/plugin/skills/lit-pptx/templates/tonalities/studio/pack.yaml +1 -1
  149. package/plugin/skills/lit-schematic/SKILL.md +114 -0
  150. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/build.mjs +38 -0
  151. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/scene.mjs +133 -0
  152. package/plugin/skills/lit-schematic/examples/journal-adsorption-rig/build.mjs +87 -0
  153. package/plugin/skills/lit-schematic/examples/pid-dosing-skid/build.mjs +85 -0
  154. package/plugin/skills/lit-schematic/references/cutaway-outputs.md +70 -0
  155. package/plugin/skills/lit-schematic/references/isometric-craft.md +101 -0
  156. package/plugin/skills/lit-schematic/references/journal-figures.md +72 -0
  157. package/plugin/skills/lit-schematic/references/kit-api.md +134 -0
  158. package/plugin/skills/lit-schematic/references/pfd-and-layout.md +53 -0
  159. package/plugin/skills/lit-schematic/references/pid-drafting.md +103 -0
  160. package/plugin/skills/lit-schematic/references/pid-symbols.md +163 -0
  161. package/plugin/skills/lit-schematic/references/verification.md +100 -0
  162. package/plugin/skills/lit-schematic/scripts/doctor.mjs +57 -0
  163. package/plugin/skills/lit-schematic/scripts/lib/figure.mjs +81 -0
  164. package/plugin/skills/lit-schematic/scripts/lib/fonts.mjs +27 -0
  165. package/plugin/skills/lit-schematic/scripts/lib/geom.mjs +113 -0
  166. package/plugin/skills/lit-schematic/scripts/lib/interactive.mjs +292 -0
  167. package/plugin/skills/lit-schematic/scripts/lib/isa.mjs +115 -0
  168. package/plugin/skills/lit-schematic/scripts/lib/iso.mjs +719 -0
  169. package/plugin/skills/lit-schematic/scripts/lib/legend-sheet.mjs +162 -0
  170. package/plugin/skills/lit-schematic/scripts/lib/pid.mjs +937 -0
  171. package/plugin/skills/lit-schematic/scripts/lib/png.mjs +132 -0
  172. package/plugin/skills/lit-schematic/scripts/lib/qa-core.mjs +658 -0
  173. package/plugin/skills/lit-schematic/scripts/lib/route.mjs +218 -0
  174. package/plugin/skills/lit-schematic/scripts/lib/sheet.mjs +890 -0
  175. package/plugin/skills/lit-schematic/scripts/lib/svg.mjs +82 -0
  176. package/plugin/skills/lit-schematic/scripts/lib/theme.mjs +115 -0
  177. package/plugin/skills/lit-schematic/scripts/motion.mjs +129 -0
  178. package/plugin/skills/lit-schematic/scripts/qa.mjs +92 -0
  179. package/plugin/skills/lit-schematic/scripts/render.mjs +233 -0
  180. package/plugin/skills/lit-schematic/scripts/scaffold.mjs +60 -0
  181. package/plugin/skills/lit-scientific-visualization/SKILL.md +17 -6
  182. package/plugin/skills/lit-typographic-motion/SKILL.md +58 -48
  183. package/plugin/skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES +13 -2
  184. package/plugin/skills/lit-typographic-motion/engine/blender/runner.py +218 -0
  185. package/plugin/skills/lit-typographic-motion/engine/core/presets.mjs +1 -1
  186. package/plugin/skills/lit-typographic-motion/engine/node/analysis.mjs +65 -1
  187. package/plugin/skills/lit-typographic-motion/engine/node/assets.mjs +298 -0
  188. package/plugin/skills/lit-typographic-motion/engine/node/blender.mjs +143 -0
  189. package/plugin/skills/lit-typographic-motion/engine/node/board.mjs +136 -0
  190. package/plugin/skills/lit-typographic-motion/engine/node/brief.mjs +7 -1
  191. package/plugin/skills/lit-typographic-motion/engine/node/chrome.mjs +9 -12
  192. package/plugin/skills/lit-typographic-motion/engine/node/cover-assets.mjs +5 -3
  193. package/plugin/skills/lit-typographic-motion/engine/node/cover-capture.mjs +7 -6
  194. package/plugin/skills/lit-typographic-motion/engine/node/cover-treatment.mjs +37 -4
  195. package/plugin/skills/lit-typographic-motion/engine/node/cover.mjs +19 -8
  196. package/plugin/skills/lit-typographic-motion/engine/node/done.mjs +45 -6
  197. package/plugin/skills/lit-typographic-motion/engine/node/frame-worker.mjs +7 -5
  198. package/plugin/skills/lit-typographic-motion/engine/node/gallery.mjs +121 -0
  199. package/plugin/skills/lit-typographic-motion/engine/node/host.mjs +34 -0
  200. package/plugin/skills/lit-typographic-motion/engine/node/house.mjs +44 -0
  201. package/plugin/skills/lit-typographic-motion/engine/node/look.mjs +34 -20
  202. package/plugin/skills/lit-typographic-motion/engine/node/pipeline.mjs +19 -9
  203. package/plugin/skills/lit-typographic-motion/engine/node/scaffold.mjs +210 -0
  204. package/plugin/skills/lit-typographic-motion/engine/node/score.mjs +639 -0
  205. package/plugin/skills/lit-typographic-motion/engine/node/sound-cli.mjs +21 -4
  206. package/plugin/skills/lit-typographic-motion/engine/node/sound.mjs +127 -29
  207. package/plugin/skills/lit-typographic-motion/engine/node/stage-capture.mjs +7 -6
  208. package/plugin/skills/lit-typographic-motion/engine/node/stage-gate.mjs +59 -5
  209. package/plugin/skills/lit-typographic-motion/engine/node/stage-qa.mjs +141 -9
  210. package/plugin/skills/lit-typographic-motion/engine/node/stage-serve.mjs +28 -5
  211. package/plugin/skills/lit-typographic-motion/engine/node/stage.mjs +82 -14
  212. package/plugin/skills/lit-typographic-motion/engine/node/styles.mjs +213 -0
  213. package/plugin/skills/lit-typographic-motion/engine/node/treatment.mjs +311 -10
  214. package/plugin/skills/lit-typographic-motion/engine/stage/cover-init.js +14 -2
  215. package/plugin/skills/lit-typographic-motion/engine/stage/init.js +11 -1
  216. package/plugin/skills/lit-typographic-motion/engine/stage/qa.js +6 -1
  217. package/plugin/skills/lit-typographic-motion/engine/stage/stage-kit.js +83 -0
  218. package/plugin/skills/lit-typographic-motion/engine/vendor/three/LICENSE +21 -0
  219. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/environments/RoomEnvironment.js +144 -0
  220. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/geometries/RoundedBoxGeometry.js +155 -0
  221. package/plugin/skills/lit-typographic-motion/engine/vendor/three/three.module.js +54571 -0
  222. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/expected.json +69 -0
  223. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/index.html +139 -0
  224. package/plugin/skills/lit-typographic-motion/recipes/orbit-loop/expected.json +6 -4
  225. package/plugin/skills/lit-typographic-motion/recipes/painted-light/expected.json +4 -2
  226. package/plugin/skills/lit-typographic-motion/recipes/weight-tide/expected.json +7 -5
  227. package/plugin/skills/lit-typographic-motion/references/cover.md +394 -443
  228. package/plugin/skills/lit-typographic-motion/references/craft-loop.md +57 -87
  229. package/plugin/skills/lit-typographic-motion/references/depth.md +122 -0
  230. package/plugin/skills/lit-typographic-motion/references/look.md +94 -129
  231. package/plugin/skills/lit-typographic-motion/references/runtime.md +58 -91
  232. package/plugin/skills/lit-typographic-motion/references/sound.md +130 -99
  233. package/plugin/skills/lit-typographic-motion/references/stage.md +190 -215
  234. package/plugin/skills/lit-typographic-motion/references/studio.md +245 -0
  235. package/plugin/skills/lit-typographic-motion/references/style-bibles.md +108 -97
  236. package/plugin/skills/lit-typographic-motion/references/treatment.md +191 -143
  237. package/plugin/skills/lit-typographic-motion/scripts/motion-doctor.mjs +17 -5
  238. package/plugin/skills/lit-typographic-motion/scripts/motion.mjs +47 -7
  239. package/plugin/skills/lit-typographic-motion/styles/paper.json +41 -0
  240. package/plugin/skills/lit-typographic-motion/styles/swiss-signal.json +41 -0
  241. package/plugin/skills/lit-typographic-motion/styles/terminalcore.json +42 -0
  242. package/plugin/skills/lit-typographic-motion/styles/tidal.json +41 -0
  243. package/plugin/skills/litresearch/SKILL.md +1 -0
  244. package/plugin/skills/readme-studio/SKILL.md +2 -0
  245. package/plugin/skills/review-work/SKILL.md +1 -1
  246. package/plugin/skills/start-work/SKILL.md +1 -1
@@ -1,275 +1,251 @@
1
1
  # Markdown Slide Specification v1
2
2
 
3
- > **Status:** Base contract, extended by `markdown-slide-spec-v2.md`. A deck written only with the
4
- > constructs below compiles to a `slide-ast-v1` document, byte for byte what it produced before v2 existed.
5
- > v2 adds placement (`region`, `columns`, `box`, `shape`), slide-local keys, variants and the open layout set.
6
- > The one v1 non-goal that v2 reverses is free-form absolute positioning (section 11).
7
- > **Reference implementation:** `scripts/lib/markdown-loader.js`, `directive-parser.js`, `slide-ast.js`,
8
- > `spec-validator.js`. **Schema:** `specs/slide-ast-v1.schema.json`.
3
+ > **Status:** Superseded by `markdown-slide-spec-v2.md`, and still valid. This document
4
+ > defines the v1 contract; a deck written entirely to it compiles to a `slide-ast-v1`
5
+ > document exactly as before. v2 is additive — read it for placement (`region`,
6
+ > `columns`, `box`, `shape`), variants, and the open layout set. The one non-goal v2
7
+ > reverses is §11's ban on free-form absolute positioning.
8
+ > **Date:** 2026-04-19
9
+
10
+ The executive/research profile below is a backward-compatible authoring profile. It composes existing v1 blocks and does not add coordinates, CSS, directives, or AST types.
9
11
 
10
12
  ## Purpose
11
13
 
12
- The dialect is the single authoring source for slide decks. It is a constrained Markdown plus fenced
13
- directives, built to be:
14
+ Define a constrained Markdown + directive dialect that serves as the single authoring source for PPTX slide decks. The dialect must be:
15
+
16
+ 1. **LLM-friendly** — predictable structure, easy for agents to generate and edit.
17
+ 2. **Precision-first** — compiles into a versioned intermediate AST that preserves layout intent.
18
+ 3. **Template-aware** — resolves against enrolled template contracts, not hardcoded behavior.
14
19
 
15
- 1. **Easy for an agent to write and edit.** The structure is predictable: one frontmatter block, then
16
- slide chunks that each start with a `layout:` line.
17
- 2. **Exact.** It compiles into a versioned AST that keeps the author's intent (layout, blocks, order), and a
18
- violation stops the compile with a message that names the slide.
19
- 3. **Design-independent.** The source carries structure and words. A tonality pack or a template contract
20
- owns fonts, colours, geometry and decoration.
20
+ ## 1. Deck Structure
21
21
 
22
- ## 1. Deck structure
22
+ A deck source file is a single Markdown file with:
23
23
 
24
- A deck is one Markdown file made of a frontmatter block and one or more slide chunks:
24
+ 1. **YAML frontmatter** (required) — deck-level metadata enclosed in `---`.
25
+ 2. **Slide sections** — separated by `---` horizontal rules. Each section contains a layout directive and slide content.
25
26
 
26
- ```markdown
27
+ ```
27
28
  ---
28
29
  template: MY-BRAND
29
- title: 세탁 서비스 분기 보고
30
- date: 2026.10.05
31
- department: 운영팀
32
- presenter: 예시 발표자
30
+ title: Deck Title
31
+ date: 2026.04.19
32
+ department: Department
33
+ presenter: Name
33
34
  ---
34
35
 
35
36
  ---
36
37
  layout: cover
37
38
 
38
- # 세탁 서비스 분기 보고
39
+ # Cover Title
39
40
  ---
40
41
 
41
42
  ---
42
43
  layout: content
43
44
 
44
- ## 접수와 처리 현황
45
+ ## Section Title
45
46
 
46
- - 3분기 접수 12,400건
47
- - 전분기 대비 +8%
47
+ - Bullet 1
48
+ - Bullet 2
48
49
  ---
49
50
  ```
50
51
 
51
- The source must start with `---`. A missing opening fence, an unclosed frontmatter and a missing `title`
52
- each stop the compile (`Deck must start with YAML frontmatter (---)`, `Frontmatter must be closed with
53
- ---`, `Frontmatter must declare a 'title' field`).
54
-
55
- ## 2. Frontmatter
52
+ ## 2. YAML Frontmatter
56
53
 
57
- The frontmatter is flat `key: value` text. A value may be wrapped in single or double quotes.
54
+ Required fields:
58
55
 
59
- | Field | Required | Description |
60
- |---|---|---|
61
- | `title` | yes | deck title |
62
- | `template` or `tonality` | one of the two | the enrolled template name, or the tonality id the deck was written for |
63
- | `date`, `department`, `presenter` | no | metadata the design may print on a cover |
64
- | any other key | no | carried into `deck.metadata` (`density`, `variance`, `canvas`, `faces`, `notice`, `data`, `accent`, `font`, `background` are read by the engine) |
56
+ | Field | Type | Required | Description |
57
+ |-------|------|----------|-------------|
58
+ | `template` | string | yes | Enrolled template name (e.g. `MY-BRAND`) |
59
+ | `title` | string | yes | Deck title |
60
+ | `date` | string | no | Presentation date |
61
+ | `department` | string | no | Department name |
62
+ | `presenter` | string | no | Presenter name |
65
63
 
66
- A deck that names a `tonality` records `tonality:<id>` as its template in the AST. The render step needs the
67
- design chosen: `--template <NAME>`, `--tonality <id>`, or a `tonality:` line in the frontmatter.
64
+ ## 3. Slide Separators
68
65
 
69
- ## 3. Slide separators
70
-
71
- A line that holds only `---` ends one chunk and starts the next. The first chunk after the frontmatter is
72
- usually empty and is skipped. Every non-empty chunk starts with a `layout:` line and a line break:
73
-
74
- ```
75
- layout: <name>
76
- ```
66
+ Slides are delimited by `---` on its own line (standard Markdown horizontal rule). The content between two `---` markers is a single slide section.
77
67
 
78
- A chunk without it stops the compile (`Slide chunk must start with a 'layout:' directive`). A horizontal
79
- rule inside a slide splits that slide, which also leaves the second half with no `layout:` line. Pipe-table
80
- separator rows (`|---|---|`) are safe because the dashes share their line with pipes.
68
+ Each slide section starts with a `layout` directive on the first non-empty line, followed by the slide content.
81
69
 
82
- ## 4. Allowed Markdown subset
70
+ ## 4. Allowed Markdown Subset
83
71
 
84
72
  ### 4.1 Permitted constructs
85
73
 
86
74
  | Construct | Syntax | Notes |
87
- |---|---|---|
88
- | Headings | `#`, `##`, `###` | `#` on cover and closing, `##` on a content title, `###` opens a summary group |
89
- | Bullets | `- item` | one level; a bold-only bullet (`- **Heading**`) opens a group |
90
- | Bold | `**text**` | group headings and run-in labels |
91
- | Numbered items | `(1) text` | typed numbers in parentheses, indented under a group heading |
92
- | Tables | pipe table | first row headers, a separator row, then data rows |
93
- | Table caption | a `>` line under the table | becomes a `table-caption` block |
94
- | Images | `![alt](path)` on a line of its own | the alt text becomes the visible figure caption |
95
- | Links | `[label](https://...)` | in a table cell, drawn as an external hyperlink |
96
- | Directive blocks | `::: name` ... `:::` | section 5 |
75
+ |-----------|--------|-------|
76
+ | Headings | `#`, `##`, `###` | Level 1 for cover/closing titles, Level 2 for slide titles, Level 3 for sub-headings |
77
+ | Bullet lists | `- item` | Level 1 bullets |
78
+ | Bold text | `**text**` | Within list items for section headers |
79
+ | Numbered items | `(1) text` | Manual numbering with parenthesized Arabic numerals |
80
+ | Tables | `\| ... \|` | Standard Markdown pipe tables |
81
+ | Images | `![alt](path)` | With relative or absolute paths |
82
+ | Table links | `[label](https://...)` | Rendered as a clickable external PPTX hyperlink in table cells |
83
+ | Fenced blocks | `::: type ... :::` | Directive blocks (see §5) |
97
84
 
98
85
  ### 4.2 Forbidden constructs
99
86
 
100
- The parser rejects these at parse time with a slide index and a line number inside the slide:
87
+ The following are **rejected at parse time** with explicit errors:
101
88
 
102
89
  | Forbidden | Reason |
103
- |---|---|
104
- | raw HTML tags `div span table thead tbody tr td th section article header footer nav main aside style script` | would bypass the design contract |
105
- | `<style>` blocks | CSS cannot travel through a slide file |
106
- | inline `style="..."` attributes | arbitrary positioning breaks the layout contract |
107
- | a `:::` block inside a `:::` block | ambiguous nesting (v2 allows a longer outer fence) |
108
- | arbitrary CSS classes | layout comes from the template |
109
-
110
- ## 5. Directive blocks
111
-
112
- A directive is a fenced block. The open line is `::: <name>` (v2 adds attributes) and the close line is
113
- `:::` of the same length.
114
-
115
- | Directive | Purpose | Where it applies |
116
- |---|---|---|
117
- | `main-box` | bordered callout at the foot of the slide | `main` |
118
- | `kpi-table` | headline-number table | `content`, `main`, `summary` |
119
- | `chart` | native chart from a pipe table | wherever a table fits (v2 section 9) |
120
- | `image` | an image with its caption | `content`, `main`, `summary` |
121
- | `key-message` | one-line lead under the title | `content`, `main`, `summary` |
122
- | `notes` | speaker or footnote text | `content`, `section` |
123
-
124
- `summary-group` is a block type the parser builds from `###` headings; the author never writes it as a
125
- directive.
90
+ |-----------|--------|
91
+ | Raw HTML (`<div>`, `<span>`, etc.) | Bypasses template layout contracts |
92
+ | `<style>` blocks | CSS escapes break PPTX fidelity |
93
+ | Inline `style=` attributes | Arbitrary positioning breaks layout |
94
+ | Nested fenced blocks (`:::` inside `:::`) | Ambiguous directive nesting |
95
+ | Arbitrary CSS classes | Layout must come from template contracts |
96
+
97
+ ## 5. Directive Blocks
98
+
99
+ Directives use fenced blocks with `:::` delimiters. Each directive type has a specific contract.
100
+
101
+ ### 5.1 v1 Directive Set
102
+
103
+ | Directive | Purpose | Allowed in layouts |
104
+ |-----------|---------|--------------------|
105
+ | `main-box` | Bordered text box at bottom of slide | `main` |
106
+ | `summary-group` | Grouped summary content (top/bottom) | `summary` |
107
+ | `kpi-table` | Key Performance Indicator table | `main`, `content` |
108
+ | `image` | Positioned image with caption | `content`, `main` |
109
+ | `notes` | Speaker/footnotes | `content`, `main` |
110
+
111
+ ### 5.2 Directive Syntax
126
112
 
127
113
  ```
128
114
  ::: main-box
129
- 처리 지연은 주말 접수분에 몰려 있다.
115
+ Text content for the bordered box.
130
116
  :::
117
+ ```
131
118
 
119
+ ```
132
120
  ::: kpi-table
133
- | 지표 | 목표 | 실적 |
134
- |---|---|---|
135
- | 접수 | 12,000 | 12,400 |
121
+ | Metric | Target | Actual |
122
+ |--------|--------|--------|
123
+ | Revenue | 5000억 | 5450억 |
136
124
  :::
137
125
  ```
138
126
 
139
- Nesting rules: a block closes before another of the same fence length opens. The error names the line.
140
- A directive name that is not in the table becomes a block of that type, and the AST validator rejects it
141
- for any layout that does not list it (`block type "weird" is not allowed ... Allowed: ...`).
127
+ ```
128
+ ::: notes
129
+ Source: Internal data, Q1 2026.
130
+ :::
131
+ ```
142
132
 
143
- ## 6. Layouts
133
+ ### 5.3 Nesting Rules
144
134
 
145
- ### 6.1 The v1 layouts
135
+ - Directive blocks **MUST NOT** be nested inside other directive blocks.
136
+ - Each `:::` open must have a matching `:::` close before another `:::` open.
137
+ - Violation produces a parse error with the offending line number.
146
138
 
147
- | Layout | Purpose | Blocks it accepts |
148
- |---|---|---|
149
- | `cover` | opening slide | `title` |
150
- | `content` | title plus body | `title`, `key-message`, `body`, `image`, `notes`, `kpi-table`, `figure-caption`, `table-caption` |
151
- | `main` | content plus an optional callout | `content` blocks without `notes`, plus `main-box` |
152
- | `summary` | two grouped blocks | `title`, `key-message`, `summary-group`, `image`, `kpi-table`, captions |
153
- | `section` | divider | `title`, `notes` |
154
- | `closing` | final slide | `title` |
139
+ ## 6. Layout Types
155
140
 
156
- The accepted-block column comes from `LAYOUT_BLOCKS` in `spec-validator.js`; placement blocks (`box`,
157
- `shape`, `columns`) pass on every layout. The renderer applies a second check against the chosen
158
- template's own capability list.
141
+ ### 6.1 v1 Approved Layouts
159
142
 
160
- ### 6.2 Content rules per layout
143
+ | Layout | Purpose | Required blocks |
144
+ |--------|---------|-----------------|
145
+ | `cover` | Opening slide | title (level 1) |
146
+ | `content` | Standard title + body | title (level 2), body |
147
+ | `main` | Content with optional bordered box | title (level 2), body, optional `main-box` |
148
+ | `summary` | Two-group hierarchical summary | title (level 2), summary-groups via `###` headings |
149
+ | `closing` | Thank-you slide | title (level 1) |
161
150
 
162
- - `cover`: one `#` heading and no body.
163
- - `content`: one `##` heading, then bullets, a table or an image.
164
- - `main`: one `##` heading, a body, and optionally one `::: main-box`.
165
- - `summary`: one `##` heading, then `###` groups. The first group is `position: "top"`, the second
166
- `"bottom"`, a third and later `group-N`.
167
- - `section` and `closing`: a heading only.
151
+ ### 6.2 Layout-specific content rules
168
152
 
169
- Under a tonality the same names are accepted as legacy layouts and read as families (`content` and `main`
170
- become `text-column`, `summary` becomes `comparison`); the pack's own families are listed in
171
- `references/layout-families.md`.
153
+ - `cover`: Exactly one `#` heading. No body lists.
154
+ - `content`: One `##` heading. Body with bullet lists or tables.
155
+ - `main`: One `##` heading. Body with bullet lists. Optional `::: main-box`.
156
+ - `summary`: One `##` heading. Content organized under `###` sub-headings. The first `###` group maps to the top position, the second maps to the bottom position.
157
+ - `closing`: Exactly one `#` heading. No body content.
172
158
 
173
- ## 7. Bullet hierarchy
159
+ ## 7. Bullet Hierarchy
174
160
 
175
- Body text has two levels and plain lines:
161
+ The template uses a two-level hierarchy:
176
162
 
163
+ **Level 1 — Section headers:**
177
164
  ```
178
- - **Section title**
179
- (1) Detail item
180
- (2) Detail item
181
- - A plain bullet
182
- A plain line is kept as text.
165
+ - **Section Title**
183
166
  ```
167
+ Rendered as bold bullet with `•` character.
184
168
 
185
- | Source | AST item |
186
- |---|---|
187
- | `- **Heading**` | `{"type": "section", "heading", "children"}` |
188
- | `(N) text` | `{"type": "numbered", "text"}`, attached to the open section when one exists |
189
- | `- text` | `{"type": "bullet", "text", "level": 1}` |
190
- | any other line | `{"type": "text", "text"}` |
191
- | `![alt](path)` | `{"type": "image", ...}` |
169
+ **Level 2 — Numbered sub-items:**
170
+ ```
171
+ (1) Detail item 1
172
+ (2) Detail item 2
173
+ ```
174
+ Rendered as indented numbered items with `(1)`, `(2)` format.
192
175
 
193
- A bold lead-in that continues on the same line (`- **요약:** 방문이 늘었다`) is an ordinary bullet whose bold
194
- run is a label.
176
+ Indentation for level 2 items is 2 spaces.
195
177
 
196
- ## 8. Failure behaviour
178
+ ## 8. Failure Behavior
197
179
 
198
180
  ### 8.1 Parse errors
199
181
 
200
- 1. Stop at the first violation; the compile writes no partial output.
201
- 2. Name the slide (0-based index in parse errors) and the line counted inside the slide's content.
202
- 3. Name the violation (`Arbitrary HTML is not allowed ...`, `Unclosed directive block`).
182
+ When the parser encounters a forbidden construct:
183
+
184
+ 1. **Stop parsing immediately** — do not silently skip or degrade.
185
+ 2. **Report the file path**, slide index, and approximate **line number**.
186
+ 3. **Name the specific violation** (e.g., "arbitrary HTML `<div>` not allowed", "nested directives at line 42").
203
187
 
204
188
  ### 8.2 Validation errors
205
189
 
206
- 1. Reject the whole deck.
207
- 2. Name the slide (0-based) and the block (`Slide 0 (layout: cover): block type "body" is not supported. Allowed: title, box, shape, columns`).
208
- 3. List the allowed block types.
209
-
210
- ## 9. AST output contract
211
-
212
- The compiler emits JSON that conforms to `slide-ast-v1.schema.json`. A deck of the small example above
213
- compiles to:
214
-
215
- ```json
216
- {
217
- "astVersion": "slide-ast-v1",
218
- "version": "1.0.0",
219
- "deck": {"template": "AZURE-PRO", "title": "세탁 서비스 분기 보고", "metadata": {"date": "2026.10.05"}},
220
- "slides": [
221
- {"index": 0, "layout": "main", "blocks": [
222
- {"type": "title", "content": "접수와 처리 현황", "level": 2},
223
- {"type": "kpi-table", "headers": ["구분", "건수"], "rows": [["접수", "12,400"]], "caption": "표 1. 3분기 접수 (예시 데이터)"},
224
- {"type": "table-caption", "caption": "표 1. 3분기 접수 (예시 데이터)"},
225
- {"type": "body", "items": [{"type": "section", "heading": "접수량", "children": [{"type": "numbered", "text": "3분기 접수 12,400건"}]}]},
226
- {"type": "main-box", "content": "처리 지연은 주말 접수분에 몰려 있다."}
227
- ]}
228
- ]
229
- }
230
- ```
190
+ When the compiled AST violates the schema:
191
+
192
+ 1. **Reject the entire deck** — do not produce partial output.
193
+ 2. **Report which slide and which block** failed validation.
194
+ 3. **Name the schema constraint** that was violated.
195
+
196
+ ## 9. AST Output Contract
197
+
198
+ The compiler emits a JSON object conforming to `slide-ast-v1.schema.json`.
199
+
200
+ Required top-level fields:
201
+
202
+ | Field | Type | Description |
203
+ |-------|------|-------------|
204
+ | `astVersion` | string | Must be `"slide-ast-v1"` |
205
+ | `version` | string | Schema version (semver) |
206
+ | `deck` | object | Template name, title, metadata |
207
+ | `slides` | array | Ordered array of slide objects |
208
+
209
+ Each slide object must have:
210
+
211
+ | Field | Type | Description |
212
+ |-------|------|-------------|
213
+ | `index` | number | 0-based slide position |
214
+ | `layout` | string | One of the approved layout types |
215
+ | `blocks` | array | Content blocks in order |
231
216
 
232
- | Top-level field | Meaning |
233
- |---|---|
234
- | `astVersion` | `"slide-ast-v1"`, or `"slide-ast-v2"` once the deck places content (v2 section 1) |
235
- | `version` | `1.0.0` or `2.0.0` |
236
- | `deck` | `template`, `title`, optional `metadata` |
237
- | `slides` | ordered array of `{index, layout, blocks}` (and `meta` in v2) |
217
+ Each block must have:
238
218
 
239
- Block types: `title`, `body`, `main-box`, `summary-group`, `kpi-table`, `image`, `notes`, `key-message`,
240
- `figure-caption`, `table-caption`. Inside one text segment a table's block comes before the body, in that
241
- order, whatever the source order. An image line adds a `figure-caption` block when its alt text is non-empty.
219
+ | Field | Type | Description |
220
+ |-------|------|-------------|
221
+ | `type` | string | Block type: `title`, `body`, `main-box`, `summary-group`, `kpi-table`, `image`, `notes` |
222
+ | `content` or `items` | varies | Block payload |
242
223
 
243
- ## 10. Relationship to templates
224
+ ## 10. Relationship to Enrolled Templates
244
225
 
245
- The AST is design-independent. It states intent (layout, blocks, content), and the template registry plus
246
- the layout resolver turn it into positions at render time. Consequences:
226
+ The AST is **template-independent**. It describes intent (layout, content structure), not pixel positions. Template-specific rendering (fonts, colors, positions, decorations) is resolved by the template registry and layout resolver at render time.
247
227
 
248
- - The same AST can render through different designs.
249
- - An unsupported layout or block for the chosen design stops the compile with the available names. No
250
- silent fallback exists.
251
- - A template or pack declares which layouts and blocks it supports.
228
+ This means:
229
+ - The same AST can theoretically render through different enrolled templates.
230
+ - Template enrollment contracts declare which layouts and blocks they support.
231
+ - A deck targeting an unsupported layout/block for a given template produces a clear error, not a fallback.
252
232
 
253
233
  ### 10.1 Evidence-oriented compositions
254
234
 
255
- These are compositions of existing blocks, so every design that draws the blocks draws them:
235
+ Enrolled templates may advertise these semantic compositions of existing blocks:
256
236
 
257
- - **figure plus interpretation:** `image` + `figure-caption` + a body that interprets it;
258
- - **table plus decision takeaway:** a table (or `kpi-table`) + `table-caption` + a body takeaway;
259
- - **source capture:** `image` + `figure-caption` carrying locator and source + a body that states relevance;
260
- - **two-record appendix evidence:** a title and body or `summary-group` with at most two records, each with
261
- its DOI or canonical link.
237
+ - **figure plus interpretation:** `image` + `figure-caption` + body interpretation;
238
+ - **table plus decision takeaway:** table/`kpi-table` + `table-caption` + body takeaway;
239
+ - **source capture:** `image` + `figure-caption` containing locator/source + body relevance and data basis;
240
+ - **two-record appendix evidence:** title/body or `summary-group`, with no more than two records and DOI/canonical links when available.
262
241
 
263
- For an image used as evidence, the alt text is the visible caption: a figure number plus `Source:` or
264
- `출처:`. A `>` line right after a table is its caption and source. Appendix link fields use
265
- `[label](https://...)` in a table cell, so the file carries an external hyperlink relationship. The gate
266
- reads all three (evidence binding, appendix links) from the finished file.
242
+ For a Markdown image used as evidence, alt text is the visible figure caption and should contain a figure number plus `Source:`/`출처:`. A blockquote immediately after a table is its visible table caption/source. Appendix DOI/canonical/raw URL fields use `[label](https://...)` in table cells so the PPTX contains an external hyperlink relationship. These requirements reuse existing parser and renderer behavior.
267
243
 
268
- ## 11. Non-goals of v1
244
+ ## 11. Explicit Non-Goals for v1
269
245
 
270
- - Full compatibility with other slide dialects.
271
- - Arbitrary CSS in authoring input.
272
- - Free-form absolute positioning in Markdown (reversed by v2 section 5).
246
+ - Full Marp compatibility.
247
+ - Arbitrary CSS as part of authoring input.
248
+ - Free-form absolute positioning in Markdown.
273
249
  - Silent fallback or degradation for unsupported constructs.
274
250
  - Raw HTML passthrough.
275
- - Scripts or interactive content.
251
+ - JavaScript or interactive content.