@kubohiroya/turbowarp-react-islands 0.2.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/LICENSE +373 -0
- package/README.ja.md +94 -0
- package/README.md +162 -0
- package/dist/extension-manifest.json +62 -0
- package/dist/island.d.ts +33 -0
- package/dist/island.js +78 -0
- package/dist/island.js.map +1 -0
- package/dist/turbowarp-react-islands.js +152 -0
- package/docs/architecture.ja.md +87 -0
- package/docs/architecture.md +47 -0
- package/docs/index.html +37 -0
- package/package.json +73 -0
- package/schemas/extension-manifest.schema.json +49 -0
- package/src/block-definitions.json +44 -0
- package/src/config.ts +12 -0
- package/src/extension-manifest.ts +149 -0
- package/src/extension.ts +93 -0
- package/src/globals.d.ts +25 -0
- package/src/index.ts +8 -0
- package/src/island.ts +113 -0
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
import type {Plugin} from 'vite';
|
|
2
|
+
|
|
3
|
+
export const EXTENSION_MANIFEST_FORMAT_VERSION = 1 as const;
|
|
4
|
+
|
|
5
|
+
export interface ExtensionManifestArgument {
|
|
6
|
+
id: string;
|
|
7
|
+
type: string;
|
|
8
|
+
menu?: string;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export interface ExtensionManifestBlock {
|
|
12
|
+
opcode: string;
|
|
13
|
+
blockType: string;
|
|
14
|
+
arguments: ExtensionManifestArgument[];
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export interface ExtensionManifestMenu {
|
|
18
|
+
id: string;
|
|
19
|
+
acceptReporters: boolean;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface ExtensionManifest {
|
|
23
|
+
formatVersion: typeof EXTENSION_MANIFEST_FORMAT_VERSION;
|
|
24
|
+
id: string;
|
|
25
|
+
blocks: ExtensionManifestBlock[];
|
|
26
|
+
menus: ExtensionManifestMenu[];
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export interface ExtensionManifestPluginOptions {
|
|
30
|
+
id: string;
|
|
31
|
+
definitions: unknown;
|
|
32
|
+
fileName?: string;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export function createExtensionManifest(id: string, definitions: unknown): ExtensionManifest {
|
|
36
|
+
if (!/^[a-z0-9]+$/.test(id)) {
|
|
37
|
+
throw new TypeError('Extension manifest ID must contain only lowercase letters and numbers.');
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const source = requireRecord(definitions, 'Block definitions');
|
|
41
|
+
const sourceBlocks = source.blocks;
|
|
42
|
+
if (!Array.isArray(sourceBlocks)) {
|
|
43
|
+
throw new TypeError('Block definitions must contain a blocks array.');
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const menus = normalizeMenus(source.menus);
|
|
47
|
+
const menuIds = new Set(menus.map((menu) => menu.id));
|
|
48
|
+
const seenOpcodes = new Set<string>();
|
|
49
|
+
const blocks = sourceBlocks.map((block, index) => {
|
|
50
|
+
const normalized = normalizeBlock(block, index, menuIds);
|
|
51
|
+
if (seenOpcodes.has(normalized.opcode)) {
|
|
52
|
+
throw new TypeError(`Duplicate block opcode: ${normalized.opcode}`);
|
|
53
|
+
}
|
|
54
|
+
seenOpcodes.add(normalized.opcode);
|
|
55
|
+
return normalized;
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
return {
|
|
59
|
+
formatVersion: EXTENSION_MANIFEST_FORMAT_VERSION,
|
|
60
|
+
id,
|
|
61
|
+
blocks: blocks.sort((left, right) => compareIds(left.opcode, right.opcode)),
|
|
62
|
+
menus
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export function serializeExtensionManifest(id: string, definitions: unknown): string {
|
|
67
|
+
return `${JSON.stringify(createExtensionManifest(id, definitions), null, 2)}\n`;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export function extensionManifestPlugin(options: ExtensionManifestPluginOptions): Plugin {
|
|
71
|
+
return {
|
|
72
|
+
name: 'extension-api-manifest',
|
|
73
|
+
apply: 'build',
|
|
74
|
+
enforce: 'post',
|
|
75
|
+
generateBundle() {
|
|
76
|
+
this.emitFile({
|
|
77
|
+
type: 'asset',
|
|
78
|
+
fileName: options.fileName ?? 'extension-manifest.json',
|
|
79
|
+
source: serializeExtensionManifest(options.id, options.definitions)
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function normalizeBlock(
|
|
86
|
+
value: unknown,
|
|
87
|
+
index: number,
|
|
88
|
+
menuIds: ReadonlySet<string>
|
|
89
|
+
): ExtensionManifestBlock {
|
|
90
|
+
const block = requireRecord(value, `Block at index ${index}`);
|
|
91
|
+
const opcode = requireNonEmptyString(block.opcode, `Block at index ${index} opcode`);
|
|
92
|
+
const blockType = requireNonEmptyString(block.blockType, `Block ${opcode} blockType`);
|
|
93
|
+
const sourceArguments = block.arguments ?? {};
|
|
94
|
+
const argumentRecord = requireRecord(sourceArguments, `Block ${opcode} arguments`);
|
|
95
|
+
const argumentsList = Object.entries(argumentRecord).map(([argumentId, argument]) => {
|
|
96
|
+
requireNonEmptyString(argumentId, `Block ${opcode} argument ID`);
|
|
97
|
+
const definition = requireRecord(argument, `Block ${opcode} argument ${argumentId}`);
|
|
98
|
+
const type = requireNonEmptyString(
|
|
99
|
+
definition.type,
|
|
100
|
+
`Block ${opcode} argument ${argumentId} type`
|
|
101
|
+
);
|
|
102
|
+
const menu = definition.menu;
|
|
103
|
+
if (menu !== undefined && (typeof menu !== 'string' || !menuIds.has(menu))) {
|
|
104
|
+
throw new TypeError(`Block ${opcode} argument ${argumentId} references unknown menu: ${menu}`);
|
|
105
|
+
}
|
|
106
|
+
return menu === undefined ? {id: argumentId, type} : {id: argumentId, type, menu};
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
return {
|
|
110
|
+
opcode,
|
|
111
|
+
blockType,
|
|
112
|
+
arguments: argumentsList.sort((left, right) => compareIds(left.id, right.id))
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function normalizeMenus(value: unknown): ExtensionManifestMenu[] {
|
|
117
|
+
const menuRecord = requireRecord(value ?? {}, 'Block definition menus');
|
|
118
|
+
return Object.entries(menuRecord)
|
|
119
|
+
.map(([id, menu]) => {
|
|
120
|
+
requireNonEmptyString(id, 'Menu ID');
|
|
121
|
+
const definition = requireRecord(menu, `Menu ${id}`);
|
|
122
|
+
const acceptReporters = definition.acceptReporters ?? false;
|
|
123
|
+
if (typeof acceptReporters !== 'boolean') {
|
|
124
|
+
throw new TypeError(`Menu ${id} acceptReporters must be a boolean.`);
|
|
125
|
+
}
|
|
126
|
+
return {id, acceptReporters};
|
|
127
|
+
})
|
|
128
|
+
.sort((left, right) => compareIds(left.id, right.id));
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
function requireRecord(value: unknown, label: string): Record<string, unknown> {
|
|
132
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
|
133
|
+
throw new TypeError(`${label} must be an object.`);
|
|
134
|
+
}
|
|
135
|
+
return value as Record<string, unknown>;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function requireNonEmptyString(value: unknown, label: string): string {
|
|
139
|
+
if (typeof value !== 'string' || value.length === 0) {
|
|
140
|
+
throw new TypeError(`${label} must be a non-empty string.`);
|
|
141
|
+
}
|
|
142
|
+
return value;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
function compareIds(left: string, right: string): number {
|
|
146
|
+
if (left < right) return -1;
|
|
147
|
+
if (left > right) return 1;
|
|
148
|
+
return 0;
|
|
149
|
+
}
|
package/src/extension.ts
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import {extensionConfig} from './config';
|
|
2
|
+
import definitions from './block-definitions.json';
|
|
3
|
+
import {
|
|
4
|
+
ComponentRegistry,
|
|
5
|
+
createReactIslandDescriptor,
|
|
6
|
+
parsePropsJson,
|
|
7
|
+
renderReactIslandHtml,
|
|
8
|
+
serializeReactIslandDescriptor
|
|
9
|
+
} from './island.js';
|
|
10
|
+
|
|
11
|
+
type BlockTypeName = 'COMMAND' | 'REPORTER';
|
|
12
|
+
type ArgumentTypeName = 'STRING';
|
|
13
|
+
|
|
14
|
+
interface DefinitionArgument {
|
|
15
|
+
type: ArgumentTypeName;
|
|
16
|
+
defaultValue: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
interface BlockDefinition {
|
|
20
|
+
opcode: string;
|
|
21
|
+
blockType: BlockTypeName;
|
|
22
|
+
text: string;
|
|
23
|
+
description: string;
|
|
24
|
+
arguments: Record<string, DefinitionArgument>;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const blockDefinitions = definitions.blocks as readonly BlockDefinition[];
|
|
28
|
+
|
|
29
|
+
export class TurboWarpHttpServerReactExtension implements TurboWarpExtension {
|
|
30
|
+
private readonly registry = new ComponentRegistry();
|
|
31
|
+
|
|
32
|
+
public getInfo(): Record<string, unknown> {
|
|
33
|
+
return {
|
|
34
|
+
id: extensionConfig.id,
|
|
35
|
+
name: Scratch.translate(definitions.extensionName),
|
|
36
|
+
docsURI: extensionConfig.docsURI,
|
|
37
|
+
blockIconURI: extensionConfig.blockIconURI,
|
|
38
|
+
blocks: blockDefinitions.map((block) => this.toScratchBlock(block))
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
public registerComponent(args: {COMPONENT: unknown; MODULE: unknown}): void {
|
|
43
|
+
this.registry.register(
|
|
44
|
+
Scratch.Cast.toString(args.COMPONENT),
|
|
45
|
+
Scratch.Cast.toString(args.MODULE)
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
public reactIsland(args: {COMPONENT: unknown; MOUNT_ID: unknown; PROPS_JSON: unknown}): string {
|
|
50
|
+
return serializeReactIslandDescriptor(this.createDescriptor(args));
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
public reactIslandHtml(args: {
|
|
54
|
+
COMPONENT: unknown;
|
|
55
|
+
MOUNT_ID: unknown;
|
|
56
|
+
PROPS_JSON: unknown;
|
|
57
|
+
}): string {
|
|
58
|
+
return renderReactIslandHtml(this.createDescriptor(args));
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
public componentRegistryJson(): string {
|
|
62
|
+
return JSON.stringify(this.registry.toJSON());
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
private toScratchBlock(block: BlockDefinition): Record<string, unknown> {
|
|
66
|
+
return {
|
|
67
|
+
opcode: block.opcode,
|
|
68
|
+
blockType: Scratch.BlockType[block.blockType],
|
|
69
|
+
text: Scratch.translate(block.text),
|
|
70
|
+
arguments: Object.fromEntries(
|
|
71
|
+
Object.entries(block.arguments).map(([name, argument]) => [
|
|
72
|
+
name,
|
|
73
|
+
{
|
|
74
|
+
type: Scratch.ArgumentType[argument.type],
|
|
75
|
+
defaultValue: argument.defaultValue
|
|
76
|
+
}
|
|
77
|
+
])
|
|
78
|
+
)
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
private createDescriptor(args: {
|
|
83
|
+
COMPONENT: unknown;
|
|
84
|
+
MOUNT_ID: unknown;
|
|
85
|
+
PROPS_JSON: unknown;
|
|
86
|
+
}) {
|
|
87
|
+
return createReactIslandDescriptor({
|
|
88
|
+
component: Scratch.Cast.toString(args.COMPONENT),
|
|
89
|
+
mountId: Scratch.Cast.toString(args.MOUNT_ID),
|
|
90
|
+
props: parsePropsJson(Scratch.Cast.toString(args.PROPS_JSON))
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
}
|
package/src/globals.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
interface TurboWarpExtension {
|
|
2
|
+
getInfo(): Record<string, unknown>;
|
|
3
|
+
}
|
|
4
|
+
|
|
5
|
+
interface ScratchTranslate {
|
|
6
|
+
(text: string): string;
|
|
7
|
+
(message: {default: string; description?: string}, placeholders?: Record<string, string | number>): string;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
interface ScratchApi {
|
|
11
|
+
extensions: {
|
|
12
|
+
unsandboxed: boolean;
|
|
13
|
+
register(extension: TurboWarpExtension): void;
|
|
14
|
+
};
|
|
15
|
+
BlockType: Record<'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT', string>;
|
|
16
|
+
ArgumentType: Record<'STRING' | 'NUMBER' | 'BOOLEAN', string>;
|
|
17
|
+
Cast: {
|
|
18
|
+
toString(value: unknown): string;
|
|
19
|
+
toNumber(value: unknown): number;
|
|
20
|
+
toBoolean(value: unknown): boolean;
|
|
21
|
+
};
|
|
22
|
+
translate: ScratchTranslate;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
declare const Scratch: ScratchApi;
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import {extensionConfig} from './config.js';
|
|
2
|
+
import {TurboWarpHttpServerReactExtension} from './extension.js';
|
|
3
|
+
|
|
4
|
+
if (extensionConfig.unsandboxed && !Scratch.extensions.unsandboxed) {
|
|
5
|
+
throw new Error(`${extensionConfig.name} must run unsandboxed.`);
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
Scratch.extensions.register(new TurboWarpHttpServerReactExtension());
|
package/src/island.ts
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
export type JsonPrimitive = string | number | boolean | null;
|
|
2
|
+
export type JsonValue = JsonPrimitive | JsonValue[] | {[key: string]: JsonValue};
|
|
3
|
+
export type JsonObject = {[key: string]: JsonValue};
|
|
4
|
+
|
|
5
|
+
export interface ReactComponentRegistration {
|
|
6
|
+
component: string;
|
|
7
|
+
module: string;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
export interface ReactIslandDescriptor {
|
|
11
|
+
kind: 'react-island';
|
|
12
|
+
version: 1;
|
|
13
|
+
component: string;
|
|
14
|
+
mountId: string;
|
|
15
|
+
props: JsonObject;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface ReactIslandInput {
|
|
19
|
+
component: string;
|
|
20
|
+
mountId: string;
|
|
21
|
+
props?: JsonObject;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export class ComponentRegistry {
|
|
25
|
+
private readonly components = new Map<string, ReactComponentRegistration>();
|
|
26
|
+
|
|
27
|
+
public register(component: string, module: string): ReactComponentRegistration {
|
|
28
|
+
const registration = {
|
|
29
|
+
component: validateComponentName(component),
|
|
30
|
+
module: validateModuleSpecifier(module)
|
|
31
|
+
};
|
|
32
|
+
this.components.set(registration.component, registration);
|
|
33
|
+
return registration;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
public list(): ReactComponentRegistration[] {
|
|
37
|
+
return [...this.components.values()].sort((left, right) =>
|
|
38
|
+
left.component.localeCompare(right.component)
|
|
39
|
+
);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
public toJSON(): ReactComponentRegistration[] {
|
|
43
|
+
return this.list();
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export function createReactIslandDescriptor(input: ReactIslandInput): ReactIslandDescriptor {
|
|
48
|
+
return {
|
|
49
|
+
kind: 'react-island',
|
|
50
|
+
version: 1,
|
|
51
|
+
component: validateComponentName(input.component),
|
|
52
|
+
mountId: validateMountId(input.mountId),
|
|
53
|
+
props: input.props ?? {}
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function parsePropsJson(value: string): JsonObject {
|
|
58
|
+
const trimmed = value.trim();
|
|
59
|
+
if (trimmed.length === 0) return {};
|
|
60
|
+
|
|
61
|
+
const parsed = JSON.parse(trimmed) as unknown;
|
|
62
|
+
if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
|
|
63
|
+
throw new TypeError('React island props must be a JSON object.');
|
|
64
|
+
}
|
|
65
|
+
return parsed as JsonObject;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export function serializeReactIslandDescriptor(descriptor: ReactIslandDescriptor): string {
|
|
69
|
+
return JSON.stringify(descriptor);
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export function renderReactIslandHtml(descriptor: ReactIslandDescriptor): string {
|
|
73
|
+
const propsJson = JSON.stringify(descriptor.props).replace(/</g, '\\u003c');
|
|
74
|
+
return [
|
|
75
|
+
`<div id="${escapeHtmlAttribute(descriptor.mountId)}" data-tw-react-island="${escapeHtmlAttribute(
|
|
76
|
+
descriptor.component
|
|
77
|
+
)}">`,
|
|
78
|
+
`<script type="application/json" data-tw-react-props>${propsJson}</script>`,
|
|
79
|
+
'</div>'
|
|
80
|
+
].join('');
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
function validateComponentName(value: string): string {
|
|
84
|
+
const component = value.trim();
|
|
85
|
+
if (!/^[A-Z][A-Za-z0-9]*(?:[.:/-][A-Z]?[A-Za-z0-9]+)*$/.test(component)) {
|
|
86
|
+
throw new TypeError(`Invalid React component name: ${value}`);
|
|
87
|
+
}
|
|
88
|
+
return component;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function validateMountId(value: string): string {
|
|
92
|
+
const mountId = value.trim();
|
|
93
|
+
if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(mountId)) {
|
|
94
|
+
throw new TypeError(`Invalid React island mount ID: ${value}`);
|
|
95
|
+
}
|
|
96
|
+
return mountId;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function validateModuleSpecifier(value: string): string {
|
|
100
|
+
const module = value.trim();
|
|
101
|
+
if (module.length === 0) {
|
|
102
|
+
throw new TypeError('React component module must be non-empty.');
|
|
103
|
+
}
|
|
104
|
+
return module;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function escapeHtmlAttribute(value: string): string {
|
|
108
|
+
return value
|
|
109
|
+
.replace(/&/g, '&')
|
|
110
|
+
.replace(/"/g, '"')
|
|
111
|
+
.replace(/</g, '<')
|
|
112
|
+
.replace(/>/g, '>');
|
|
113
|
+
}
|