@blankgrimoire/runtime 0.0.0-stage → 1.0.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.
@@ -0,0 +1,49 @@
1
+ import type { Page } from '@blankgrimoire/types';
2
+ import type { DocumentLike, ParseHTML, WindowLike } from './dom.js';
3
+ import { type CssStrategy } from './css.js';
4
+ export interface ScriptJSONStrategy {
5
+ kind: 'scriptJSON';
6
+ pattern: string;
7
+ path: string;
8
+ base64?: boolean;
9
+ }
10
+ export interface HydrationStrategy {
11
+ kind: 'hydration';
12
+ framework: 'next' | 'nuxt';
13
+ path?: string;
14
+ }
15
+ export interface AjaxStrategy {
16
+ kind: 'ajax';
17
+ method: 'GET' | 'POST';
18
+ path: string;
19
+ body?: string;
20
+ then: unknown;
21
+ }
22
+ export interface StrategyEnvironment {
23
+ baseURL: string;
24
+ window?: WindowLike;
25
+ parseHTML?: ParseHTML;
26
+ }
27
+ /**
28
+ * Parse a JSON value from script text. Inline scripts often wrap the payload
29
+ * in an assignment (`window.__DATA__ = {...}`), so fall back to the first
30
+ * balanced object or array.
31
+ */
32
+ export declare function parseJSONText(text: string): unknown;
33
+ /** Dot/bracket path lookup, e.g. `props.pageProps.pages` or `items[0].url`. */
34
+ export declare function readPath(value: unknown, path: string): unknown;
35
+ /** Normalise a strategy payload (URL strings or page objects) into `Page[]`. */
36
+ export declare function toPages(payload: unknown, baseURL: string, headers?: Record<string, string>): Page[];
37
+ /**
38
+ * Extract pages from a JSON script. Inline scripts are parsed first; a
39
+ * matching external script is fetched through the native bridge. Failed
40
+ * scripts are skipped so later candidates can still succeed.
41
+ */
42
+ export declare function extractScriptJSON(strategy: ScriptJSONStrategy, document: DocumentLike, baseURL: string, parseHTML?: ParseHTML): Promise<Page[]>;
43
+ /** Extract pages from a Next.js or Nuxt hydration payload. */
44
+ export declare function extractHydration(strategy: HydrationStrategy, document: DocumentLike, baseURL: string, windowObj?: WindowLike): Page[];
45
+ /** Fetch a URL and apply the nested strategy to the response HTML. */
46
+ export declare function extractAjax(strategy: AjaxStrategy, document: DocumentLike, environment: StrategyEnvironment, depth?: number): Promise<Page[]>;
47
+ /** Run one strategy. A strategy returns `[]` when it does not match. */
48
+ export declare function runStrategy(strategy: unknown, document: DocumentLike, environment: StrategyEnvironment, depth?: number): Promise<Page[]>;
49
+ export type { CssStrategy };
@@ -0,0 +1,282 @@
1
+ // SPDX-License-Identifier: MIT
2
+ import { attr, queryAll, resolveURL, textOf } from './dom.js';
3
+ import { __http, __parseHTML } from './prelude.js';
4
+ import { extractCss } from './css.js';
5
+ const MAX_AJAX_DEPTH = 5;
6
+ function base64Decode(input) {
7
+ try {
8
+ if (typeof atob !== 'undefined') {
9
+ return atob(input);
10
+ }
11
+ const buffer = globalThis.Buffer;
12
+ if (buffer) {
13
+ return buffer.from(input, 'base64').toString('utf-8');
14
+ }
15
+ throw new Error('no base64 decoder available');
16
+ }
17
+ catch {
18
+ return input;
19
+ }
20
+ }
21
+ /**
22
+ * Parse a JSON value from script text. Inline scripts often wrap the payload
23
+ * in an assignment (`window.__DATA__ = {...}`), so fall back to the first
24
+ * balanced object or array.
25
+ */
26
+ export function parseJSONText(text) {
27
+ const trimmed = text.trim();
28
+ try {
29
+ return JSON.parse(trimmed);
30
+ }
31
+ catch {
32
+ // Fall through to the balanced-value scanner.
33
+ }
34
+ const start = trimmed.search(/[[{]/);
35
+ if (start === -1) {
36
+ return undefined;
37
+ }
38
+ const stack = [];
39
+ let inString = false;
40
+ let escaped = false;
41
+ for (let index = start; index < trimmed.length; index += 1) {
42
+ const character = trimmed[index];
43
+ if (character === undefined) {
44
+ break;
45
+ }
46
+ if (inString) {
47
+ if (escaped) {
48
+ escaped = false;
49
+ }
50
+ else if (character === '\\') {
51
+ escaped = true;
52
+ }
53
+ else if (character === '"') {
54
+ inString = false;
55
+ }
56
+ continue;
57
+ }
58
+ if (character === '"') {
59
+ inString = true;
60
+ continue;
61
+ }
62
+ if (character === '{' || character === '[') {
63
+ stack.push(character);
64
+ continue;
65
+ }
66
+ if (character === '}' || character === ']') {
67
+ const open = stack.pop();
68
+ if (open === undefined ||
69
+ (open === '{' && character !== '}') ||
70
+ (open === '[' && character !== ']')) {
71
+ return undefined;
72
+ }
73
+ if (stack.length === 0) {
74
+ try {
75
+ return JSON.parse(trimmed.slice(start, index + 1));
76
+ }
77
+ catch {
78
+ return undefined;
79
+ }
80
+ }
81
+ }
82
+ }
83
+ return undefined;
84
+ }
85
+ /** Dot/bracket path lookup, e.g. `props.pageProps.pages` or `items[0].url`. */
86
+ export function readPath(value, path) {
87
+ if (path.trim() === '') {
88
+ return value;
89
+ }
90
+ let current = value;
91
+ for (const rawPart of path.split('.')) {
92
+ const match = /^([^[\]]*)(?:\[(\d+)\])?$/.exec(rawPart);
93
+ if (!match) {
94
+ return undefined;
95
+ }
96
+ const key = match[1] ?? '';
97
+ if (key !== '') {
98
+ current = current?.[key];
99
+ }
100
+ if (match[2] !== undefined) {
101
+ current = current?.[Number(match[2])];
102
+ }
103
+ if (current === undefined || current === null) {
104
+ return undefined;
105
+ }
106
+ }
107
+ return current;
108
+ }
109
+ function pageURLFromItem(item) {
110
+ if (typeof item === 'string') {
111
+ return item.trim() === '' ? null : item;
112
+ }
113
+ if (item && typeof item === 'object') {
114
+ const record = item;
115
+ for (const key of ['imageURL', 'url', 'src', 'image']) {
116
+ const value = record[key];
117
+ if (typeof value === 'string' && value.trim() !== '') {
118
+ return value;
119
+ }
120
+ }
121
+ }
122
+ return null;
123
+ }
124
+ /** Normalise a strategy payload (URL strings or page objects) into `Page[]`. */
125
+ export function toPages(payload, baseURL, headers) {
126
+ const candidates = Array.isArray(payload) ? payload : [payload];
127
+ const pages = [];
128
+ for (const candidate of candidates) {
129
+ const value = pageURLFromItem(candidate);
130
+ if (!value) {
131
+ continue;
132
+ }
133
+ const page = {
134
+ index: pages.length,
135
+ imageURL: resolveURL(value, baseURL),
136
+ };
137
+ if (headers) {
138
+ page.headers = { ...headers };
139
+ }
140
+ pages.push(page);
141
+ }
142
+ return pages;
143
+ }
144
+ /**
145
+ * Extract pages from a JSON script. Inline scripts are parsed first; a
146
+ * matching external script is fetched through the native bridge. Failed
147
+ * scripts are skipped so later candidates can still succeed.
148
+ */
149
+ export async function extractScriptJSON(strategy, document, baseURL, parseHTML) {
150
+ void parseHTML;
151
+ const regex = new RegExp(strategy.pattern);
152
+ for (const script of queryAll(document, 'script')) {
153
+ const text = textOf(script);
154
+ const src = attr(script, 'src');
155
+ let content = '';
156
+ if (text !== '' && regex.test(text)) {
157
+ content = text;
158
+ }
159
+ else if (src && regex.test(src)) {
160
+ try {
161
+ const response = await __http({ url: resolveURL(src, baseURL), method: 'GET' });
162
+ if (response.status < 200 || response.status >= 300) {
163
+ continue;
164
+ }
165
+ content = response.body;
166
+ }
167
+ catch {
168
+ continue;
169
+ }
170
+ }
171
+ else {
172
+ continue;
173
+ }
174
+ try {
175
+ const decoded = strategy.base64 ? base64Decode(content) : content;
176
+ const parsed = parseJSONText(decoded);
177
+ if (parsed === undefined) {
178
+ continue;
179
+ }
180
+ const payload = readPath(parsed, strategy.path);
181
+ if (payload === undefined || payload === null) {
182
+ continue;
183
+ }
184
+ const pages = toPages(payload, baseURL);
185
+ if (pages.length > 0) {
186
+ return pages;
187
+ }
188
+ }
189
+ catch {
190
+ // Malformed JSON or unresolved path: try the next script.
191
+ }
192
+ }
193
+ return [];
194
+ }
195
+ function hydrationPayload(strategy, document, windowObj) {
196
+ if (windowObj) {
197
+ const value = strategy.framework === 'next' ? windowObj.__NEXT_DATA__ : windowObj.__NUXT__;
198
+ if (value !== undefined) {
199
+ return value;
200
+ }
201
+ }
202
+ const selectors = strategy.framework === 'next'
203
+ ? ['#__NEXT_DATA__']
204
+ : ['#__NUXT_DATA__', '#__NUXT__'];
205
+ for (const selector of selectors) {
206
+ const element = document.querySelector(selector);
207
+ const text = textOf(element);
208
+ if (text !== '') {
209
+ const parsed = parseJSONText(text);
210
+ if (parsed !== undefined) {
211
+ return parsed;
212
+ }
213
+ }
214
+ }
215
+ return undefined;
216
+ }
217
+ /** Extract pages from a Next.js or Nuxt hydration payload. */
218
+ export function extractHydration(strategy, document, baseURL, windowObj) {
219
+ const payload = hydrationPayload(strategy, document, windowObj);
220
+ if (payload === undefined) {
221
+ return [];
222
+ }
223
+ let value = payload;
224
+ if (strategy.path) {
225
+ value = readPath(payload, strategy.path);
226
+ }
227
+ if (value === undefined || value === null) {
228
+ return [];
229
+ }
230
+ return toPages(value, baseURL);
231
+ }
232
+ /** Fetch a URL and apply the nested strategy to the response HTML. */
233
+ export async function extractAjax(strategy, document, environment, depth = 0) {
234
+ if (depth >= MAX_AJAX_DEPTH) {
235
+ return [];
236
+ }
237
+ const url = resolveURL(strategy.path, environment.baseURL);
238
+ const request = {
239
+ url,
240
+ method: strategy.method,
241
+ };
242
+ if (strategy.body !== undefined) {
243
+ request.body = strategy.body;
244
+ }
245
+ let response;
246
+ try {
247
+ response = await __http(request);
248
+ }
249
+ catch {
250
+ return [];
251
+ }
252
+ if (response.status < 200 || response.status >= 300) {
253
+ return [];
254
+ }
255
+ let parsed;
256
+ try {
257
+ parsed = environment.parseHTML ? environment.parseHTML(response.body) : __parseHTML(response.body);
258
+ }
259
+ catch {
260
+ return [];
261
+ }
262
+ return runStrategy(strategy.then, parsed, environment, depth + 1);
263
+ }
264
+ /** Run one strategy. A strategy returns `[]` when it does not match. */
265
+ export async function runStrategy(strategy, document, environment, depth = 0) {
266
+ if (!strategy || typeof strategy !== 'object') {
267
+ return [];
268
+ }
269
+ const kind = strategy.kind;
270
+ switch (kind) {
271
+ case 'css':
272
+ return extractCss(strategy, document, environment.baseURL);
273
+ case 'scriptJSON':
274
+ return extractScriptJSON(strategy, document, environment.baseURL, environment.parseHTML);
275
+ case 'hydration':
276
+ return extractHydration(strategy, document, environment.baseURL, environment.window);
277
+ case 'ajax':
278
+ return extractAjax(strategy, document, environment, depth);
279
+ default:
280
+ return [];
281
+ }
282
+ }
package/package.json CHANGED
@@ -1,6 +1,39 @@
1
1
  {
2
2
  "name": "@blankgrimoire/runtime",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.0.0",
4
+ "description": "Declarative extraction runtime for BlankGrimoire theme adapters.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "dist/index.js",
8
+ "types": "dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js"
13
+ },
14
+ "./runtime.js": "./dist/runtime.js"
15
+ },
16
+ "files": [
17
+ "dist"
18
+ ],
19
+ "publishConfig": {
20
+ "access": "public"
21
+ },
22
+ "repository": {
23
+ "type": "git",
24
+ "url": "https://github.com/BlankGrimoire/BlankGrimoire-sdk",
25
+ "directory": "packages/runtime"
26
+ },
27
+ "dependencies": {
28
+ "@blankgrimoire/types": "1.0.0"
29
+ },
30
+ "devDependencies": {
31
+ "esbuild": "^0.24.0",
32
+ "jsdom": "^24.0.0"
33
+ },
34
+ "scripts": {
35
+ "build": "tsc -p tsconfig.json && esbuild src/index.ts --bundle --format=iife --outfile=dist/runtime.js --global-name=BlankGrimoireRuntime",
36
+ "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
37
+ "test": "vitest run --passWithNoTests"
38
+ }
6
39
  }