@peekling/runtime 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.
- package/AUTHORS +8 -0
- package/LICENSE +202 -0
- package/LICENSING.md +20 -0
- package/NOTICE +6 -0
- package/README.md +294 -0
- package/dist/configuration-validation.d.ts +19 -0
- package/dist/configuration-validation.d.ts.map +1 -0
- package/dist/configuration-validation.js +298 -0
- package/dist/content.d.ts +44 -0
- package/dist/content.d.ts.map +1 -0
- package/dist/content.js +738 -0
- package/dist/contracts.d.ts +10 -0
- package/dist/contracts.d.ts.map +1 -0
- package/dist/contracts.js +106 -0
- package/dist/defaults.d.ts +7 -0
- package/dist/defaults.d.ts.map +1 -0
- package/dist/defaults.js +6 -0
- package/dist/diagnostics.d.ts +25 -0
- package/dist/diagnostics.d.ts.map +1 -0
- package/dist/diagnostics.js +122 -0
- package/dist/direction.d.ts +3 -0
- package/dist/direction.d.ts.map +1 -0
- package/dist/direction.js +6 -0
- package/dist/errors.d.ts +15 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +53 -0
- package/dist/events.d.ts +5 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/events.js +60 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/input.d.ts +31 -0
- package/dist/input.d.ts.map +1 -0
- package/dist/input.js +215 -0
- package/dist/json.d.ts +3 -0
- package/dist/json.d.ts.map +1 -0
- package/dist/json.js +109 -0
- package/dist/loader.d.ts +33 -0
- package/dist/loader.d.ts.map +1 -0
- package/dist/loader.js +477 -0
- package/dist/locomotion.d.ts +8 -0
- package/dist/locomotion.d.ts.map +1 -0
- package/dist/locomotion.js +29 -0
- package/dist/normalized.d.ts +5 -0
- package/dist/normalized.d.ts.map +1 -0
- package/dist/normalized.js +266 -0
- package/dist/overrides.d.ts +29 -0
- package/dist/overrides.d.ts.map +1 -0
- package/dist/overrides.js +296 -0
- package/dist/own-data.d.ts +18 -0
- package/dist/own-data.d.ts.map +1 -0
- package/dist/own-data.js +205 -0
- package/dist/pack-api.d.ts +9 -0
- package/dist/pack-api.d.ts.map +1 -0
- package/dist/pack-api.js +6 -0
- package/dist/pack-shared.d.ts +28 -0
- package/dist/pack-shared.d.ts.map +1 -0
- package/dist/pack-shared.js +408 -0
- package/dist/pack.d.ts +6 -0
- package/dist/pack.d.ts.map +1 -0
- package/dist/pack.js +316 -0
- package/dist/peekling.css +1 -0
- package/dist/peekling.css.sri +1 -0
- package/dist/peekling.js +7469 -0
- package/dist/peekling.js.sri +1 -0
- package/dist/peekling.min.js +2 -0
- package/dist/peekling.min.js.sri +1 -0
- package/dist/plan-compiler.d.ts +82 -0
- package/dist/plan-compiler.d.ts.map +1 -0
- package/dist/plan-compiler.js +724 -0
- package/dist/plan.d.ts +21 -0
- package/dist/plan.d.ts.map +1 -0
- package/dist/plan.js +287 -0
- package/dist/preflight-api.d.ts +3 -0
- package/dist/preflight-api.d.ts.map +1 -0
- package/dist/preflight-api.js +1 -0
- package/dist/preflight.d.ts +22 -0
- package/dist/preflight.d.ts.map +1 -0
- package/dist/preflight.js +158 -0
- package/dist/registry.d.ts +9 -0
- package/dist/registry.d.ts.map +1 -0
- package/dist/registry.js +24 -0
- package/dist/renderer.d.ts +16 -0
- package/dist/renderer.d.ts.map +1 -0
- package/dist/renderer.js +176 -0
- package/dist/resolver.d.ts +3 -0
- package/dist/resolver.d.ts.map +1 -0
- package/dist/resolver.js +30 -0
- package/dist/runtime-diagnostics.d.ts +3 -0
- package/dist/runtime-diagnostics.d.ts.map +1 -0
- package/dist/runtime-diagnostics.js +5 -0
- package/dist/runtime-validation.d.ts +6 -0
- package/dist/runtime-validation.d.ts.map +1 -0
- package/dist/runtime-validation.js +104 -0
- package/dist/runtime.d.ts +87 -0
- package/dist/runtime.d.ts.map +1 -0
- package/dist/runtime.js +1015 -0
- package/dist/sections.d.ts +15 -0
- package/dist/sections.d.ts.map +1 -0
- package/dist/sections.js +221 -0
- package/dist/styles.d.ts +18 -0
- package/dist/styles.d.ts.map +1 -0
- package/dist/styles.js +132 -0
- package/dist/tooling-preflight.d.ts +23 -0
- package/dist/tooling-preflight.d.ts.map +1 -0
- package/dist/tooling-preflight.js +207 -0
- package/dist/tooling-validation.d.ts +8 -0
- package/dist/tooling-validation.d.ts.map +1 -0
- package/dist/tooling-validation.js +94 -0
- package/dist/types.d.ts +403 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +29 -0
- package/dist/visibility.d.ts +12 -0
- package/dist/visibility.d.ts.map +1 -0
- package/dist/visibility.js +333 -0
- package/dist/web-component.d.ts +31 -0
- package/dist/web-component.d.ts.map +1 -0
- package/dist/web-component.js +236 -0
- package/package.json +74 -0
package/AUTHORS
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
Peekling Runtime was originally designed and developed by Prajwal S. Venkateshmurthy (https://prajwal.me).
|
|
2
|
+
|
|
3
|
+
Other contributors are recorded in the repository history.
|
|
4
|
+
|
|
5
|
+
This is a factual authorship record. Licensing terms and applicable
|
|
6
|
+
notice-retention requirements are in LICENSE and NOTICE. Redistributions must
|
|
7
|
+
comply with Section 4 of the Apache License 2.0, including its applicable
|
|
8
|
+
notice-retention requirements.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
package/LICENSING.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Licensing and attribution
|
|
2
|
+
|
|
3
|
+
The Peekling Runtime code and documentation are licensed under Apache-2.0. The
|
|
4
|
+
license allows personal and commercial use, modification, distribution, and
|
|
5
|
+
sublicensing subject to its terms.
|
|
6
|
+
|
|
7
|
+
Redistributions must comply with Section 4 of the Apache License 2.0, including
|
|
8
|
+
its applicable notice-retention requirements. When a distribution includes a
|
|
9
|
+
`NOTICE` file, Section 4 describes how readable copies of applicable NOTICE
|
|
10
|
+
attributions may be provided. Apache-2.0 does not require every website using
|
|
11
|
+
Peekling to display a visible attribution.
|
|
12
|
+
|
|
13
|
+
`AUTHORS` is a factual authorship record and does not add a license condition.
|
|
14
|
+
Character art and character packs keep their own licenses. The Peekling name,
|
|
15
|
+
logo, official mascot, and other distinctive brand identity are outside this
|
|
16
|
+
code license except as allowed by applicable law or separate permission. See
|
|
17
|
+
Section 6 of Apache-2.0.
|
|
18
|
+
|
|
19
|
+
The Apache License text controls if this summary conflicts with it. This summary
|
|
20
|
+
is informational and is not legal advice.
|
package/NOTICE
ADDED
package/README.md
ADDED
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# `@peekling/runtime`
|
|
2
|
+
|
|
3
|
+
The dependency-free browser engine for data-only Peekling character Packs.
|
|
4
|
+
Developers choose a Pack and describe page behavior with one Configuration and
|
|
5
|
+
one immutable Plan. Peekling validates both before it renders.
|
|
6
|
+
|
|
7
|
+
The runtime performs no telemetry and requires no Peekling backend. Character
|
|
8
|
+
data cannot contain code, callbacks, DOM nodes, or raw HTML.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
npm install @peekling/runtime@0.1.0
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
The runtime supports modern ESM applications and the complete browser bundle.
|
|
17
|
+
Tooling and server-side imports require Node 22.14 or newer.
|
|
18
|
+
|
|
19
|
+
## First character with ESM
|
|
20
|
+
|
|
21
|
+
This Vite example emits the package stylesheet as an asset, selects the pinned
|
|
22
|
+
`peek` Pack, waits for the first valid runtime state, and owns teardown:
|
|
23
|
+
|
|
24
|
+
```js
|
|
25
|
+
import { hatch } from "@peekling/runtime";
|
|
26
|
+
import peeklingStyles from "@peekling/runtime/peekling.css?url";
|
|
27
|
+
|
|
28
|
+
let companion;
|
|
29
|
+
|
|
30
|
+
try {
|
|
31
|
+
companion = hatch({
|
|
32
|
+
character: "peek",
|
|
33
|
+
styles: { url: peeklingStyles },
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
await companion.ready;
|
|
37
|
+
} catch (error) {
|
|
38
|
+
console.error("Peekling did not start", error);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// Call this from the owning view's teardown hook.
|
|
42
|
+
export function destroyPeekling() {
|
|
43
|
+
companion?.destroy();
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
After `ready` resolves, the Pack, stylesheet, initial State, and owned DOM are
|
|
48
|
+
ready. `character: "peek"` is a networked selection. It resolves an exact pinned
|
|
49
|
+
manifest and verifies the manifest and selected atlas before browser decoding.
|
|
50
|
+
|
|
51
|
+
Other bundlers can copy `@peekling/runtime/peekling.css` to a public asset and
|
|
52
|
+
pass its final URL through `styles.url`. An HTTP or HTTPS ESM module can omit
|
|
53
|
+
`styles` when a usable `peekling.css` sits beside the module. A module location
|
|
54
|
+
that cannot identify an HTTP or HTTPS stylesheet fails with `styles.default`
|
|
55
|
+
instead of silently rendering without styles.
|
|
56
|
+
|
|
57
|
+
## Choose a Pack
|
|
58
|
+
|
|
59
|
+
Configure one source when possible:
|
|
60
|
+
|
|
61
|
+
| Source | Example | Network behavior |
|
|
62
|
+
| ----------------- | -------------------------------------------------- | ------------------------------------------------------------- |
|
|
63
|
+
| Registered alias | `{ character: "peek" }` | Fetches the alias's pinned manifest and one atlas. |
|
|
64
|
+
| Explicit manifest | `{ packUrl: "/characters/moss/character.json" }` | Fetches that manifest and one declared atlas. |
|
|
65
|
+
| Inline Pack | `{ pack, atlasUrl: "/characters/moss/atlas.png" }` | Uses supplied Pack data and fetches the declared atlas bytes. |
|
|
66
|
+
|
|
67
|
+
If merged Configuration contains several sources, the runtime uses `pack` first,
|
|
68
|
+
then `packUrl`, then `character`. `atlasUrl` changes only the asset location for
|
|
69
|
+
bytes already declared by the selected Pack. It is not an image conversion hook.
|
|
70
|
+
|
|
71
|
+
Every atlas candidate needs a 64-character lowercase SHA-256. For an adaptive
|
|
72
|
+
Pack used with `atlasUrl`, set `density` to one declared variant. The runtime
|
|
73
|
+
loads that candidate once and disables automatic density upgrades for the
|
|
74
|
+
mirrored asset.
|
|
75
|
+
|
|
76
|
+
## Public instance API
|
|
77
|
+
|
|
78
|
+
`hatch` returns one independently owned instance:
|
|
79
|
+
|
|
80
|
+
| Member | Purpose |
|
|
81
|
+
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
82
|
+
| `ready` | Rejecting startup promise. Await it before relying on Pack-specific behavior. |
|
|
83
|
+
| `finished` | Non-rejecting terminal promise. Settles after cleanup with `destroyed`, `pagehide`, or `failed`. |
|
|
84
|
+
| `emit(name, payload)` | Admit one bounded application Event and return its admission result. |
|
|
85
|
+
| `override(input)` | Request temporary ownership of declared presentation channels. |
|
|
86
|
+
| `pause()` | Add the host pause reason and park runtime work. |
|
|
87
|
+
| `resume()` | Remove the host pause reason. Work resumes after every suspension reason clears. |
|
|
88
|
+
| `destroy()` | Abort pending work and release the instance's listeners, observers, frames, timers, roots, and object URLs. |
|
|
89
|
+
|
|
90
|
+
Configuration failures that can be decided without Pack bytes throw before
|
|
91
|
+
`hatch` returns. Pack loading, Pack-dependent references, stylesheet setup, and
|
|
92
|
+
browser resource failures reject `ready`. Wrap both stages in the same `try`
|
|
93
|
+
block when the host needs one startup error path.
|
|
94
|
+
|
|
95
|
+
`finished` never rejects and settles once. Cleanup is idempotent, so calling
|
|
96
|
+
`destroy()` again is safe.
|
|
97
|
+
|
|
98
|
+
## Events and temporary control
|
|
99
|
+
|
|
100
|
+
Application Events are bounded immutable facts:
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
await companion.ready;
|
|
104
|
+
|
|
105
|
+
const result = companion.emit("job.progress", {
|
|
106
|
+
session: "build-42",
|
|
107
|
+
revision: 3,
|
|
108
|
+
completed: 12,
|
|
109
|
+
total: 20,
|
|
110
|
+
});
|
|
111
|
+
|
|
112
|
+
if (!result.accepted) {
|
|
113
|
+
console.warn("Event was not admitted", result.reason);
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
`emit` does not mutate the Plan, render inline, or run host code inline. It
|
|
118
|
+
validates and snapshots the payload, then schedules ordinary Plan evaluation.
|
|
119
|
+
The queue holds 32 Events. A full queue rejects the new Event without evicting
|
|
120
|
+
accepted work. Eligible streams can opt into `coalesce: "latest"`. Other rate
|
|
121
|
+
limits belong in host code before `emit`.
|
|
122
|
+
|
|
123
|
+
An Override uses the same Effect and channel model as the Plan:
|
|
124
|
+
|
|
125
|
+
```js
|
|
126
|
+
const handle = companion.override({
|
|
127
|
+
effect: {
|
|
128
|
+
channels: ["state"],
|
|
129
|
+
state: { state: "happy" },
|
|
130
|
+
},
|
|
131
|
+
until: { type: "duration", ms: 2000 },
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
console.log(await handle.finished);
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
The selected State must exist in the Pack. An Override never edits the Plan.
|
|
138
|
+
When its lifetime ends, the runtime reevaluates the unchanged Plan from current
|
|
139
|
+
world state.
|
|
140
|
+
|
|
141
|
+
See the repository [configuration guide](../../docs/configuration.md) for Plan
|
|
142
|
+
syntax and recipes. The [execution model](../../docs/execution-model.md) defines
|
|
143
|
+
Event ordering, channel ownership, Override conflicts, and cleanup.
|
|
144
|
+
|
|
145
|
+
## Web Component
|
|
146
|
+
|
|
147
|
+
The complete browser file registers `<peekling-character>` when that name is
|
|
148
|
+
free. The element is a lifecycle facade over hatch, not a second engine.
|
|
149
|
+
|
|
150
|
+
```html
|
|
151
|
+
<script
|
|
152
|
+
defer
|
|
153
|
+
src="https://cdn.jsdelivr.net/npm/@peekling/runtime@0.1.0/dist/peekling.min.js"
|
|
154
|
+
integrity="sha384-<runtime-release-hash>"
|
|
155
|
+
crossorigin="anonymous"
|
|
156
|
+
></script>
|
|
157
|
+
|
|
158
|
+
<peekling-character
|
|
159
|
+
character="peek"
|
|
160
|
+
styles-url="https://cdn.jsdelivr.net/npm/@peekling/runtime@0.1.0/dist/peekling.css"
|
|
161
|
+
styles-integrity="sha256-<stylesheet-release-hash>"
|
|
162
|
+
></peekling-character>
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Replace both integrity placeholders with the values emitted by the selected
|
|
166
|
+
release. Cross-origin JavaScript and CSS need CORS. The page must allow the
|
|
167
|
+
runtime, stylesheet, manifest, atlas fetch, and verified Blob atlas through its
|
|
168
|
+
CSP.
|
|
169
|
+
|
|
170
|
+
Connection hatches one instance. Disconnection destroys it. Reconnection gets a
|
|
171
|
+
new `ready` promise and a fresh instance. Object values such as `plan`,
|
|
172
|
+
`content`, `bindings`, `theme`, `styles`, `accessibility`, `diagnostics`, and
|
|
173
|
+
`logger` are JavaScript properties. Scalar Pack and stylesheet selections also
|
|
174
|
+
have documented attributes.
|
|
175
|
+
|
|
176
|
+
Importing the ESM root does not register the element or create a browser global.
|
|
177
|
+
Call `definePeeklingElement()` explicitly when an ESM application wants the
|
|
178
|
+
declarative facade.
|
|
179
|
+
|
|
180
|
+
The browser file claims `globalThis.Peekling` and `<peekling-character>`
|
|
181
|
+
independently. It never overwrites a host value or foreign custom element. A
|
|
182
|
+
collision dispatches `peekling:collision` on `globalThis` and names the occupied
|
|
183
|
+
surface in `event.detail`.
|
|
184
|
+
|
|
185
|
+
## Content and trusted host code
|
|
186
|
+
|
|
187
|
+
Packs and serialized Configuration remain data only. A Plan Effect may select a
|
|
188
|
+
named content item and immutable data. Built-in text and links render through
|
|
189
|
+
safe DOM operations.
|
|
190
|
+
|
|
191
|
+
Trusted JavaScript Configuration may register a mount function for custom host
|
|
192
|
+
content. Peekling supplies an empty engine-owned root, immutable data, an
|
|
193
|
+
`AbortSignal`, and an `emit` helper. The host creates nodes with DOM APIs and
|
|
194
|
+
returns cleanup. Peekling contains mount, update, cleanup, and rejected-promise
|
|
195
|
+
failures to that surface. The scheduler never waits for host code.
|
|
196
|
+
|
|
197
|
+
Framework adapters, if used, belong above this mount seam. They do not become
|
|
198
|
+
runtime dependencies or introduce another scheduler.
|
|
199
|
+
|
|
200
|
+
## Lifecycle and visibility
|
|
201
|
+
|
|
202
|
+
Host pause, hidden-page suspension, page lifecycle, and site dismissal are
|
|
203
|
+
composable reasons. The instance resumes only after every active reason clears.
|
|
204
|
+
Ordinary parked instances own no runtime animation frame, Plan timer, or
|
|
205
|
+
evaluator work. A clock-based dismissal owns one recovery timeout until show,
|
|
206
|
+
expiry, or teardown.
|
|
207
|
+
|
|
208
|
+
Reduced motion is a rendering policy, not another Plan. It shows a validated
|
|
209
|
+
static tableau and suppresses incompatible motion while preserving host-page
|
|
210
|
+
interaction.
|
|
211
|
+
|
|
212
|
+
Direct hatch integrations in single-page applications must call `destroy()` when
|
|
213
|
+
the owning view unmounts. `pushState`, hash changes, and client-side route
|
|
214
|
+
changes do not end the document. A disconnected Web Component performs its own
|
|
215
|
+
teardown.
|
|
216
|
+
|
|
217
|
+
The public visibility helpers let a host provide a normal recovery action after
|
|
218
|
+
site dismissal:
|
|
219
|
+
|
|
220
|
+
```js
|
|
221
|
+
import {
|
|
222
|
+
hidePeekling,
|
|
223
|
+
isPeeklingHidden,
|
|
224
|
+
showPeekling,
|
|
225
|
+
} from "@peekling/runtime";
|
|
226
|
+
|
|
227
|
+
hidePeekling("1-hour");
|
|
228
|
+
console.log(isPeeklingHidden());
|
|
229
|
+
showPeekling();
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Browser and security boundary
|
|
233
|
+
|
|
234
|
+
- Pack data is schema-validated, bounded, and never evaluated.
|
|
235
|
+
- Pack strings never enter HTML-parsing sinks.
|
|
236
|
+
- The character root is `aria-hidden` and pointer-transparent.
|
|
237
|
+
- Browser listeners are passive and never cancel host interaction.
|
|
238
|
+
- Strict CSP needs no `unsafe-inline` or `unsafe-eval` exception.
|
|
239
|
+
- The runtime sends no telemetry and opens no WebSocket or event stream.
|
|
240
|
+
- Closed Shadow DOM provides encapsulation, not a security boundary.
|
|
241
|
+
- Host code and Peekling still share the browser main thread.
|
|
242
|
+
|
|
243
|
+
Manifest and atlas origins belong in `connect-src`. The verified atlas renders
|
|
244
|
+
from a browser-created Blob URL, so `img-src` must allow `blob:`. The runtime
|
|
245
|
+
script uses `script-src`, and `peekling.css` uses `style-src`. See
|
|
246
|
+
[compatibility and hosting](../../docs/compatibility-and-hosting.md) for CORS,
|
|
247
|
+
SRI, MIME, caching, self-hosting, diagnostics, and browser limits.
|
|
248
|
+
|
|
249
|
+
For symptom-to-action help with startup, Pack loading, CSP, lifecycle, and Event
|
|
250
|
+
admission, use the repository
|
|
251
|
+
[troubleshooting guide](../../docs/troubleshooting.md).
|
|
252
|
+
|
|
253
|
+
## Package entry points
|
|
254
|
+
|
|
255
|
+
| Import | Contents |
|
|
256
|
+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
257
|
+
| `@peekling/runtime` | Side-effect-free ESM hatch API, public types, visibility helpers, and explicit Web Component registration. |
|
|
258
|
+
| `@peekling/runtime/browser` | Complete browser-global artifact. |
|
|
259
|
+
| `@peekling/runtime/peekling.css` | Required runtime stylesheet asset. |
|
|
260
|
+
| `@peekling/runtime/pack` | Supported Pack parsing and validation surface for authoring tools. |
|
|
261
|
+
| `@peekling/runtime/preflight` | Node-safe validation tooling used by developer packages. |
|
|
262
|
+
|
|
263
|
+
Internal compilers, evaluators, queues, renderers, schedulers, and browser host
|
|
264
|
+
classes are package-private. `@peekling/preflight`, `@peekling/vite`,
|
|
265
|
+
`@peekling/cli`, and `@peekling/adapter-codex-pet` are separate packages. They
|
|
266
|
+
do not enter the complete browser JavaScript artifact.
|
|
267
|
+
|
|
268
|
+
## Verification and size
|
|
269
|
+
|
|
270
|
+
Browser tests cover strict CSP, ESM and browser hatch, Web Component lifecycle,
|
|
271
|
+
host surfaces, blocked stylesheets, suspension, dismissal recovery, remount
|
|
272
|
+
cleanup, hostile host layout, root repair, and contained failures in Chromium,
|
|
273
|
+
Firefox, and WebKit.
|
|
274
|
+
|
|
275
|
+
<!-- peekling-size-evidence:start -->
|
|
276
|
+
|
|
277
|
+
The recorded canonical delivery measurement is 32,287 bytes gzip and 28,635
|
|
278
|
+
bytes Brotli. Against the 32 KiB gzip and 32 KiB Brotli caps, that recorded
|
|
279
|
+
build leaves 481 bytes of gzip headroom and 4,133 bytes of Brotli headroom.
|
|
280
|
+
After the required 256-byte reserve, 225 gzip bytes and 3,877 Brotli bytes
|
|
281
|
+
remain for that build.
|
|
282
|
+
<!-- peekling-size-evidence:end -->
|
|
283
|
+
|
|
284
|
+
The record is bound to artifact hashes. Node 22.14.0, npm 11.16.0, and Node's
|
|
285
|
+
default zlib compression certify the recorded values. Other supported Node
|
|
286
|
+
versions still enforce their local size cap and reserve.
|
|
287
|
+
|
|
288
|
+
The [browser performance guide](../../docs/browser-performance.md) explains the
|
|
289
|
+
three-browser release harness and what its result can and cannot prove.
|
|
290
|
+
|
|
291
|
+
## License
|
|
292
|
+
|
|
293
|
+
Apache-2.0. Character artwork keeps its own Pack license. See
|
|
294
|
+
[licensing and attribution](LICENSING.md).
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { PeeklingOptions } from "./runtime.js";
|
|
2
|
+
import { type HostContent } from "./types.js";
|
|
3
|
+
export type ConfigurationFaultSink = (code: string, path: string, detail?: string) => void;
|
|
4
|
+
export interface RuntimeConfigurationIssue {
|
|
5
|
+
readonly code: string;
|
|
6
|
+
readonly path: string;
|
|
7
|
+
readonly message: string;
|
|
8
|
+
}
|
|
9
|
+
export declare class PeeklingPreflightError extends TypeError {
|
|
10
|
+
readonly issues: readonly RuntimeConfigurationIssue[];
|
|
11
|
+
constructor(code: string, path: string, message: string);
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Validate shared Configuration semantics without selecting presentation prose.
|
|
15
|
+
* A throwing sink is fail-fast. A collecting sink receives every safe fault.
|
|
16
|
+
*/
|
|
17
|
+
export declare function validateConfiguration(options: PeeklingOptions, baseUrl: string, fault: ConfigurationFaultSink): HostContent;
|
|
18
|
+
export declare function validRuntimeName(value: PeeklingOptions["name"]): boolean;
|
|
19
|
+
//# sourceMappingURL=configuration-validation.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"configuration-validation.d.ts","sourceRoot":"","sources":["../src/configuration-validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AA4B/D,MAAM,MAAM,sBAAsB,GAAG,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,KACZ,IAAI,CAAC;AAEV,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,sBAAuB,SAAQ,SAAS;IACnD,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAEtD,YAAY,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAItD;CACF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,sBAAsB,GAC5B,WAAW,CA4Ib;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,GAAG,OAAO,CAExE"}
|