kitfly 0.1.2 → 0.2.1

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 (209) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/README.md +63 -16
  3. package/VERSION +1 -1
  4. package/dist/_raw/content/deployment/preflight.md +134 -0
  5. package/dist/_raw/content/deployment/recipes/aws-s3.md +128 -0
  6. package/dist/_raw/content/deployment/recipes/cloudflare-pages.md +73 -0
  7. package/dist/_raw/content/deployment/recipes/cloudflare-r2.md +156 -0
  8. package/dist/_raw/content/deployment/recipes/fly-io.md +57 -0
  9. package/dist/_raw/content/deployment/recipes/github-pages.md +112 -0
  10. package/dist/_raw/content/deployment/recipes/netlify.md +99 -0
  11. package/dist/_raw/content/deployment/recipes/vercel.md +88 -0
  12. package/dist/_raw/content/deployment/secrets-and-env-vars.md +75 -0
  13. package/dist/_raw/content/deployment.md +128 -0
  14. package/dist/_raw/content/guide/approaches.md +182 -0
  15. package/dist/_raw/content/guide/features.md +121 -0
  16. package/dist/_raw/content/guide/getting-started.md +112 -0
  17. package/dist/_raw/content/guide/kitfly-overview.md +209 -0
  18. package/dist/_raw/content/reference/configuration.md +259 -0
  19. package/dist/_raw/content/reference/design-catalog.md +167 -0
  20. package/dist/_raw/content/reference/environment-variables.md +66 -0
  21. package/dist/_raw/content/reference/glossary.md +92 -0
  22. package/dist/_raw/content/reference/key-concepts.md +118 -0
  23. package/dist/_raw/content/reference/plugins.md +220 -0
  24. package/dist/_raw/content/reference/slides-authoring-guidelines.md +129 -0
  25. package/dist/_raw/content/reference/structure.md +166 -0
  26. package/dist/_raw/content/reference.md +20 -0
  27. package/dist/_raw/content/templates/crucible.md +192 -0
  28. package/dist/_raw/content/templates/handbook.md +83 -0
  29. package/dist/_raw/content/templates/minimal.md +138 -0
  30. package/dist/_raw/content/templates/overview.md +187 -0
  31. package/dist/_raw/content/templates/pipeline.md +151 -0
  32. package/dist/_raw/content/templates/productbook.md +187 -0
  33. package/dist/_raw/content/templates/runbook.md +193 -0
  34. package/dist/_raw/content/templates/servicebook.md +163 -0
  35. package/dist/_raw/docs/decisions/ADR-0001-minimalist-site-code.md +118 -0
  36. package/dist/_raw/docs/decisions/ADR-0002-ai-accessibility.md +153 -0
  37. package/dist/_raw/docs/decisions/ADR-0003-single-file-bundle.md +93 -0
  38. package/dist/_raw/docs/decisions/ADR-0004-bun-runtime.md +98 -0
  39. package/dist/_raw/docs/decisions/ADR-0005-plugin-contract-and-distribution.md +110 -0
  40. package/dist/_raw/docs/decisions/DDR-0001-viewport-locked-layout.md +111 -0
  41. package/dist/_raw/docs/decisions/DDR-0002-theme-system.md +131 -0
  42. package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md +106 -0
  43. package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md +113 -0
  44. package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md +107 -0
  45. package/dist/_raw/docs/userguide/cli/build.md +85 -0
  46. package/dist/_raw/docs/userguide/cli/bundle.md +81 -0
  47. package/dist/_raw/docs/userguide/cli/dev.md +92 -0
  48. package/dist/_raw/docs/userguide/cli/init.md +116 -0
  49. package/dist/_raw/docs/userguide/cli/servers.md +69 -0
  50. package/dist/_raw/docs/userguide/cli/stop.md +76 -0
  51. package/dist/_raw/docs/userguide/cli/update.md +78 -0
  52. package/dist/_raw/docs/userguide/cli/version.md +65 -0
  53. package/dist/_raw/docs/userguide/cli.md +34 -0
  54. package/dist/_raw/docs/userguide/sharing.md +94 -0
  55. package/dist/_raw/schemas/plugin-schemas-notes.md +71 -0
  56. package/dist/_raw/schemas.md +42 -0
  57. package/dist/assets/brand/kitfly-favicon-32.png +0 -0
  58. package/dist/assets/brand/kitfly-icon-64.png +0 -0
  59. package/dist/assets/brand/kitfly-logo-128.png +0 -0
  60. package/dist/assets/brand/kitfly-logo-512.png +0 -0
  61. package/dist/assets/brand/kitfly-logo.svg +12132 -0
  62. package/dist/assets/brand/kitfly-neon-128.png +0 -0
  63. package/dist/assets/brand/kitfly-neon-192.png +0 -0
  64. package/dist/assets/brand/kitfly-neon-256.png +0 -0
  65. package/dist/assets/brand/kitfly-neon.png +0 -0
  66. package/dist/assets/brand/palette.md +75 -0
  67. package/dist/content/deployment/index.html +11 -0
  68. package/dist/content/deployment/preflight.html +418 -0
  69. package/dist/content/deployment/recipes/aws-s3.html +421 -0
  70. package/dist/content/deployment/recipes/cloudflare-pages.html +372 -0
  71. package/dist/content/deployment/recipes/cloudflare-r2.html +443 -0
  72. package/dist/content/deployment/recipes/fly-io.html +356 -0
  73. package/dist/content/deployment/recipes/github-pages.html +414 -0
  74. package/dist/content/deployment/recipes/index.html +11 -0
  75. package/dist/content/deployment/recipes/netlify.html +394 -0
  76. package/dist/content/deployment/recipes/vercel.html +382 -0
  77. package/dist/content/deployment/secrets-and-env-vars.html +380 -0
  78. package/dist/content/deployment.html +426 -0
  79. package/dist/content/guide/approaches.html +501 -0
  80. package/dist/content/guide/features.html +436 -0
  81. package/dist/content/guide/getting-started.html +403 -0
  82. package/dist/content/guide/index.html +11 -0
  83. package/dist/content/guide/kitfly-overview.html +544 -0
  84. package/dist/content/index.html +11 -0
  85. package/dist/content/reference/configuration.html +580 -0
  86. package/dist/content/reference/design-catalog.html +449 -0
  87. package/dist/content/reference/environment-variables.html +367 -0
  88. package/dist/content/reference/glossary.html +368 -0
  89. package/dist/content/reference/index.html +11 -0
  90. package/dist/content/reference/key-concepts.html +399 -0
  91. package/dist/content/reference/plugins.html +491 -0
  92. package/dist/content/reference/slides-authoring-guidelines.html +418 -0
  93. package/dist/content/reference/structure.html +463 -0
  94. package/dist/content/reference.html +335 -0
  95. package/dist/content/templates/crucible.html +546 -0
  96. package/dist/content/templates/handbook.html +405 -0
  97. package/dist/content/templates/index.html +11 -0
  98. package/dist/content/templates/minimal.html +447 -0
  99. package/dist/content/templates/overview.html +558 -0
  100. package/dist/content/templates/pipeline.html +494 -0
  101. package/dist/content/templates/productbook.html +540 -0
  102. package/dist/content/templates/runbook.html +543 -0
  103. package/dist/content/templates/servicebook.html +523 -0
  104. package/dist/content-index.json +549 -0
  105. package/dist/docs/decisions/ADR-0001-minimalist-site-code.html +491 -0
  106. package/dist/docs/decisions/ADR-0002-ai-accessibility.html +434 -0
  107. package/dist/docs/decisions/ADR-0003-single-file-bundle.html +412 -0
  108. package/dist/docs/decisions/ADR-0004-bun-runtime.html +409 -0
  109. package/dist/docs/decisions/ADR-0005-plugin-contract-and-distribution.html +402 -0
  110. package/dist/docs/decisions/DDR-0001-viewport-locked-layout.html +459 -0
  111. package/dist/docs/decisions/DDR-0002-theme-system.html +452 -0
  112. package/dist/docs/decisions/DDR-0003-bounded-logo-slot.html +423 -0
  113. package/dist/docs/decisions/DDR-0004-slides-rendering-model.html +399 -0
  114. package/dist/docs/decisions/DDR-0005-deterministic-layout-boundary.html +422 -0
  115. package/dist/docs/decisions/index.html +11 -0
  116. package/dist/docs/userguide/cli/build.html +408 -0
  117. package/dist/docs/userguide/cli/bundle.html +419 -0
  118. package/dist/docs/userguide/cli/dev.html +428 -0
  119. package/dist/docs/userguide/cli/index.html +11 -0
  120. package/dist/docs/userguide/cli/init.html +436 -0
  121. package/dist/docs/userguide/cli/servers.html +393 -0
  122. package/dist/docs/userguide/cli/stop.html +408 -0
  123. package/dist/docs/userguide/cli/update.html +406 -0
  124. package/dist/docs/userguide/cli/version.html +406 -0
  125. package/dist/docs/userguide/cli.html +386 -0
  126. package/dist/docs/userguide/index.html +11 -0
  127. package/dist/docs/userguide/sharing.html +465 -0
  128. package/dist/index.html +387 -0
  129. package/dist/llms.txt +18 -0
  130. package/dist/provenance.json +7 -0
  131. package/dist/schemas/index.html +11 -0
  132. package/dist/schemas/plugin-registry.schema.html +327 -0
  133. package/dist/schemas/plugin-schemas-notes.html +364 -0
  134. package/dist/schemas/plugin.schema.html +327 -0
  135. package/dist/schemas/plugins.schema.html +327 -0
  136. package/dist/schemas/v0/common.schema.html +386 -0
  137. package/dist/schemas/v0/index.html +11 -0
  138. package/dist/schemas/v0/plugin-registry.schema.html +547 -0
  139. package/dist/schemas/v0/plugin.schema.html +497 -0
  140. package/dist/schemas/v0/plugins.schema.html +406 -0
  141. package/dist/schemas/v0/site.schema.html +541 -0
  142. package/dist/schemas/v0/theme.schema.html +615 -0
  143. package/dist/schemas.html +351 -0
  144. package/dist/styles.css +1262 -0
  145. package/package.json +4 -2
  146. package/plugins-dist/callouts.css +32 -0
  147. package/plugins-dist/callouts.js +46 -0
  148. package/plugins-dist/slides-visuals.css +390 -0
  149. package/plugins-dist/slides-visuals.js +689 -0
  150. package/registry/plugins.yaml +35 -0
  151. package/schemas/README.md +10 -0
  152. package/schemas/plugin-registry.schema.json +5 -0
  153. package/schemas/plugin-schemas-notes.md +71 -0
  154. package/schemas/plugin.schema.json +5 -0
  155. package/schemas/plugins.schema.json +5 -0
  156. package/schemas/v0/common.schema.json +64 -0
  157. package/schemas/v0/plugin-registry.schema.json +225 -0
  158. package/schemas/v0/plugin.schema.json +175 -0
  159. package/schemas/v0/plugins.schema.json +84 -0
  160. package/schemas/v0/site.schema.json +56 -9
  161. package/schemas/v0/theme.schema.json +105 -22
  162. package/scripts/build.ts +158 -3
  163. package/scripts/bundle.ts +261 -95
  164. package/scripts/dev.ts +301 -11
  165. package/src/__tests__/build.test.ts +220 -1
  166. package/src/__tests__/bundle.test.ts +31 -0
  167. package/src/__tests__/cli.test.ts +14 -3
  168. package/src/__tests__/dev-plugin-errors.test.ts +20 -0
  169. package/src/__tests__/fixtures/fences/slides-visuals/invalid/bad-list-indent.md +5 -0
  170. package/src/__tests__/fixtures/fences/slides-visuals/invalid/blank-line.md +5 -0
  171. package/src/__tests__/fixtures/fences/slides-visuals/invalid/compare-object-items.md +9 -0
  172. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-branching-no-source.md +5 -0
  173. package/src/__tests__/fixtures/fences/slides-visuals/invalid/flow-converging-no-target.md +6 -0
  174. package/src/__tests__/fixtures/fences/slides-visuals/invalid/indented-fence.md +4 -0
  175. package/src/__tests__/fixtures/fences/slides-visuals/invalid/staircase-empty-steps.md +3 -0
  176. package/src/__tests__/fixtures/fences/slides-visuals/invalid/stat-grid-missing-fields.md +5 -0
  177. package/src/__tests__/fixtures/fences/slides-visuals/invalid/timeline-horizontal-no-events.md +2 -0
  178. package/src/__tests__/fixtures/fences/slides-visuals/invalid/unknown-type.md +3 -0
  179. package/src/__tests__/fixtures/fences/slides-visuals/valid/compare.md +10 -0
  180. package/src/__tests__/fixtures/fences/slides-visuals/valid/comparison-table.md +14 -0
  181. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching-no-split.md +7 -0
  182. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-branching.md +8 -0
  183. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging-no-merge.md +7 -0
  184. package/src/__tests__/fixtures/fences/slides-visuals/valid/flow-converging.md +8 -0
  185. package/src/__tests__/fixtures/fences/slides-visuals/valid/funnel.md +7 -0
  186. package/src/__tests__/fixtures/fences/slides-visuals/valid/kpi.md +5 -0
  187. package/src/__tests__/fixtures/fences/slides-visuals/valid/layer-cake.md +6 -0
  188. package/src/__tests__/fixtures/fences/slides-visuals/valid/pyramid.md +6 -0
  189. package/src/__tests__/fixtures/fences/slides-visuals/valid/quadrant-grid.md +8 -0
  190. package/src/__tests__/fixtures/fences/slides-visuals/valid/scorecard.md +13 -0
  191. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase-down.md +7 -0
  192. package/src/__tests__/fixtures/fences/slides-visuals/valid/staircase.md +8 -0
  193. package/src/__tests__/fixtures/fences/slides-visuals/valid/stat-grid.md +8 -0
  194. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-horizontal.md +9 -0
  195. package/src/__tests__/fixtures/fences/slides-visuals/valid/timeline-vertical.md +10 -0
  196. package/src/__tests__/init.test.ts +35 -0
  197. package/src/__tests__/plugin-loader.test.ts +221 -0
  198. package/src/__tests__/shared.test.ts +451 -0
  199. package/src/__tests__/slides-visuals-fence-contract.test.ts +28 -0
  200. package/src/__tests__/slides-visuals-runtime-regressions.bun.test.ts +147 -0
  201. package/src/__tests__/styles.test.ts +35 -0
  202. package/src/cli.ts +9 -4
  203. package/src/plugin-loader.ts +245 -0
  204. package/src/shared.ts +650 -7
  205. package/src/site/styles.css +331 -0
  206. package/src/site/template.html +66 -5
  207. package/src/templates/deck.ts +186 -0
  208. package/src/templates/driver.ts +11 -1
  209. package/src/templates/minimal.ts +1 -0
package/dist/_raw/docs/decisions/DDR-0002-theme-system.md ADDED
@@ -0,0 +1,131 @@
1
+ ---
2
+ title: "DDR-0002: Two-Layer Theme System"
3
+ description: "Defines the kitfly theming model: theme.yaml semantic tokens → generated CSS variables → styles.css fallbacks"
4
+ author: "deliverylead"
5
+ supervised_by: "@3leapsdave"
6
+ date: "2026-02-09"
7
+ status: "accepted"
8
+ tags: ["ddr", "theming", "css", "design"]
9
+ ---
10
+
11
+ # DDR-0002: Two-Layer Theme System
12
+
13
+ ## Status
14
+
15
+ Accepted
16
+
17
+ ## Context
18
+
19
+ Kitfly needs a theming system that lets users customize colors and typography without editing CSS. At the same time, the shipped CSS must render correctly even without a theme file — cold-start works must work. The system must support light/dark modes, syntax highlighting themes, and user-supplied theme files alongside bundled presets.
20
+
21
+ ## Decision
22
+
23
+ Adopt a **two-layer theming model** where a YAML configuration layer defines semantic design tokens and a CSS layer consumes them as custom properties, with hardcoded fallbacks.
24
+
25
+ ### Layer 1: theme.yaml → CSS Variables
26
+
27
+ `theme.yaml` defines semantic color tokens and typography settings:
28
+
29
+ ```yaml
30
+ colors:
31
+ light:
32
+ background: "#ffffff"
33
+ surface: "#f5f7f8"
34
+ text: "#374151"
35
+ heading: "#152F46"
36
+ primary: "#007182"
37
+ accent: "#D17059"
38
+ border: "#e5e7eb"
39
+ dark:
40
+ background: "#0d1117"
41
+ surface: "#152F46"
42
+ # ...
43
+
44
+ typography:
45
+ body: "system"
46
+ headings: "system"
47
+ code: "mono"
48
+ baseSize: "16px"
49
+ scale: "1.25"
50
+
51
+ code:
52
+ light: "default"
53
+ dark: "okaidia"
54
+ ```
55
+
56
+ `src/theme.ts` loads this file, deep-merges with `DEFAULT_THEME`, and calls `generateThemeCSS()` to produce a `<style id="kitfly-theme">` block that sets CSS custom properties on `:root`.
57
+
58
+ ### Layer 2: styles.css Fallbacks
59
+
60
+ `src/site/styles.css` contains hardcoded fallback values in its `:root` block:
61
+
62
+ ```css
63
+ :root {
64
+ --color-bg: #ffffff;
65
+ --color-bg-sidebar: #f8f9fa;
66
+ --color-text: #1a1a1a;
67
+ /* ... */
68
+ }
69
+ ```
70
+
71
+ These fallbacks ensure the site renders correctly if `theme.yaml` is missing or `generateThemeCSS()` is not injected. When the theme `<style>` block is present, it overrides the fallbacks because it appears later in the document `<head>`.
72
+
73
+ ### Token Mapping
74
+
75
+ | theme.yaml token | CSS variable | CSS usage |
76
+ | --------------------------- | -------------------- | ------------------------------- |
77
+ | `colors.light.background` | `--color-bg` | Page background |
78
+ | `colors.light.surface` | `--color-bg-sidebar` | Sidebar, code block backgrounds |
79
+ | `colors.light.text` | `--color-text` | Body text |
80
+ | `colors.light.textMuted` | `--color-text-muted` | Secondary text, metadata |
81
+ | `colors.light.heading` | `--color-accent` | Headings, logo color |
82
+ | `colors.light.primary` | `--color-link` | Links, active nav |
83
+ | `colors.light.primaryHover` | `--color-link-hover` | Link hover state |
84
+ | `colors.light.border` | `--color-border` | Borders, dividers |
85
+
86
+ Dark mode uses the same mapping under `@media (prefers-color-scheme: dark)` and `[data-theme="dark"]`.
87
+
88
+ ### Dark Mode Strategy
89
+
90
+ Three selectors handle dark mode:
91
+
92
+ 1. `@media (prefers-color-scheme: dark)` — OS-level automatic
93
+ 2. `[data-theme="dark"]` — explicit user toggle
94
+ 3. `:root:not([data-theme="light"])` — prevents OS dark overriding an explicit light choice
95
+
96
+ ### Theme Presets
97
+
98
+ Bundled themes in `themes/` (`github.yaml`, `paper.yaml`, `terminal.yaml`) can be copied and customized. Users place their `theme.yaml` in the project root alongside `site.yaml`.
99
+
100
+ ## Consequences
101
+
102
+ ### Positive
103
+
104
+ - Users customize appearance via YAML without touching CSS
105
+ - CSS works standalone — no build step required to see something
106
+ - Dark mode works automatically via OS preference with manual override
107
+ - Theme presets provide starting points for customization
108
+ - Syntax highlighting themes are decoupled (Prism CDN URLs per light/dark)
109
+
110
+ ### Negative
111
+
112
+ - CSS fallback values can drift from `DEFAULT_THEME` if one is updated without the other (mitigated: both live in the codebase and tests can catch drift)
113
+ - Token mapping is implicit — `surface` → `--color-bg-sidebar` isn't obvious without reading theme.ts
114
+
115
+ ### Neutral
116
+
117
+ - Typography uses named presets (`system`, `serif`, `readable`) rather than raw font stacks — simple but limits advanced control
118
+
119
+ ## Alternatives Considered
120
+
121
+ ### CSS-only theming (no YAML)
122
+
123
+ Users edit CSS directly. Rejected because YAML is more accessible for non-developers and integrates with the existing `site.yaml` configuration model.
124
+
125
+ ### CSS Modules / PostCSS pipeline
126
+
127
+ Build-time CSS transformation. Rejected because it contradicts ADR-0001 (minimalist site code) and adds build dependencies.
128
+
129
+ ### Single source of truth (no CSS fallbacks)
130
+
131
+ Only generate CSS from theme.ts, no hardcoded `:root`. Rejected because it breaks cold-start: opening `styles.css` directly or loading before JS runs would show unstyled content.
package/dist/_raw/docs/decisions/DDR-0003-bounded-logo-slot.md ADDED
@@ -0,0 +1,106 @@
1
+ ---
2
+ title: "DDR-0003: Bounded Logo Slot"
3
+ description: "Logo rendering uses a bounded bounding-box model supporting both square icons and wide wordmarks"
4
+ author: "deliverylead"
5
+ supervised_by: "@3leapsdave"
6
+ date: "2026-02-09"
7
+ status: "accepted"
8
+ tags: ["ddr", "logo", "css", "branding"]
9
+ ---
10
+
11
+ # DDR-0003: Bounded Logo Slot
12
+
13
+ ## Status
14
+
15
+ Accepted
16
+
17
+ ## Context
18
+
19
+ Kitfly sites display a brand logo in the sidebar header. Logos come in two aspect ratios:
20
+
21
+ - **Square icons** (1:1 or near-square) — app icons, monograms, favicons scaled up
22
+ - **Wide wordmarks** (3:1 or wider) — full brand names, logotypes with text
23
+
24
+ The previous implementation used a fixed pixel height for the logo image, which worked for one shape but not the other. A square icon at 64px rendered fine; the same 64px height on a wide wordmark meant it consumed most of the sidebar width and pushed navigation down. Conversely, constraining width for wordmarks made square icons tiny.
25
+
26
+ ## Decision
27
+
28
+ Use a **bounded bounding-box model** where the logo slot defines maximum dimensions per breakpoint, and the image fills the box while preserving its native aspect ratio.
29
+
30
+ ### Slot Dimensions
31
+
32
+ | Breakpoint | Max Height | Max Width |
33
+ | ------------------ | ---------- | --------- |
34
+ | Desktop (> 1024px) | 64px | 180px |
35
+ | Tablet (≤ 1024px) | 56px | 150px |
36
+ | Mobile (≤ 768px) | 48px | 130px |
37
+
38
+ ### CSS Implementation
39
+
40
+ ```css
41
+ .logo-icon {
42
+ height: 64px;
43
+ width: auto;
44
+ max-width: 180px;
45
+ }
46
+ ```
47
+
48
+ The key properties:
49
+
50
+ - `height` sets the box height (the dominant constraint for square icons)
51
+ - `width: auto` preserves aspect ratio
52
+ - `max-width` prevents wide wordmarks from overflowing the sidebar
53
+
54
+ For wordmark logos, the `.logo-wordmark` class switches the constraint axis:
55
+
56
+ ```css
57
+ .logo.logo-wordmark .logo-img {
58
+ max-width: 180px;
59
+ height: auto;
60
+ max-height: 64px;
61
+ }
62
+ ```
63
+
64
+ ### logoType Configuration
65
+
66
+ `site.yaml` supports `brand.logoType` to select the rendering mode:
67
+
68
+ | Value | Behavior |
69
+ | ------------------ | ---------------------------------------------- |
70
+ | `"icon"` (default) | Height-dominant constraint, square/near-square |
71
+ | `"wordmark"` | Width-dominant constraint, wide aspect ratio |
72
+
73
+ The bundle system propagates `logoType` via `buildBundleSidebarHeader()` to ensure parity between build and bundle output.
74
+
75
+ ### Supported Formats
76
+
77
+ - **PNG**: Recommended for icons. Use `kitfly-logo-128.png` at 128px for 2x retina clarity in the 64px slot.
78
+ - **SVG**: Supported but requires a tightly-cropped `viewBox`. An oversized canvas (e.g., A4 page `viewBox="0 0 210 297"`) will render the artwork too small within the bounded slot.
79
+
80
+ ## Consequences
81
+
82
+ ### Positive
83
+
84
+ - Both icon and wordmark logos render cleanly without CSS customization
85
+ - Responsive scaling is automatic — one set of breakpoints handles both shapes
86
+ - No logo distortion — aspect ratio is always preserved
87
+ - Bundle output matches static build (logoType propagation)
88
+
89
+ ### Negative
90
+
91
+ - SVG logos with oversized viewBox render poorly — users must crop the viewBox to artwork bounds (documented in configuration reference)
92
+ - Two rendering modes (`icon` vs `wordmark`) add a configuration choice — mitigated by defaulting to `icon` which handles most cases
93
+
94
+ ## Alternatives Considered
95
+
96
+ ### Fixed pixel dimensions
97
+
98
+ Single `width: 120px; height: 40px` for all logos. Rejected because it distorts non-matching aspect ratios and doesn't adapt to breakpoints.
99
+
100
+ ### Percentage-based sizing
101
+
102
+ `width: 60%` of sidebar. Rejected because it couples logo size to sidebar width and produces inconsistent results across breakpoints (280px desktop vs overlay mobile).
103
+
104
+ ### User-specified dimensions in site.yaml
105
+
106
+ Let users set `logo.width` and `logo.height` in config. Rejected as over-engineering — the bounded box handles the common cases, and users can override via custom CSS if needed.
package/dist/_raw/docs/decisions/DDR-0004-slides-rendering-model.md ADDED
@@ -0,0 +1,113 @@
1
+ ---
2
+ title: "DDR-0004: Slides Rendering Model"
3
+ description: "Defines slides mode rendering, segmentation, and navigation behavior across dev/build/bundle"
4
+ author: "devlead"
5
+ supervised_by: "@3leapsdave"
6
+ date: "2026-02-11"
7
+ status: "proposed"
8
+ tags: ["ddr", "slides", "layout", "routing", "rendering"]
9
+ ---
10
+
11
+ # DDR-0004: Slides Rendering Model
12
+
13
+ ## Status
14
+
15
+ Proposed
16
+
17
+ ## Context
18
+
19
+ Kitfly is adding a new `mode: slides` experience for fixed-aspect presentation output while preserving existing docs mode behavior.
20
+
21
+ A design-level decision is needed so all render paths (`dev`, `build`, `bundle`) behave consistently and remain minimal.
22
+
23
+ ## Decision
24
+
25
+ ### 1. Single-page, hash-routed slides
26
+
27
+ Slides mode renders as a single-page deck with hash navigation (`#slide-n`).
28
+
29
+ Behavior:
30
+
31
+ - prev/next controls update active slide,
32
+ - keyboard navigation supports ArrowLeft/ArrowRight/Space/Home/End,
33
+ - URL hash deep-links and restores slide state on reload.
34
+
35
+ ### 2. Explicit slide segmentation delimiter
36
+
37
+ Within a markdown file, slide boundaries use:
38
+
39
+ `--- slide ---`
40
+
41
+ Rules:
42
+
43
+ - standard YAML frontmatter remains unchanged,
44
+ - plain markdown `---` is treated as content (horizontal rule),
45
+ - one file per slide remains a first-class authoring model.
46
+
47
+ ### 3. Frontmatter metadata for slide behavior
48
+
49
+ Per-slide frontmatter supports:
50
+
51
+ - `title` for sidebar/counter labels,
52
+ - `class` for slide-level layout/style hooks.
53
+
54
+ Rendered slide wrapper form:
55
+
56
+ `<section class="slide {frontmatter.class?}"> ... </section>`
57
+
58
+ ### 4. Mode branch with parity requirement
59
+
60
+ Slides mode is a rendering branch, not a separate engine.
61
+
62
+ Parity requirement:
63
+
64
+ - `scripts/dev.ts`, `scripts/build.ts`, and `scripts/bundle.ts` must produce equivalent slide ordering, segmentation, and navigation semantics.
65
+ - Shared logic should live in `src/shared.ts` where feasible to avoid divergence.
66
+
67
+ ### 5. Overflow policy
68
+
69
+ Default slide frame behavior is scrollable overflow (`overflow: auto`) to avoid silent content clipping. Optional strict clipping can be enabled via slide class if needed.
70
+
71
+ ## Consequences
72
+
73
+ ### Positive
74
+
75
+ - Deterministic routing and shareable deep links.
76
+ - Lower ambiguity for authors/agents due to explicit delimiter.
77
+ - Consistent output across dev/build/bundle.
78
+ - Keeps core implementation compact and understandable.
79
+
80
+ ### Negative
81
+
82
+ - Authors must learn a non-standard delimiter token for intra-file slides.
83
+ - Very dense slides may still need manual content shaping for best presentation quality.
84
+
85
+ ### Neutral
86
+
87
+ - Slides mode does not aim to replace full presentation suites; it optimizes markdown-native, web-first decks.
88
+
89
+ ## Non-Goals
90
+
91
+ - Animated transitions in core,
92
+ - presenter mode/speaker notes in core,
93
+ - runtime slide master system,
94
+ - swipe gestures requirement for v1.
95
+
96
+ ## Alternatives Considered
97
+
98
+ ### Multi-page slide routing
99
+
100
+ Rejected for v1 due to higher complexity and weaker parity with single-file bundle behavior.
101
+
102
+ ### Reusing plain `---` as slide break
103
+
104
+ Rejected due to ambiguity with frontmatter and horizontal-rule markdown usage.
105
+
106
+ ### Hidden overflow by default
107
+
108
+ Rejected because clipped content fails silently and is hard to debug during authoring.
109
+
110
+ ## References
111
+
112
+ - v0.2.0 slides mode plan (`.plans/active/v0.2.0/`)
113
+ - [DDR-0001: Viewport-Locked Layout](DDR-0001-viewport-locked-layout.md)
package/dist/_raw/docs/decisions/DDR-0005-deterministic-layout-boundary.md ADDED
@@ -0,0 +1,107 @@
1
+ ---
2
+ title: "DDR-0005: Deterministic Layout Boundary"
3
+ description: "Defines the boundary between CSS layout primitives/figures and diagramming engines for slide visual composition"
4
+ author: "deliverylead"
5
+ supervised_by: "@3leapsdave"
6
+ date: "2026-02-12"
7
+ status: "proposed"
8
+ tags: ["ddr", "slides", "layout", "primitives", "figures", "diagrams"]
9
+ ---
10
+
11
+ # DDR-0005: Deterministic Layout Boundary
12
+
13
+ ## Status
14
+
15
+ Proposed
16
+
17
+ ## Context
18
+
19
+ Kitfly generates slidesites — fixed-aspect pages that are not “infinite scroll” documents. A key use case is AI agents generating presentation-quality slides, including infographic-style layouts with shapes, connectors, and composed visual patterns. (If content is long, it may scroll _within_ the slide frame; the page layout remains slide-like.)
20
+
21
+ Kitfly is not trying to recreate diagram engines like Mermaid or PlantUML. Those tools compute layout from relationships, which is powerful but hard to control precisely in slide composition and hard for agents to predict.
22
+
23
+ We need to decide how far to push CSS-based shapes and figures before delegating to diagram engines. The risk on one side is rebuilding a diagram engine inside CSS; the risk on the other is forcing all visual compositions through tools whose auto-layout is difficult for agents to control precisely.
24
+
25
+ ### Observed Problems
26
+
27
+ 1. **Mermaid/PlantUML alignment** — Auto-layout engines optimize for their own constraints. Achieving pixel-precise placement within a slide's visual design is unreliable. Agents cannot predict where nodes will land.
28
+ 2. **Agent reasoning** — AI agents generate better results when they can specify placement explicitly ("put X at grid position 2,1") rather than describing relationships and hoping the layout engine produces the desired visual.
29
+ 3. **Scope creep** — Without a clear boundary, CSS primitives could grow into a general-purpose diagramming system, duplicating work better handled by existing engines.
30
+
31
+ ## Decision
32
+
33
+ **Kitfly will maintain two distinct tiers of visual building blocks, separated by a deterministic layout boundary.**
34
+
35
+ ### Tier 1: Shapes (Primitives)
36
+
37
+ Atomic visual elements (shapes, connectors, text treatments, decorators) with **no internal layout logic**. The author or agent specifies position explicitly. These are analogous to icons in an icon library.
38
+
39
+ Examples: box, circle, diamond, chevron, block-arrow, line-connector, callout, badge.
40
+
41
+ ### Tier 2: Figures (Deterministic Infographic Patterns)
42
+
43
+ Parameterized layout templates built from primitives. The figure owns its **internal arrangement** via a deterministic algorithm (CSS Grid, flexbox, trigonometric placement). The agent fills named slots; the figure handles spacing, sizing, and connector routing within its bounding box.
44
+
45
+ Examples: cycle-wheel, quadrant-grid, layer-cake, funnel, hub-spoke, horizontal-flow, timeline.
46
+
47
+ ### The Boundary Rule
48
+
49
+ > **If you can name the pieces and where they go (explicit positions or slots), it is a figure. If layout must be computed from relationships between a variable set of nodes, it is a diagram engine.**
50
+
51
+ | Criterion | Primitives / Figures | Diagramming Engine |
52
+ | ------------------------------------------- | --------------------------- | ------------------- |
53
+ | Agent knows element count | Yes | Maybe not |
54
+ | Agent controls placement | Yes (explicit or via slots) | No (engine decides) |
55
+ | Adding a node requires recalculating others | No | Yes |
56
+ | Relationships determine layout | No | Yes |
57
+ | Topology is fixed per figure type | Yes | No |
58
+
59
+ ### Diagramming Engine Integration
60
+
61
+ For compositions that cross the boundary (flowcharts with variable branching, org charts, dependency graphs, state machines), kitfly's **plugin model** will wrap diagramming engines with a constrained contract:
62
+
63
+ - The plugin renders into a **declared bounding box** within the slide grid.
64
+ - The plugin accepts a **kitfly theme** (colors, fonts, stroke styles) for visual consistency.
65
+ - Internal layout is fully delegated to the engine.
66
+ - The agent does not attempt to micro-position nodes within the engine's output.
67
+
68
+ ## Consequences
69
+
70
+ ### Implementation Notes (M1.1)
71
+
72
+ - Core ships **shape primitives** as `.block` modifiers (for example `circle`, `diamond`, `chevron`, `block-arrow`) with deterministic CSS-only behavior.
73
+ - Simple directional flows use existing `block-flow` glyph arrows plus directional shapes; general connector routing remains deferred to plugin/engine phases.
74
+ - This keeps Tier 1 in core without crossing into layout-engine responsibilities.
75
+
76
+ ### Benefits
77
+
78
+ 1. **Agent reliability** — Agents produce consistent, predictable visual output for common infographic patterns that are deterministic layouts.
79
+ 2. **Clear plugin contract** — Diagramming engines are scoped to a bounding box with theme passthrough, avoiding the "Mermaid vs. slide layout" fight.
80
+ 3. **No engine rebuild** — We explicitly stop before reimplementing graph layout, edge routing, or constraint solving in CSS.
81
+ 4. **Catalog-driven authoring** — The figure catalog acts as a vocabulary. Agents pick a pattern and fill slots, similar to choosing an icon from a set.
82
+
83
+ ### Trade-offs
84
+
85
+ 1. **Figure library maintenance** — Each new infographic pattern requires a new figure implementation. This is intentional — it's the cost of deterministic quality.
86
+ 2. **Boundary edge cases** — Some compositions (e.g., a flow diagram with exactly 2 branch points) could go either way. Default to figures when topology is fixed and small; to engines when variable.
87
+ 3. **Two rendering paths** — Slides mixing figures and engine-rendered diagrams have two rendering subsystems. The plugin model must ensure visual coherence (shared theme tokens).
88
+
89
+ ## Alternatives Considered
90
+
91
+ ### A. CSS-only, no diagramming engines
92
+
93
+ Rejected. Connector routing and auto-layout for arbitrary graphs is a solved problem in existing engines. Rebuilding it in CSS is high effort, low quality.
94
+
95
+ ### B. Diagramming engine-only (Mermaid/PlantUML for everything)
96
+
97
+ Rejected. Agents cannot control output placement precisely enough for slide-quality layouts. Simple compositions (4-box grid, layer cake) become unnecessarily complex in diagram DSLs.
98
+
99
+ ### C. Canvas/SVG drawing API exposed to agents
100
+
101
+ Rejected for primary use. Too low-level — agents generating raw SVG coordinates produce inconsistent results. However, primitives may use inline SVG internally (especially for connectors), hidden behind the primitive's API.
102
+
103
+ ## References
104
+
105
+ - [Design Catalog: Shapes and Figures](../../content/reference/design-catalog.md)
106
+ - [ADR-0005: Plugin Contract and Distribution Strategy](ADR-0005-plugin-contract-and-distribution.md)
107
+ - [DDR-0004: Slides Rendering Model](DDR-0004-slides-rendering-model.md)
package/dist/_raw/docs/userguide/cli/build.md ADDED
@@ -0,0 +1,85 @@
1
+ # kitfly build
2
+
3
+ Build static site to output directory.
4
+
5
+ ## Usage
6
+
7
+ ```bash
8
+ kitfly build [folder] [options]
9
+ ```
10
+
11
+ ## Description
12
+
13
+ Generates a complete static HTML site from your markdown files. The output can be deployed to any static hosting service (GitHub Pages, Netlify, S3, etc.).
14
+
15
+ ## Arguments
16
+
17
+ | Argument | Description |
18
+ | -------- | -------------------------------------------------------------------------------- |
19
+ | `folder` | Content folder to build (default: current directory or `docroot` from site.yaml) |
20
+
21
+ ## Options
22
+
23
+ | Option | Environment Variable | Default | Description |
24
+ | ------------- | -------------------- | ------- | -------------------------------- |
25
+ | `--out <dir>` | `KITFLY_BUILD_OUT` | dist | Output directory |
26
+ | `--no-raw` | - | false | Don't include raw markdown files |
27
+
28
+ ## Examples
29
+
30
+ ### Basic usage
31
+
32
+ ```bash
33
+ # Build current project
34
+ kitfly build
35
+
36
+ # Build specific folder
37
+ kitfly build ./docs
38
+
39
+ # Custom output directory
40
+ kitfly build --out ./public
41
+ ```
42
+
43
+ ### Without raw markdown
44
+
45
+ ```bash
46
+ # HTML only, no .md files in output
47
+ kitfly build --no-raw
48
+ ```
49
+
50
+ ## Output Structure
51
+
52
+ ```
53
+ dist/
54
+ ├── index.html
55
+ ├── guide/
56
+ │ ├── getting-started.html
57
+ │ └── getting-started.md # (if --no-raw not specified)
58
+ ├── reference/
59
+ │ └── ...
60
+ └── assets/
61
+ └── ...
62
+ ```
63
+
64
+ ## Raw Markdown Files
65
+
66
+ By default, kitfly includes the original `.md` files alongside the generated HTML. This allows:
67
+
68
+ - Downloading source for offline editing
69
+ - Transparency about content source
70
+ - Easy content migration
71
+
72
+ Use `--no-raw` to exclude these files if not needed.
73
+
74
+ ## Plugin validation errors (triple-colon fences)
75
+
76
+ Some plugins add special block syntax (for example, `slides-visuals` uses `:::` fences).
77
+
78
+ When a plugin is enabled, kitfly may validate your content during the build. If validation fails, `kitfly build` will exit with a clear error message so you can fix the content and re-run the build.
79
+
80
+ See the exact contract (with examples): `../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals`.
81
+
82
+ ## See Also
83
+
84
+ - [kitfly dev](dev.md) - Development server
85
+ - [kitfly bundle](bundle.md) - Single-file output
package/dist/_raw/docs/userguide/cli/bundle.md ADDED
@@ -0,0 +1,81 @@
1
+ # kitfly bundle
2
+
3
+ Build single-file HTML bundle.
4
+
5
+ ## Usage
6
+
7
+ ```bash
8
+ kitfly bundle [folder] [options]
9
+ ```
10
+
11
+ ## Description
12
+
13
+ Creates a single, self-contained HTML file with all content, styles, and navigation embedded. Perfect for sharing via email, Slack, or file sharing services.
14
+
15
+ ## Arguments
16
+
17
+ | Argument | Description |
18
+ | -------- | --------------------------------------------------------------------------------- |
19
+ | `folder` | Content folder to bundle (default: current directory or `docroot` from site.yaml) |
20
+
21
+ ## Options
22
+
23
+ | Option | Environment Variable | Default | Description |
24
+ | --------------- | -------------------- | ----------- | ------------------------------ |
25
+ | `--out <dir>` | `KITFLY_BUILD_OUT` | dist | Output directory |
26
+ | `--name <file>` | - | bundle.html | Output filename |
27
+ | `--raw` | `KITFLY_BUILD_RAW` | true | Include raw markdown in bundle |
28
+ | `--no-raw` | - | - | Don't include raw markdown |
29
+
30
+ ## Examples
31
+
32
+ ### Basic usage
33
+
34
+ ```bash
35
+ # Create bundle.html in dist/
36
+ kitfly bundle
37
+
38
+ # Custom filename
39
+ kitfly bundle --name my-docs.html
40
+
41
+ # Custom output location
42
+ kitfly bundle --out ./release --name handbook.html
43
+ ```
44
+
45
+ ## Output
46
+
47
+ A single HTML file containing:
48
+
49
+ - All page content with images inlined as base64 data URIs
50
+ - Embedded CSS styles
51
+ - Syntax highlighting (Prism.js, inlined)
52
+ - Diagram rendering (Mermaid, inlined)
53
+ - Navigation and table of contents
54
+ - Dark mode support
55
+ - Brand logo and favicon (inlined)
56
+ - No external dependencies (works fully offline)
57
+
58
+ ## Use Cases
59
+
60
+ - **Email attachment**: Share documentation without hosting
61
+ - **Offline reading**: Works without internet connection
62
+ - **Review cycles**: Send to stakeholders for feedback
63
+ - **Archival**: Single-file snapshot of documentation
64
+ - **Client handoff**: Portable single-file deliverable with all images embedded
65
+
66
+ ## File Size
67
+
68
+ Bundle size depends on content volume and images. Typical documentation sites produce bundles of 100KB-1MB. Sites with many images will be larger due to base64 encoding (~33% overhead per image).
69
+
70
+ ## Plugin validation errors (triple-colon fences)
71
+
72
+ Some plugins add special block syntax (for example, `slides-visuals` uses `:::` fences).
73
+
74
+ When a plugin is enabled, kitfly may validate your content before bundling. If validation fails, `kitfly bundle` will exit with a clear error message so you can fix the content and re-run the bundle.
75
+
76
+ See the exact contract (with examples): `../../../content/reference/plugins.html#triple-colon-fence-contract-slides-visuals`.
77
+
78
+ ## See Also
79
+
80
+ - [kitfly build](build.md) - Multi-file static build
81
+ - [kitfly dev](dev.md) - Development server