frameyard 0.2.0 → 0.4.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 (112) hide show
  1. package/CHANGELOG.md +102 -0
  2. package/GLOSSARY.md +58 -2
  3. package/README.md +185 -95
  4. package/dist/bindings.d.ts +42 -0
  5. package/dist/bindings.d.ts.map +1 -0
  6. package/dist/bindings.js +144 -0
  7. package/dist/bindings.js.map +1 -0
  8. package/dist/cli.js +37 -14
  9. package/dist/cli.js.map +1 -1
  10. package/dist/contracts.d.ts +73 -47
  11. package/dist/contracts.d.ts.map +1 -1
  12. package/dist/contracts.js +14 -159
  13. package/dist/contracts.js.map +1 -1
  14. package/dist/errors.d.ts +15 -4
  15. package/dist/errors.d.ts.map +1 -1
  16. package/dist/errors.js +8 -0
  17. package/dist/errors.js.map +1 -1
  18. package/dist/html/index.d.ts +5 -0
  19. package/dist/html/index.d.ts.map +1 -0
  20. package/dist/html/index.js +3 -0
  21. package/dist/html/index.js.map +1 -0
  22. package/dist/html/parse.d.ts +30 -0
  23. package/dist/html/parse.d.ts.map +1 -0
  24. package/dist/html/parse.js +80 -0
  25. package/dist/html/parse.js.map +1 -0
  26. package/dist/html/validate.d.ts +14 -0
  27. package/dist/html/validate.d.ts.map +1 -0
  28. package/dist/html/validate.js +931 -0
  29. package/dist/html/validate.js.map +1 -0
  30. package/dist/index.d.ts +2 -2
  31. package/dist/index.d.ts.map +1 -1
  32. package/dist/index.js +1 -1
  33. package/dist/index.js.map +1 -1
  34. package/dist/preview/main.d.ts +12 -3
  35. package/dist/preview/main.d.ts.map +1 -1
  36. package/dist/preview/main.js +208 -85
  37. package/dist/preview/main.js.map +1 -1
  38. package/dist/project.d.ts +2 -0
  39. package/dist/project.d.ts.map +1 -1
  40. package/dist/project.js +4 -0
  41. package/dist/project.js.map +1 -1
  42. package/dist/renderer/audio.d.ts +5 -1
  43. package/dist/renderer/audio.d.ts.map +1 -1
  44. package/dist/renderer/audio.js +4 -0
  45. package/dist/renderer/audio.js.map +1 -1
  46. package/dist/renderer/browser.d.ts +12 -1
  47. package/dist/renderer/browser.d.ts.map +1 -1
  48. package/dist/renderer/browser.js +69 -11
  49. package/dist/renderer/browser.js.map +1 -1
  50. package/dist/renderer/index.d.ts +30 -5
  51. package/dist/renderer/index.d.ts.map +1 -1
  52. package/dist/renderer/index.js +204 -26
  53. package/dist/renderer/index.js.map +1 -1
  54. package/dist/runtime/bindings.d.ts +11 -0
  55. package/dist/runtime/bindings.d.ts.map +1 -0
  56. package/dist/runtime/bindings.js +164 -0
  57. package/dist/runtime/bindings.js.map +1 -0
  58. package/dist/runtime/diagnostics.d.ts +4 -0
  59. package/dist/runtime/diagnostics.d.ts.map +1 -0
  60. package/dist/runtime/diagnostics.js +107 -0
  61. package/dist/runtime/diagnostics.js.map +1 -0
  62. package/dist/runtime/host.d.ts +12 -0
  63. package/dist/runtime/host.d.ts.map +1 -0
  64. package/dist/runtime/host.js +701 -0
  65. package/dist/runtime/host.js.map +1 -0
  66. package/dist/runtime/index.d.ts +0 -26
  67. package/dist/runtime/index.d.ts.map +1 -1
  68. package/dist/runtime/index.js +0 -286
  69. package/dist/runtime/index.js.map +1 -1
  70. package/dist/runtime/media.d.ts +16 -0
  71. package/dist/runtime/media.d.ts.map +1 -0
  72. package/dist/runtime/media.js +307 -0
  73. package/dist/runtime/media.js.map +1 -0
  74. package/dist/scaffold.d.ts.map +1 -1
  75. package/dist/scaffold.js +169 -78
  76. package/dist/scaffold.js.map +1 -1
  77. package/dist/server/composition-html.d.ts +20 -0
  78. package/dist/server/composition-html.d.ts.map +1 -0
  79. package/dist/server/composition-html.js +45 -0
  80. package/dist/server/composition-html.js.map +1 -0
  81. package/dist/server/preview-html.d.ts.map +1 -1
  82. package/dist/server/preview-html.js +19 -14
  83. package/dist/server/preview-html.js.map +1 -1
  84. package/dist/server/server.d.ts.map +1 -1
  85. package/dist/server/server.js +94 -6
  86. package/dist/server/server.js.map +1 -1
  87. package/dist/version.d.ts +1 -1
  88. package/dist/version.js +1 -1
  89. package/docs/adr/0001-keep-composition-authoring-web-native.md +2 -0
  90. package/docs/adr/0003-render-browser-frames-offline.md +2 -0
  91. package/docs/adr/0005-keep-parallel-rendering-opt-in-and-frame-ordered.md +3 -0
  92. package/docs/adr/0006-seek-embedded-media-from-the-frame-clock.md +11 -0
  93. package/docs/adr/0007-make-html-documents-the-composition-unit.md +31 -0
  94. package/docs/migration-0.4.md +279 -0
  95. package/docs/v0.1-design.md +82 -57
  96. package/examples/demo/README.md +7 -3
  97. package/examples/demo/compositions/demo.controller.js +120 -0
  98. package/examples/demo/compositions/demo.html +253 -0
  99. package/examples/demo/video.config.js +1 -1
  100. package/package.json +9 -3
  101. package/skills/frameyard/README.md +4 -0
  102. package/skills/frameyard/SKILL.md +41 -11
  103. package/skills/frameyard/references/audio-assets.md +25 -14
  104. package/skills/frameyard/references/bindings.md +73 -0
  105. package/skills/frameyard/references/common-mistakes.md +59 -0
  106. package/skills/frameyard/references/controllers.md +126 -0
  107. package/skills/frameyard/references/deterministic-authoring.md +160 -41
  108. package/skills/frameyard/references/diagnostics.md +90 -0
  109. package/skills/frameyard/references/failure-recovery.md +38 -12
  110. package/skills/frameyard/references/json-results.md +43 -8
  111. package/skills/frameyard/references/subtitles-karaoke.md +10 -18
  112. package/examples/demo/compositions/demo.js +0 -206
@@ -0,0 +1,107 @@
1
+ function installDiagnosticsClock() {
2
+ const warnings = new Set();
3
+ const originalRandom = Math.random;
4
+ const originalDateNow = Date.now;
5
+ const originalSetTimeout = window.setTimeout;
6
+ const originalSetInterval = window.setInterval;
7
+ const originalRaf = window.requestAnimationFrame;
8
+ const perf = performance;
9
+ const originalPerfNow = perf.now;
10
+ let perfPatched = false;
11
+ Math.random = () => {
12
+ warnings.add("Math.random()");
13
+ return originalRandom();
14
+ };
15
+ Date.now = () => {
16
+ warnings.add("Date.now()");
17
+ return originalDateNow();
18
+ };
19
+ window.setTimeout = ((handler, timeout, ...args) => {
20
+ warnings.add("setTimeout()");
21
+ return originalSetTimeout(handler, timeout, ...args);
22
+ });
23
+ window.setInterval = ((handler, timeout, ...args) => {
24
+ warnings.add("setInterval()");
25
+ return originalSetInterval(handler, timeout, ...args);
26
+ });
27
+ window.requestAnimationFrame = ((callback) => {
28
+ warnings.add("requestAnimationFrame()");
29
+ return originalRaf(callback);
30
+ });
31
+ try {
32
+ perf.now = () => {
33
+ warnings.add("performance.now()");
34
+ return originalPerfNow();
35
+ };
36
+ perfPatched = true;
37
+ }
38
+ catch {
39
+ // Some engines make performance.now non-writable; skip that signal.
40
+ }
41
+ return {
42
+ warnings,
43
+ restore() {
44
+ Math.random = originalRandom;
45
+ Date.now = originalDateNow;
46
+ window.setTimeout = originalSetTimeout;
47
+ window.setInterval = originalSetInterval;
48
+ window.requestAnimationFrame = originalRaf;
49
+ if (perfPatched) {
50
+ perf.now = originalPerfNow;
51
+ }
52
+ },
53
+ };
54
+ }
55
+ function diagnosticsMessage(scope, frame, warning) {
56
+ const location = frame === null ? "" : ` at frame ${frame}`;
57
+ switch (warning) {
58
+ case "Math.random()":
59
+ return `${scope}${location} used Math.random(); use random("stable:key") for deterministic values.`;
60
+ case "Date.now()":
61
+ case "performance.now()":
62
+ return `${scope}${location} read ${warning}; derive time from the frame and frame rate.`;
63
+ default:
64
+ return `${scope}${location} used ${warning}; drive animation from update({ frame }).`;
65
+ }
66
+ }
67
+ export function withDiagnosticsSync(scope, frame, diagnostics, callback) {
68
+ if (!diagnostics) {
69
+ return callback();
70
+ }
71
+ const clock = installDiagnosticsClock();
72
+ try {
73
+ return callback();
74
+ }
75
+ finally {
76
+ clock.restore();
77
+ for (const warning of clock.warnings) {
78
+ try {
79
+ diagnostics(diagnosticsMessage(scope, frame, warning));
80
+ }
81
+ catch {
82
+ // Diagnostics must never affect composition execution.
83
+ }
84
+ }
85
+ }
86
+ }
87
+ export async function withDiagnosticsAsync(scope, diagnostics, callback) {
88
+ if (!diagnostics) {
89
+ return callback();
90
+ }
91
+ const clock = installDiagnosticsClock();
92
+ try {
93
+ return await callback();
94
+ }
95
+ finally {
96
+ clock.restore();
97
+ for (const warning of clock.warnings) {
98
+ try {
99
+ diagnostics(diagnosticsMessage(scope, null, warning));
100
+ }
101
+ catch {
102
+ // Diagnostics must never affect composition execution.
103
+ }
104
+ }
105
+ }
106
+ }
107
+ //# sourceMappingURL=diagnostics.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/runtime/diagnostics.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,12 @@
1
+ import { type FrameyardHost } from "../contracts.js";
2
+ export declare function createFrameyardHost(): Promise<FrameyardHost>;
3
+ declare global {
4
+ interface Window {
5
+ __fy: FrameyardHost;
6
+ __fyError?: {
7
+ code: string;
8
+ message: string;
9
+ };
10
+ }
11
+ }
12
+ //# sourceMappingURL=host.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/runtime/host.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,aAAa,EAInB,MAAM,iBAAiB,CAAC;AAuxBzB,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,aAAa,CAAC,CAiClE;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,IAAI,EAAE,aAAa,CAAC;QACpB,SAAS,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAC/C;CACF"}