@hyperframes/core 0.1.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 (103) hide show
  1. package/README.md +125 -0
  2. package/dist/adapters/gsap.d.ts +14 -0
  3. package/dist/adapters/gsap.d.ts.map +1 -0
  4. package/dist/adapters/gsap.js +25 -0
  5. package/dist/adapters/gsap.js.map +1 -0
  6. package/dist/adapters/index.d.ts +4 -0
  7. package/dist/adapters/index.d.ts.map +1 -0
  8. package/dist/adapters/index.js +2 -0
  9. package/dist/adapters/index.js.map +1 -0
  10. package/dist/adapters/types.d.ts +15 -0
  11. package/dist/adapters/types.d.ts.map +1 -0
  12. package/dist/adapters/types.js +2 -0
  13. package/dist/adapters/types.js.map +1 -0
  14. package/dist/compiler/htmlBundler.d.ts +16 -0
  15. package/dist/compiler/htmlBundler.d.ts.map +1 -0
  16. package/dist/compiler/htmlBundler.js +448 -0
  17. package/dist/compiler/htmlBundler.js.map +1 -0
  18. package/dist/compiler/htmlCompiler.d.ts +18 -0
  19. package/dist/compiler/htmlCompiler.d.ts.map +1 -0
  20. package/dist/compiler/htmlCompiler.js +65 -0
  21. package/dist/compiler/htmlCompiler.js.map +1 -0
  22. package/dist/compiler/index.d.ts +5 -0
  23. package/dist/compiler/index.d.ts.map +1 -0
  24. package/dist/compiler/index.js +9 -0
  25. package/dist/compiler/index.js.map +1 -0
  26. package/dist/compiler/staticGuard.d.ts +8 -0
  27. package/dist/compiler/staticGuard.d.ts.map +1 -0
  28. package/dist/compiler/staticGuard.js +26 -0
  29. package/dist/compiler/staticGuard.js.map +1 -0
  30. package/dist/compiler/timingCompiler.d.ts +72 -0
  31. package/dist/compiler/timingCompiler.d.ts.map +1 -0
  32. package/dist/compiler/timingCompiler.js +191 -0
  33. package/dist/compiler/timingCompiler.js.map +1 -0
  34. package/dist/core.types.d.ts +314 -0
  35. package/dist/core.types.d.ts.map +1 -0
  36. package/dist/core.types.js +52 -0
  37. package/dist/core.types.js.map +1 -0
  38. package/dist/generators/hyperframes.d.ts +21 -0
  39. package/dist/generators/hyperframes.d.ts.map +1 -0
  40. package/dist/generators/hyperframes.js +572 -0
  41. package/dist/generators/hyperframes.js.map +1 -0
  42. package/dist/hyperframe.manifest.json +22 -0
  43. package/dist/hyperframe.runtime.iife.js +13 -0
  44. package/dist/hyperframe.runtime.mjs +13 -0
  45. package/dist/index.d.ts +23 -0
  46. package/dist/index.d.ts.map +1 -0
  47. package/dist/index.js +16 -0
  48. package/dist/index.js.map +1 -0
  49. package/dist/inline-scripts/hyperframe.d.ts +13 -0
  50. package/dist/inline-scripts/hyperframe.d.ts.map +1 -0
  51. package/dist/inline-scripts/hyperframe.js +15 -0
  52. package/dist/inline-scripts/hyperframe.js.map +1 -0
  53. package/dist/inline-scripts/hyperframesRuntime.engine.d.ts +7 -0
  54. package/dist/inline-scripts/hyperframesRuntime.engine.d.ts.map +1 -0
  55. package/dist/inline-scripts/hyperframesRuntime.engine.js +31 -0
  56. package/dist/inline-scripts/hyperframesRuntime.engine.js.map +1 -0
  57. package/dist/inline-scripts/parityContract.d.ts +5 -0
  58. package/dist/inline-scripts/parityContract.d.ts.map +1 -0
  59. package/dist/inline-scripts/parityContract.js +43 -0
  60. package/dist/inline-scripts/parityContract.js.map +1 -0
  61. package/dist/inline-scripts/pickerApi.d.ts +32 -0
  62. package/dist/inline-scripts/pickerApi.d.ts.map +1 -0
  63. package/dist/inline-scripts/pickerApi.js +2 -0
  64. package/dist/inline-scripts/pickerApi.js.map +1 -0
  65. package/dist/inline-scripts/runtimeContract.d.ts +14 -0
  66. package/dist/inline-scripts/runtimeContract.d.ts.map +1 -0
  67. package/dist/inline-scripts/runtimeContract.js +21 -0
  68. package/dist/inline-scripts/runtimeContract.js.map +1 -0
  69. package/dist/lint/hyperframeLinter.d.ts +3 -0
  70. package/dist/lint/hyperframeLinter.d.ts.map +1 -0
  71. package/dist/lint/hyperframeLinter.js +621 -0
  72. package/dist/lint/hyperframeLinter.js.map +1 -0
  73. package/dist/lint/index.d.ts +3 -0
  74. package/dist/lint/index.d.ts.map +1 -0
  75. package/dist/lint/index.js +2 -0
  76. package/dist/lint/index.js.map +1 -0
  77. package/dist/lint/types.d.ts +21 -0
  78. package/dist/lint/types.d.ts.map +1 -0
  79. package/dist/lint/types.js +2 -0
  80. package/dist/lint/types.js.map +1 -0
  81. package/dist/parsers/gsapParser.d.ts +50 -0
  82. package/dist/parsers/gsapParser.d.ts.map +1 -0
  83. package/dist/parsers/gsapParser.js +411 -0
  84. package/dist/parsers/gsapParser.js.map +1 -0
  85. package/dist/parsers/htmlParser.d.ts +29 -0
  86. package/dist/parsers/htmlParser.d.ts.map +1 -0
  87. package/dist/parsers/htmlParser.js +726 -0
  88. package/dist/parsers/htmlParser.js.map +1 -0
  89. package/dist/templates/base.d.ts +4 -0
  90. package/dist/templates/base.d.ts.map +1 -0
  91. package/dist/templates/base.js +20 -0
  92. package/dist/templates/base.js.map +1 -0
  93. package/dist/templates/constants.d.ts +7 -0
  94. package/dist/templates/constants.d.ts.map +1 -0
  95. package/dist/templates/constants.js +8 -0
  96. package/dist/templates/constants.js.map +1 -0
  97. package/docs/common-mistakes.md +73 -0
  98. package/docs/core.md +532 -0
  99. package/docs/core_notes.md +61 -0
  100. package/docs/quickstart-template.html +180 -0
  101. package/docs/versions/changelog.md +5 -0
  102. package/docs/versions/v0.1/core.md +326 -0
  103. package/package.json +83 -0
package/README.md ADDED
@@ -0,0 +1,125 @@
1
+ # HyperFrames Core
2
+
3
+ > Create videos by writing HTML. The HTML is the source of truth - timing, layout, content. Scripts define how clips animate.
4
+
5
+ HyperFrames Core is the foundational library for video composition. It defines the data attributes and HTML structure that represent video timelines, with GSAP animations to bring clips to life.
6
+
7
+ Frame adapter direction:
8
+
9
+ - [`../FRAME.md`](../FRAME.md) - repository-level frame model and deterministic renderer direction
10
+ - [`adapters/README.md`](adapters/README.md) - adapter contract and contribution guide
11
+
12
+ ## Philosophy
13
+
14
+ ```
15
+ HTML = Scene description (content, timing, layout)
16
+ CSS = Styling
17
+ JS = GSAP animations (motion)
18
+ ```
19
+
20
+ Every element in the video timeline is represented as an HTML element with data attributes that define its position in time.
21
+
22
+ ---
23
+
24
+ ## Documentation
25
+
26
+ ### Schema
27
+
28
+ The specification for valid HyperFrames HTML:
29
+
30
+ - **[schema.md](docs/schema.md)** - Element types, data attributes, HTML patterns
31
+
32
+ ### Guides
33
+
34
+ For AI agents and developers working with HyperFrames:
35
+
36
+ | Document | Description |
37
+ | --------------------------------------------------------- | -------------------------------------- |
38
+ | [Cheat Sheet](docs/guides/cheat-sheet.md) | Quick reference for common actions |
39
+ | [Position Guide](docs/guides/position.md) | Natural language → position mappings |
40
+ | [Text Style Guide](docs/guides/text-style.md) | Natural language → text style mappings |
41
+ | [Motion Design Guide](docs/guides/motion-design/guide.md) | Creating and editing motion designs |
42
+ | [Caption Guide](docs/guides/motion-design/captions.md) | Adding captions to videos |
43
+
44
+ ---
45
+
46
+ ## Quick Start
47
+
48
+ ### Using the Editor (Recommended)
49
+
50
+ ```bash
51
+ pnpm install
52
+ pnpm dev
53
+ ```
54
+
55
+ This starts the studio dev server.
56
+
57
+ ### Writing Compositions Manually
58
+
59
+ ```html
60
+ <!DOCTYPE html>
61
+ <html>
62
+ <head>
63
+ <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
64
+ <style>
65
+ * {
66
+ margin: 0;
67
+ padding: 0;
68
+ box-sizing: border-box;
69
+ }
70
+ html,
71
+ body {
72
+ width: 100%;
73
+ height: 100%;
74
+ overflow: hidden;
75
+ background: #000;
76
+ }
77
+ #stage {
78
+ position: relative;
79
+ width: 1920px;
80
+ height: 1080px;
81
+ overflow: hidden;
82
+ }
83
+ </style>
84
+ </head>
85
+ <body>
86
+ <div id="stage">
87
+ <video id="el-1" data-start="0" data-end="10" src="video.mp4" muted playsinline></video>
88
+ <div id="el-2" data-start="2" data-end="6" data-type="text">
89
+ <div>Hello World</div>
90
+ </div>
91
+ </div>
92
+ <script>
93
+ const tl = gsap.timeline({ paused: true });
94
+ // Add animations...
95
+ </script>
96
+ </body>
97
+ </html>
98
+ ```
99
+
100
+ ---
101
+
102
+ ## Element Types
103
+
104
+ | Type | HTML Tag | Purpose |
105
+ | ----------- | ------------------------------- | -------------------- |
106
+ | video | `<video>` | Video clips |
107
+ | image | `<img>` | Static images |
108
+ | text | `<div data-type="text">` | Text overlays |
109
+ | audio | `<audio>` | Music, sound effects |
110
+ | composition | `<div data-type="composition">` | Motion designs |
111
+
112
+ ## Data Attributes
113
+
114
+ | Attribute | Purpose | Required |
115
+ | ------------ | --------------------------------- | -------- |
116
+ | `data-start` | When element appears (seconds) | Yes |
117
+ | `data-end` | When element disappears (seconds) | No |
118
+ | `data-name` | Display name in UI | No |
119
+ | `data-layer` | Z-index for stacking | No |
120
+
121
+ See [schema.md](docs/schema.md) for the complete reference.
122
+
123
+ ---
124
+
125
+ **Remember:** HTML is the storyboard. CSS is the art direction. JS is just for motion.
package/dist/adapters/gsap.d.ts ADDED
@@ -0,0 +1,14 @@
1
+ import type { FrameAdapter } from "./types";
2
+ export interface GSAPTimelineLike {
3
+ duration: () => number;
4
+ totalDuration?: () => number;
5
+ seek: (timeInSeconds: number, suppressEvents?: boolean) => unknown;
6
+ pause?: () => unknown;
7
+ }
8
+ export interface CreateGSAPFrameAdapterOptions {
9
+ id?: string;
10
+ fps: number;
11
+ timeline: GSAPTimelineLike;
12
+ }
13
+ export declare function createGSAPFrameAdapter(options: CreateGSAPFrameAdapterOptions): FrameAdapter;
14
+ //# sourceMappingURL=gsap.d.ts.map
package/dist/adapters/gsap.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"gsap.d.ts","sourceRoot":"","sources":["../../src/adapters/gsap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,WAAW,gBAAgB;IAE/B,QAAQ,EAAE,MAAM,MAAM,CAAC;IAEvB,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,IAAI,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IACnE,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,6BAA6B,GAAG,YAAY,CAyB3F"}
package/dist/adapters/gsap.js ADDED
@@ -0,0 +1,25 @@
1
+ export function createGSAPFrameAdapter(options) {
2
+ const { fps, timeline } = options;
3
+ const adapterId = options.id ?? "gsap";
4
+ const getDurationSeconds = () => {
5
+ const totalDuration = typeof timeline.totalDuration === "function" ? timeline.totalDuration() : timeline.duration();
6
+ return Number.isFinite(totalDuration) && totalDuration > 0 ? totalDuration : 0;
7
+ };
8
+ return {
9
+ id: adapterId,
10
+ init: () => {
11
+ timeline.pause?.();
12
+ },
13
+ getDurationFrames: () => {
14
+ const durationSeconds = getDurationSeconds();
15
+ return Math.max(0, Math.ceil(durationSeconds * fps));
16
+ },
17
+ seekFrame: (frame) => {
18
+ const clampedFrame = Number.isFinite(frame) ? Math.max(0, frame) : 0;
19
+ const targetSeconds = clampedFrame / fps;
20
+ timeline.pause?.();
21
+ timeline.seek(targetSeconds, false);
22
+ },
23
+ };
24
+ }
25
+ //# sourceMappingURL=gsap.js.map
package/dist/adapters/gsap.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"gsap.js","sourceRoot":"","sources":["../../src/adapters/gsap.ts"],"names":[],"mappings":"AAiBA,MAAM,UAAU,sBAAsB,CAAC,OAAsC;IAC3E,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAClC,MAAM,SAAS,GAAG,OAAO,CAAC,EAAE,IAAI,MAAM,CAAC;IAEvC,MAAM,kBAAkB,GAAG,GAAW,EAAE;QACtC,MAAM,aAAa,GAAG,OAAO,QAAQ,CAAC,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACpH,OAAO,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,CAAC,CAAC;IAEF,OAAO;QACL,EAAE,EAAE,SAAS;QACb,IAAI,EAAE,GAAG,EAAE;YACT,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;QACrB,CAAC;QACD,iBAAiB,EAAE,GAAG,EAAE;YACtB,MAAM,eAAe,GAAG,kBAAkB,EAAE,CAAC;YAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,GAAG,GAAG,CAAC,CAAC,CAAC;QACvD,CAAC;QACD,SAAS,EAAE,CAAC,KAAa,EAAE,EAAE;YAC3B,MAAM,YAAY,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrE,MAAM,aAAa,GAAG,YAAY,GAAG,GAAG,CAAC;YACzC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}
package/dist/adapters/index.d.ts ADDED
@@ -0,0 +1,4 @@
1
+ export type { FrameAdapter, FrameAdapterContext } from "./types";
2
+ export type { GSAPTimelineLike, CreateGSAPFrameAdapterOptions } from "./gsap";
3
+ export { createGSAPFrameAdapter } from "./gsap";
4
+ //# sourceMappingURL=index.d.ts.map
package/dist/adapters/index.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,6BAA6B,EAAE,MAAM,QAAQ,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,QAAQ,CAAC"}
package/dist/adapters/index.js ADDED
@@ -0,0 +1,2 @@
1
+ export { createGSAPFrameAdapter } from "./gsap";
2
+ //# sourceMappingURL=index.js.map
package/dist/adapters/index.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,QAAQ,CAAC"}
package/dist/adapters/types.d.ts ADDED
@@ -0,0 +1,15 @@
1
+ export interface FrameAdapterContext {
2
+ compositionId: string;
3
+ fps: number;
4
+ width: number;
5
+ height: number;
6
+ rootElement?: HTMLElement;
7
+ }
8
+ export interface FrameAdapter {
9
+ id: string;
10
+ init?: (ctx: FrameAdapterContext) => Promise<void> | void;
11
+ getDurationFrames: () => number;
12
+ seekFrame: (frame: number) => Promise<void> | void;
13
+ destroy?: () => Promise<void> | void;
14
+ }
15
+ //# sourceMappingURL=types.d.ts.map
package/dist/adapters/types.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1D,iBAAiB,EAAE,MAAM,MAAM,CAAC;IAChC,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACtC"}
package/dist/adapters/types.js ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
package/dist/adapters/types.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":""}
package/dist/compiler/htmlBundler.d.ts ADDED
@@ -0,0 +1,16 @@
1
+ import { type MediaDurationProber } from "./htmlCompiler";
2
+ export interface BundleOptions {
3
+ /** Optional media duration prober (e.g., ffprobe). If omitted, media durations are not resolved. */
4
+ probeMediaDuration?: MediaDurationProber;
5
+ }
6
+ /**
7
+ * Bundle a project's index.html into a single self-contained HTML file.
8
+ *
9
+ * - Compiles timing attributes and optionally resolves media durations
10
+ * - Injects the HyperFrames runtime script
11
+ * - Inlines local CSS and JS files
12
+ * - Inlines sub-composition HTML fragments (data-composition-src)
13
+ * - Inlines small textual assets as data URLs
14
+ */
15
+ export declare function bundleToSingleHtml(projectDir: string, options?: BundleOptions): Promise<string>;
16
+ //# sourceMappingURL=htmlBundler.d.ts.map
package/dist/compiler/htmlBundler.d.ts.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"file":"htmlBundler.d.ts","sourceRoot":"","sources":["../../src/compiler/htmlBundler.ts"],"names":[],"mappings":"AAIA,OAAO,EAAe,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AA6QvE,MAAM,WAAW,aAAa;IAC5B,oGAAoG;IACpG,kBAAkB,CAAC,EAAE,mBAAmB,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAkHrG"}