@kubohiroya/sb3-toolchain 0.15.1 → 0.17.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/CHANGELOG.md +14 -0
- package/README.ja.md +2 -2
- package/README.md +4 -2
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +25 -3
- package/dist/cli.js.map +1 -1
- package/dist/constants.d.ts +1 -1
- package/dist/constants.js +1 -1
- package/dist/constants.js.map +1 -1
- package/dist/extension-bundle-configuration.d.ts +7 -2
- package/dist/extension-bundle-configuration.js +17 -7
- package/dist/extension-bundle-configuration.js.map +1 -1
- package/dist/extension-bundle.d.ts +18 -3
- package/dist/extension-bundle.js +107 -14
- package/dist/extension-bundle.js.map +1 -1
- package/dist/extension-dependencies.js +11 -0
- package/dist/extension-dependencies.js.map +1 -1
- package/dist/extension-module-bundle.d.ts +45 -0
- package/dist/extension-module-bundle.js +266 -0
- package/dist/extension-module-bundle.js.map +1 -0
- package/dist/extension-sync.js +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.js +2 -1
- package/dist/npm-extension-source.d.ts +2 -0
- package/dist/npm-extension-source.js +1 -1
- package/dist/npm-extension-source.js.map +1 -1
- package/dist/source.js +7 -4
- package/dist/source.js.map +1 -1
- package/dist/types.d.ts +10 -0
- package/docs/.nojekyll +0 -0
- package/docs/extension-bundles.md +124 -0
- package/docs/index.html +153 -0
- package/docs/ja/extension-bundles.md +133 -0
- package/docs/ja/source-format-v1.md +2 -0
- package/docs/source-format-v1.md +2 -0
- package/package.json +7 -4
package/dist/source.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"source.js","names":[],"sources":["../src/source.ts"],"sourcesContent":["// SPDX-License-Identifier: MPL-2.0\n\nimport {createHash} from 'node:crypto';\nimport {lstat, readdir, readFile} from 'node:fs/promises';\nimport path from 'node:path';\n\nimport {strToU8, zipSync} from 'fflate';\n\nimport {validateArchiveEntryName} from './archive';\nimport {assert, errorMessage} from './assert';\nimport {validateManagedExtensionApiManifest} from './extension-api-manifest';\nimport {buildExtensionBundles, validateExtensionBundleConfigurations} from './extension-bundle';\nimport type {ExtensionBundlePlan} from './extension-bundle';\nimport {\n validateExtensionSourceMetadata,\n validateManagedExtensionContents,\n} from './extension-dependencies';\nimport {applyProjectAssetAdditions} from './project-asset-additions';\nimport type {ProjectAssetAdditionsSummary} from './project-asset-additions';\nimport {cleanUpTurboWarpBlocks} from './turbowarp-clean-up';\nimport type {\n EmbeddedExtension,\n ExtensionBundleConfiguration,\n ProjectAssetReference,\n ProjectJson,\n Sb3SourceManifest,\n UnknownRecord,\n} from './types';\n\nexport const sourceFormatVersion = 1;\nexport const fixedZipTimestamp = new Date(1980, 0, 1, 0, 0, 0, 0);\n\nexport interface InspectedSb3Source {\n assetContents: Map<string, Uint8Array>;\n assetReferenceCount: number;\n extensions: EmbeddedExtension[];\n extensionApiManifestContents: Map<string, Uint8Array>;\n extensionBundles: ExtensionBundleConfiguration[];\n extensionContents: Map<string, Uint8Array>;\n project: ProjectJson;\n resolvedSourceDirectory: string;\n sourceManifest: Sb3SourceManifest;\n}\n\nexport interface BlockCleanUpSummary {\n movedCommentCount: number;\n movedScriptCount: number;\n scriptCount: number;\n targetCount: number;\n}\n\nexport interface DeterministicSb3Options {\n allowedAssetRoots?: string[];\n cleanUpBlocks?: boolean;\n projectAssetsPath?: string;\n}\n\nexport interface DeterministicSb3 {\n archive: Uint8Array;\n assetCount: number;\n assetReferenceCount: number;\n blockCleanUp: BlockCleanUpSummary | null;\n bundlePlans: ExtensionBundlePlan[];\n embeddedExtensionCount: number;\n entryCount: number;\n projectAssetAdditions: Readonly<ProjectAssetAdditionsSummary> | null;\n source: InspectedSb3Source;\n}\n\nfunction isObject(value: unknown): value is UnknownRecord {\n return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nasync function readJson(filePath: string, description: string): Promise<unknown> {\n try {\n return JSON.parse(await readFile(filePath, 'utf8'));\n } catch (error) {\n throw new Error(`${description} is not valid JSON: ${filePath} (${errorMessage(error)})`, {\n cause: error,\n });\n }\n}\n\nasync function assertDirectory(directoryPath: string, description: string): Promise<void> {\n const stats = await lstat(directoryPath);\n assert(\n stats.isDirectory() && !stats.isSymbolicLink(),\n `${description} must be a directory, not a file or symbolic link: ${directoryPath}`,\n );\n}\n\nasync function listRegularFiles(rootDirectory: string, description: string): Promise<string[]> {\n await assertDirectory(rootDirectory, description);\n const files: string[] = [];\n\n async function visit(directory: string, relativeDirectory: string): Promise<void> {\n const entries = await readdir(directory, {withFileTypes: true});\n entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));\n for (const entry of entries) {\n const relativePath = relativeDirectory\n ? path.posix.join(relativeDirectory, entry.name)\n : entry.name;\n const absolutePath = path.join(directory, entry.name);\n if (entry.isDirectory()) {\n await visit(absolutePath, relativePath);\n } else {\n assert(\n entry.isFile(),\n `${description} contains a symbolic link or unsupported entry: ${relativePath}`,\n );\n files.push(relativePath);\n }\n }\n }\n\n await visit(rootDirectory, '');\n return files;\n}\n\nfunction assertSameFileSet(\n actualFiles: string[],\n expectedFiles: string[],\n description: string,\n): void {\n const actual = new Set(actualFiles);\n const expected = new Set(expectedFiles);\n const missing = [...expected].filter((filePath) => !actual.has(filePath)).sort();\n const extra = [...actual].filter((filePath) => !expected.has(filePath)).sort();\n assert(\n missing.length === 0 && extra.length === 0,\n `${description} does not match its manifest. Missing: ${missing.join(', ') || '(none)'}. ` +\n `Extra: ${extra.join(', ') || '(none)'}.`,\n );\n}\n\nfunction md5(contents: Uint8Array | string): string {\n return createHash('md5').update(contents).digest('hex');\n}\n\nfunction validateSourceManifest(manifest: unknown): asserts manifest is Sb3SourceManifest {\n assert(isObject(manifest), 'sb3-source.json must contain an object.');\n assert(\n manifest.formatVersion === sourceFormatVersion,\n `Unsupported SB3 source format version: ${manifest.formatVersion}`,\n );\n assert(\n manifest.project === 'project.source.json',\n 'SB3 source format 1 requires project.source.json.',\n );\n assert(\n manifest.embeddedExtensions === 'embedded-extensions.json',\n 'SB3 source format 1 requires embedded-extensions.json.',\n );\n assert(\n manifest.assetsDirectory === 'assets',\n 'SB3 source format 1 requires the assets directory.',\n );\n assert(\n Array.isArray(manifest.archiveEntries) && manifest.archiveEntries.length > 0,\n 'sb3-source.json archiveEntries must be a non-empty array.',\n );\n\n const seenEntries = new Set<string>();\n let projectEntryCount = 0;\n for (const rawEntryName of manifest.archiveEntries as unknown[]) {\n const entryName = validateArchiveEntryName(rawEntryName);\n assert(!seenEntries.has(entryName), `Duplicate archive entry in manifest: ${entryName}`);\n assert(\n !entryName.endsWith('/'),\n `Directory ZIP entries are not supported in SB3 source format 1: ${entryName}`,\n );\n assert(\n !/^(?:0|[1-9][0-9]*)$/u.test(entryName),\n `Integer-like ZIP entry names cannot preserve JavaScript object order: ${entryName}`,\n );\n seenEntries.add(entryName);\n if (entryName === 'project.json') {\n projectEntryCount += 1;\n }\n }\n assert(projectEntryCount === 1, 'archiveEntries must contain project.json exactly once.');\n}\n\nfunction validateExtensionManifest(\n extensionManifest: unknown,\n project: ProjectJson,\n extensionFiles: string[],\n): {extensionBundles: ExtensionBundleConfiguration[]; extensions: EmbeddedExtension[]} {\n assert(isObject(extensionManifest), 'embedded-extensions.json must contain an object.');\n assert(\n extensionManifest.formatVersion === sourceFormatVersion,\n `Unsupported embedded extension manifest version: ${extensionManifest.formatVersion}`,\n );\n assert(\n Array.isArray(extensionManifest.extensions),\n 'embedded-extensions.json extensions must be an array.',\n );\n\n const extensionUrls: unknown = project.extensionURLs ?? {};\n assert(\n isObject(extensionUrls),\n 'project.source.json extensionURLs must be an object when present.',\n );\n const extensionsById = new Map<string, EmbeddedExtension>();\n const expectedFiles: string[] = [];\n const extensions: EmbeddedExtension[] = [];\n\n for (const entry of extensionManifest.extensions as unknown[]) {\n assert(isObject(entry), 'Each embedded extension manifest entry must be an object.');\n const extension = entry as unknown as EmbeddedExtension;\n assert(\n typeof extension.id === 'string' && /^[A-Za-z0-9._-]+$/u.test(extension.id),\n `Invalid embedded extension ID: ${JSON.stringify(extension.id)}`,\n );\n assert(!extensionsById.has(extension.id), `Duplicate embedded extension ID: ${extension.id}`);\n const expectedPath = `extensions/${extension.id}.js`;\n assert(\n extension.path === expectedPath,\n `Embedded extension path must match its ID: expected ${expectedPath}, got ${extension.path}`,\n );\n assert(\n typeof extension.mediaType === 'string' &&\n extension.mediaType.length > 0 &&\n !/[;,\\r\\n]/u.test(extension.mediaType),\n `Invalid media type for embedded extension ${extension.id}: ${extension.mediaType}`,\n );\n assert(\n Array.isArray(extension.parameters) &&\n extension.parameters.every(\n (parameter) =>\n typeof parameter === 'string' && parameter.length > 0 && !/[;,\\r\\n]/u.test(parameter),\n ),\n `Invalid data URL parameters for embedded extension ${extension.id}.`,\n );\n assert(\n extension.encoding === 'base64' || extension.encoding === 'percent',\n `Unsupported encoding for embedded extension ${extension.id}: ${extension.encoding}`,\n );\n assert(\n extensionUrls[extension.id] === `embedded-extension:${extension.path}`,\n `project.source.json mapping does not match embedded extension ${extension.id}.`,\n );\n validateExtensionSourceMetadata(extension);\n extensionsById.set(extension.id, extension);\n extensions.push(extension);\n expectedFiles.push(`${extension.id}.js`);\n if (extension.source?.apiManifest) {\n expectedFiles.push(path.posix.relative('extensions', extension.source.apiManifest.path));\n }\n }\n\n for (const [extensionId, extensionUrl] of Object.entries(extensionUrls)) {\n assert(\n typeof extensionUrl !== 'string' || !extensionUrl.startsWith('data:'),\n `project.source.json still contains an embedded data URL: ${extensionId}`,\n );\n if (typeof extensionUrl === 'string' && extensionUrl.startsWith('embedded-extension:')) {\n assert(\n extensionsById.has(extensionId),\n `project.source.json has no metadata for embedded extension ${extensionId}.`,\n );\n }\n }\n\n assertSameFileSet(extensionFiles, expectedFiles, 'Embedded extension files');\n return {\n extensionBundles: validateExtensionBundleConfigurations(\n extensionManifest.extensionBundles,\n extensions,\n ),\n extensions,\n };\n}\n\nfunction collectAssetReferences(\n project: ProjectJson,\n): {asset: ProjectAssetReference; description: string}[] {\n assert(Array.isArray(project.targets), 'project.source.json targets must be an array.');\n const references: {asset: ProjectAssetReference; description: string}[] = [];\n for (const [targetIndex, target] of (project.targets as unknown[]).entries()) {\n assert(isObject(target), `Project target ${targetIndex} must be an object.`);\n for (const [collectionName, kind] of [\n ['costumes', 'costume'],\n ['sounds', 'sound'],\n ] as const) {\n const assets: unknown = target[collectionName] ?? [];\n assert(\n Array.isArray(assets),\n `Project target ${targetIndex} ${collectionName} must be an array.`,\n );\n for (const [assetIndex, asset] of (assets as unknown[]).entries()) {\n assert(isObject(asset), `Project ${kind} ${targetIndex}:${assetIndex} must be an object.`);\n references.push({asset, description: `${kind} ${targetIndex}:${assetIndex}`});\n }\n }\n }\n return references;\n}\n\nfunction percentEncode(contents: Uint8Array): string {\n return [...contents]\n .map((byte) => `%${byte.toString(16).padStart(2, '0').toUpperCase()}`)\n .join('');\n}\n\nfunction encodeExtensionDataUrl(extension: EmbeddedExtension, contents: Uint8Array): string {\n const metadata = [extension.mediaType, ...extension.parameters].join(';');\n if (extension.encoding === 'base64') {\n return `data:${metadata};base64,${Buffer.from(contents).toString('base64')}`;\n }\n return `data:${metadata},${percentEncode(contents)}`;\n}\n\nasync function inspectSb3Source(\n sourceDirectory: string,\n validateManagedExtensions: boolean,\n): Promise<InspectedSb3Source> {\n const resolvedSourceDirectory = path.resolve(sourceDirectory);\n await assertDirectory(resolvedSourceDirectory, 'SB3 source');\n const sourceManifest = await readJson(\n path.join(resolvedSourceDirectory, 'sb3-source.json'),\n 'SB3 source manifest',\n );\n validateSourceManifest(sourceManifest);\n const assetEntries = sourceManifest.archiveEntries.filter(\n (entryName) => entryName !== 'project.json',\n );\n const project: unknown = await readJson(\n path.join(resolvedSourceDirectory, sourceManifest.project),\n 'SB3 project source',\n );\n assert(isObject(project), 'project.source.json must contain an object.');\n const extensionManifest = await readJson(\n path.join(resolvedSourceDirectory, sourceManifest.embeddedExtensions),\n 'Embedded extension manifest',\n );\n\n const assetsDirectory = path.join(resolvedSourceDirectory, sourceManifest.assetsDirectory);\n const extensionsDirectory = path.join(resolvedSourceDirectory, 'extensions');\n const [assetFiles, extensionFiles] = await Promise.all([\n listRegularFiles(assetsDirectory, 'Assets directory'),\n listRegularFiles(extensionsDirectory, 'Extensions directory'),\n ]);\n assertSameFileSet(assetFiles, assetEntries, 'Asset files');\n const {extensionBundles, extensions} = validateExtensionManifest(\n extensionManifest,\n project,\n extensionFiles,\n );\n\n const assetContents = new Map<string, Uint8Array>();\n await Promise.all(\n assetFiles.map(async (assetPath) => {\n assetContents.set(assetPath, await readFile(path.join(assetsDirectory, assetPath)));\n }),\n );\n const referencedAssets = new Set<string>();\n const references = collectAssetReferences(project);\n for (const {asset, description} of references) {\n assert(\n typeof asset.assetId === 'string' && /^[a-f0-9]{32}$/u.test(asset.assetId),\n `Invalid assetId for ${description}: ${asset.assetId}`,\n );\n assert(\n typeof asset.dataFormat === 'string' && /^[A-Za-z0-9]+$/u.test(asset.dataFormat),\n `Invalid dataFormat for ${description}: ${asset.dataFormat}`,\n );\n const expectedFilename = `${asset.assetId}.${asset.dataFormat}`;\n assert(\n asset.md5ext === expectedFilename,\n `Asset filename mismatch for ${description}: expected ${expectedFilename}, got ${asset.md5ext}`,\n );\n const contents = assetContents.get(expectedFilename);\n assert(contents, `Referenced asset is missing for ${description}: ${expectedFilename}`);\n const actualAssetId = md5(contents);\n assert(\n actualAssetId === asset.assetId,\n `Asset content hash mismatch for ${description}: expected ${asset.assetId}, got ${actualAssetId}`,\n );\n referencedAssets.add(expectedFilename);\n }\n const unreferencedAssets = assetFiles.filter((assetPath) => !referencedAssets.has(assetPath));\n assert(\n unreferencedAssets.length === 0,\n `Asset manifest contains unreferenced files: ${unreferencedAssets.join(', ')}`,\n );\n\n const extensionContents = new Map<string, Uint8Array>();\n const extensionApiManifestContents = new Map<string, Uint8Array>();\n await Promise.all(\n extensions.map(async (extension) => {\n const contents = await readFile(path.join(resolvedSourceDirectory, extension.path));\n if (validateManagedExtensions) {\n validateManagedExtensionContents(extension, contents);\n }\n extensionContents.set(extension.id, contents);\n if (extension.source?.apiManifest) {\n const apiManifestContents = await readFile(\n path.join(resolvedSourceDirectory, extension.source.apiManifest.path),\n );\n if (validateManagedExtensions) {\n validateManagedExtensionApiManifest(extension, apiManifestContents);\n }\n extensionApiManifestContents.set(extension.id, apiManifestContents);\n }\n }),\n );\n\n return {\n assetContents,\n assetReferenceCount: references.length,\n extensions,\n extensionApiManifestContents,\n extensionBundles,\n extensionContents,\n project,\n resolvedSourceDirectory,\n sourceManifest,\n };\n}\n\nexport async function inspectSb3SourceForExtensionSync(\n sourceDirectory: string,\n): Promise<InspectedSb3Source> {\n return inspectSb3Source(sourceDirectory, false);\n}\n\nexport async function validateSb3Source(sourceDirectory: string): Promise<InspectedSb3Source> {\n const source = await inspectSb3Source(sourceDirectory, true);\n buildExtensionBundles({\n extensionBundles: source.extensionBundles,\n extensionContents: source.extensionContents,\n extensions: source.extensions,\n project: source.project,\n });\n return source;\n}\n\nexport async function createDeterministicSb3(\n sourceDirectory: string,\n options: DeterministicSb3Options = {},\n): Promise<DeterministicSb3> {\n const {allowedAssetRoots = [], cleanUpBlocks = false, projectAssetsPath} = options;\n assert(typeof cleanUpBlocks === 'boolean', 'cleanUpBlocks must be a boolean.');\n assert(Array.isArray(allowedAssetRoots), 'allowedAssetRoots must be an array.');\n assert(\n projectAssetsPath === undefined || typeof projectAssetsPath === 'string',\n 'projectAssetsPath must be a string when provided.',\n );\n const source = await validateSb3Source(sourceDirectory);\n const projectAssets: {\n archiveEntries: string[];\n assetContents: Map<string, Uint8Array>;\n assetReferenceCount: number;\n project: ProjectJson;\n summary: Readonly<ProjectAssetAdditionsSummary> | null;\n } = projectAssetsPath\n ? await applyProjectAssetAdditions({\n allowedAssetRoots,\n assetContents: source.assetContents,\n archiveEntries: source.sourceManifest.archiveEntries,\n manifestPath: projectAssetsPath,\n project: source.project,\n })\n : {\n archiveEntries: source.sourceManifest.archiveEntries,\n assetContents: source.assetContents,\n assetReferenceCount: 0,\n project: source.project,\n summary: null,\n };\n const bundled = buildExtensionBundles({\n extensionBundles: source.extensionBundles,\n extensionContents: source.extensionContents,\n extensions: source.extensions,\n project: projectAssets.project,\n });\n let project = structuredClone(bundled.project);\n let blockCleanUp: BlockCleanUpSummary | null = null;\n if (cleanUpBlocks) {\n const cleaned = cleanUpTurboWarpBlocks(project);\n project = cleaned.project;\n blockCleanUp = {\n movedCommentCount: cleaned.movedCommentCount,\n movedScriptCount: cleaned.movedScriptCount,\n scriptCount: cleaned.scriptCount,\n targetCount: cleaned.targetCount,\n };\n }\n const extensionUrls: Record<string, unknown> = project.extensionURLs ?? {};\n for (const extension of bundled.extensions) {\n const contents = bundled.extensionContents.get(extension.id);\n assert(contents, `Embedded extension has no contents: ${extension.id}`);\n extensionUrls[extension.id] = encodeExtensionDataUrl(extension, contents);\n }\n project.extensionURLs = extensionUrls;\n\n const archiveEntries: Record<string, Uint8Array> = {};\n for (const entryName of projectAssets.archiveEntries) {\n if (entryName === 'project.json') {\n archiveEntries[entryName] = strToU8(`${JSON.stringify(project)}\\n`);\n continue;\n }\n const contents = projectAssets.assetContents.get(entryName);\n assert(contents, `Archive entry has no contents: ${entryName}`);\n archiveEntries[entryName] = contents;\n }\n const archive = zipSync(archiveEntries, {\n level: 6,\n mtime: fixedZipTimestamp,\n });\n\n return {\n archive,\n assetCount: projectAssets.assetContents.size,\n assetReferenceCount: source.assetReferenceCount + projectAssets.assetReferenceCount,\n blockCleanUp,\n bundlePlans: bundled.bundlePlans,\n embeddedExtensionCount: bundled.extensions.length,\n entryCount: projectAssets.archiveEntries.length,\n projectAssetAdditions: projectAssets.summary,\n source,\n };\n}\n"],"mappings":"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"}
|
|
1
|
+
{"version":3,"file":"source.js","names":[],"sources":["../src/source.ts"],"sourcesContent":["// SPDX-License-Identifier: MPL-2.0\n\nimport {createHash} from 'node:crypto';\nimport {lstat, readdir, readFile} from 'node:fs/promises';\nimport path from 'node:path';\n\nimport {strToU8, zipSync} from 'fflate';\n\nimport {validateArchiveEntryName} from './archive';\nimport {assert, errorMessage} from './assert';\nimport {validateManagedExtensionApiManifest} from './extension-api-manifest';\nimport {validateExtensionBundleConfigurations} from './extension-bundle';\nimport {buildExtensionBundlesWithModules} from './extension-module-bundle';\nimport type {ExtensionBundlePlan} from './extension-bundle';\nimport {\n validateExtensionSourceMetadata,\n validateManagedExtensionContents,\n} from './extension-dependencies';\nimport {applyProjectAssetAdditions} from './project-asset-additions';\nimport type {ProjectAssetAdditionsSummary} from './project-asset-additions';\nimport {cleanUpTurboWarpBlocks} from './turbowarp-clean-up';\nimport type {\n EmbeddedExtension,\n ExtensionBundleConfiguration,\n ProjectAssetReference,\n ProjectJson,\n Sb3SourceManifest,\n UnknownRecord,\n} from './types';\n\nexport const sourceFormatVersion = 1;\nexport const fixedZipTimestamp = new Date(1980, 0, 1, 0, 0, 0, 0);\n\nexport interface InspectedSb3Source {\n assetContents: Map<string, Uint8Array>;\n assetReferenceCount: number;\n extensions: EmbeddedExtension[];\n extensionApiManifestContents: Map<string, Uint8Array>;\n extensionBundles: ExtensionBundleConfiguration[];\n extensionContents: Map<string, Uint8Array>;\n project: ProjectJson;\n resolvedSourceDirectory: string;\n sourceManifest: Sb3SourceManifest;\n}\n\nexport interface BlockCleanUpSummary {\n movedCommentCount: number;\n movedScriptCount: number;\n scriptCount: number;\n targetCount: number;\n}\n\nexport interface DeterministicSb3Options {\n allowedAssetRoots?: string[];\n cleanUpBlocks?: boolean;\n projectAssetsPath?: string;\n}\n\nexport interface DeterministicSb3 {\n archive: Uint8Array;\n assetCount: number;\n assetReferenceCount: number;\n blockCleanUp: BlockCleanUpSummary | null;\n bundlePlans: ExtensionBundlePlan[];\n embeddedExtensionCount: number;\n entryCount: number;\n projectAssetAdditions: Readonly<ProjectAssetAdditionsSummary> | null;\n source: InspectedSb3Source;\n}\n\nfunction isObject(value: unknown): value is UnknownRecord {\n return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nasync function readJson(filePath: string, description: string): Promise<unknown> {\n try {\n return JSON.parse(await readFile(filePath, 'utf8'));\n } catch (error) {\n throw new Error(`${description} is not valid JSON: ${filePath} (${errorMessage(error)})`, {\n cause: error,\n });\n }\n}\n\nasync function assertDirectory(directoryPath: string, description: string): Promise<void> {\n const stats = await lstat(directoryPath);\n assert(\n stats.isDirectory() && !stats.isSymbolicLink(),\n `${description} must be a directory, not a file or symbolic link: ${directoryPath}`,\n );\n}\n\nasync function listRegularFiles(rootDirectory: string, description: string): Promise<string[]> {\n await assertDirectory(rootDirectory, description);\n const files: string[] = [];\n\n async function visit(directory: string, relativeDirectory: string): Promise<void> {\n const entries = await readdir(directory, {withFileTypes: true});\n entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));\n for (const entry of entries) {\n const relativePath = relativeDirectory\n ? path.posix.join(relativeDirectory, entry.name)\n : entry.name;\n const absolutePath = path.join(directory, entry.name);\n if (entry.isDirectory()) {\n await visit(absolutePath, relativePath);\n } else {\n assert(\n entry.isFile(),\n `${description} contains a symbolic link or unsupported entry: ${relativePath}`,\n );\n files.push(relativePath);\n }\n }\n }\n\n await visit(rootDirectory, '');\n return files;\n}\n\nfunction assertSameFileSet(\n actualFiles: string[],\n expectedFiles: string[],\n description: string,\n): void {\n const actual = new Set(actualFiles);\n const expected = new Set(expectedFiles);\n const missing = [...expected].filter((filePath) => !actual.has(filePath)).sort();\n const extra = [...actual].filter((filePath) => !expected.has(filePath)).sort();\n assert(\n missing.length === 0 && extra.length === 0,\n `${description} does not match its manifest. Missing: ${missing.join(', ') || '(none)'}. ` +\n `Extra: ${extra.join(', ') || '(none)'}.`,\n );\n}\n\nfunction md5(contents: Uint8Array | string): string {\n return createHash('md5').update(contents).digest('hex');\n}\n\nfunction validateSourceManifest(manifest: unknown): asserts manifest is Sb3SourceManifest {\n assert(isObject(manifest), 'sb3-source.json must contain an object.');\n assert(\n manifest.formatVersion === sourceFormatVersion,\n `Unsupported SB3 source format version: ${manifest.formatVersion}`,\n );\n assert(\n manifest.project === 'project.source.json',\n 'SB3 source format 1 requires project.source.json.',\n );\n assert(\n manifest.embeddedExtensions === 'embedded-extensions.json',\n 'SB3 source format 1 requires embedded-extensions.json.',\n );\n assert(\n manifest.assetsDirectory === 'assets',\n 'SB3 source format 1 requires the assets directory.',\n );\n assert(\n Array.isArray(manifest.archiveEntries) && manifest.archiveEntries.length > 0,\n 'sb3-source.json archiveEntries must be a non-empty array.',\n );\n\n const seenEntries = new Set<string>();\n let projectEntryCount = 0;\n for (const rawEntryName of manifest.archiveEntries as unknown[]) {\n const entryName = validateArchiveEntryName(rawEntryName);\n assert(!seenEntries.has(entryName), `Duplicate archive entry in manifest: ${entryName}`);\n assert(\n !entryName.endsWith('/'),\n `Directory ZIP entries are not supported in SB3 source format 1: ${entryName}`,\n );\n assert(\n !/^(?:0|[1-9][0-9]*)$/u.test(entryName),\n `Integer-like ZIP entry names cannot preserve JavaScript object order: ${entryName}`,\n );\n seenEntries.add(entryName);\n if (entryName === 'project.json') {\n projectEntryCount += 1;\n }\n }\n assert(projectEntryCount === 1, 'archiveEntries must contain project.json exactly once.');\n}\n\nfunction validateExtensionManifest(\n extensionManifest: unknown,\n project: ProjectJson,\n extensionFiles: string[],\n): {extensionBundles: ExtensionBundleConfiguration[]; extensions: EmbeddedExtension[]} {\n assert(isObject(extensionManifest), 'embedded-extensions.json must contain an object.');\n assert(\n extensionManifest.formatVersion === sourceFormatVersion,\n `Unsupported embedded extension manifest version: ${extensionManifest.formatVersion}`,\n );\n assert(\n Array.isArray(extensionManifest.extensions),\n 'embedded-extensions.json extensions must be an array.',\n );\n\n const extensionUrls: unknown = project.extensionURLs ?? {};\n assert(\n isObject(extensionUrls),\n 'project.source.json extensionURLs must be an object when present.',\n );\n const extensionsById = new Map<string, EmbeddedExtension>();\n const expectedFiles: string[] = [];\n const extensions: EmbeddedExtension[] = [];\n\n for (const entry of extensionManifest.extensions as unknown[]) {\n assert(isObject(entry), 'Each embedded extension manifest entry must be an object.');\n const extension = entry as unknown as EmbeddedExtension;\n assert(\n typeof extension.id === 'string' && /^[A-Za-z0-9._-]+$/u.test(extension.id),\n `Invalid embedded extension ID: ${JSON.stringify(extension.id)}`,\n );\n assert(!extensionsById.has(extension.id), `Duplicate embedded extension ID: ${extension.id}`);\n const expectedPath = `extensions/${extension.id}.js`;\n assert(\n extension.path === expectedPath,\n `Embedded extension path must match its ID: expected ${expectedPath}, got ${extension.path}`,\n );\n assert(\n typeof extension.mediaType === 'string' &&\n extension.mediaType.length > 0 &&\n !/[;,\\r\\n]/u.test(extension.mediaType),\n `Invalid media type for embedded extension ${extension.id}: ${extension.mediaType}`,\n );\n assert(\n Array.isArray(extension.parameters) &&\n extension.parameters.every(\n (parameter) =>\n typeof parameter === 'string' && parameter.length > 0 && !/[;,\\r\\n]/u.test(parameter),\n ),\n `Invalid data URL parameters for embedded extension ${extension.id}.`,\n );\n assert(\n extension.encoding === 'base64' || extension.encoding === 'percent',\n `Unsupported encoding for embedded extension ${extension.id}: ${extension.encoding}`,\n );\n assert(\n extensionUrls[extension.id] === `embedded-extension:${extension.path}`,\n `project.source.json mapping does not match embedded extension ${extension.id}.`,\n );\n validateExtensionSourceMetadata(extension);\n extensionsById.set(extension.id, extension);\n extensions.push(extension);\n expectedFiles.push(`${extension.id}.js`);\n if (extension.source?.apiManifest) {\n expectedFiles.push(path.posix.relative('extensions', extension.source.apiManifest.path));\n }\n }\n\n for (const [extensionId, extensionUrl] of Object.entries(extensionUrls)) {\n assert(\n typeof extensionUrl !== 'string' || !extensionUrl.startsWith('data:'),\n `project.source.json still contains an embedded data URL: ${extensionId}`,\n );\n if (typeof extensionUrl === 'string' && extensionUrl.startsWith('embedded-extension:')) {\n assert(\n extensionsById.has(extensionId),\n `project.source.json has no metadata for embedded extension ${extensionId}.`,\n );\n }\n }\n\n assertSameFileSet(extensionFiles, expectedFiles, 'Embedded extension files');\n return {\n extensionBundles: validateExtensionBundleConfigurations(\n extensionManifest.extensionBundles,\n extensions,\n ),\n extensions,\n };\n}\n\nfunction collectAssetReferences(\n project: ProjectJson,\n): {asset: ProjectAssetReference; description: string}[] {\n assert(Array.isArray(project.targets), 'project.source.json targets must be an array.');\n const references: {asset: ProjectAssetReference; description: string}[] = [];\n for (const [targetIndex, target] of (project.targets as unknown[]).entries()) {\n assert(isObject(target), `Project target ${targetIndex} must be an object.`);\n for (const [collectionName, kind] of [\n ['costumes', 'costume'],\n ['sounds', 'sound'],\n ] as const) {\n const assets: unknown = target[collectionName] ?? [];\n assert(\n Array.isArray(assets),\n `Project target ${targetIndex} ${collectionName} must be an array.`,\n );\n for (const [assetIndex, asset] of (assets as unknown[]).entries()) {\n assert(isObject(asset), `Project ${kind} ${targetIndex}:${assetIndex} must be an object.`);\n references.push({asset, description: `${kind} ${targetIndex}:${assetIndex}`});\n }\n }\n }\n return references;\n}\n\nfunction percentEncode(contents: Uint8Array): string {\n return [...contents]\n .map((byte) => `%${byte.toString(16).padStart(2, '0').toUpperCase()}`)\n .join('');\n}\n\nfunction encodeExtensionDataUrl(extension: EmbeddedExtension, contents: Uint8Array): string {\n const metadata = [extension.mediaType, ...extension.parameters].join(';');\n if (extension.encoding === 'base64') {\n return `data:${metadata};base64,${Buffer.from(contents).toString('base64')}`;\n }\n return `data:${metadata},${percentEncode(contents)}`;\n}\n\nasync function inspectSb3Source(\n sourceDirectory: string,\n validateManagedExtensions: boolean,\n): Promise<InspectedSb3Source> {\n const resolvedSourceDirectory = path.resolve(sourceDirectory);\n await assertDirectory(resolvedSourceDirectory, 'SB3 source');\n const sourceManifest = await readJson(\n path.join(resolvedSourceDirectory, 'sb3-source.json'),\n 'SB3 source manifest',\n );\n validateSourceManifest(sourceManifest);\n const assetEntries = sourceManifest.archiveEntries.filter(\n (entryName) => entryName !== 'project.json',\n );\n const project: unknown = await readJson(\n path.join(resolvedSourceDirectory, sourceManifest.project),\n 'SB3 project source',\n );\n assert(isObject(project), 'project.source.json must contain an object.');\n const extensionManifest = await readJson(\n path.join(resolvedSourceDirectory, sourceManifest.embeddedExtensions),\n 'Embedded extension manifest',\n );\n\n const assetsDirectory = path.join(resolvedSourceDirectory, sourceManifest.assetsDirectory);\n const extensionsDirectory = path.join(resolvedSourceDirectory, 'extensions');\n const [assetFiles, extensionFiles] = await Promise.all([\n listRegularFiles(assetsDirectory, 'Assets directory'),\n listRegularFiles(extensionsDirectory, 'Extensions directory'),\n ]);\n assertSameFileSet(assetFiles, assetEntries, 'Asset files');\n const {extensionBundles, extensions} = validateExtensionManifest(\n extensionManifest,\n project,\n extensionFiles,\n );\n\n const assetContents = new Map<string, Uint8Array>();\n await Promise.all(\n assetFiles.map(async (assetPath) => {\n assetContents.set(assetPath, await readFile(path.join(assetsDirectory, assetPath)));\n }),\n );\n const referencedAssets = new Set<string>();\n const references = collectAssetReferences(project);\n for (const {asset, description} of references) {\n assert(\n typeof asset.assetId === 'string' && /^[a-f0-9]{32}$/u.test(asset.assetId),\n `Invalid assetId for ${description}: ${asset.assetId}`,\n );\n assert(\n typeof asset.dataFormat === 'string' && /^[A-Za-z0-9]+$/u.test(asset.dataFormat),\n `Invalid dataFormat for ${description}: ${asset.dataFormat}`,\n );\n const expectedFilename = `${asset.assetId}.${asset.dataFormat}`;\n assert(\n asset.md5ext === expectedFilename,\n `Asset filename mismatch for ${description}: expected ${expectedFilename}, got ${asset.md5ext}`,\n );\n const contents = assetContents.get(expectedFilename);\n assert(contents, `Referenced asset is missing for ${description}: ${expectedFilename}`);\n const actualAssetId = md5(contents);\n assert(\n actualAssetId === asset.assetId,\n `Asset content hash mismatch for ${description}: expected ${asset.assetId}, got ${actualAssetId}`,\n );\n referencedAssets.add(expectedFilename);\n }\n const unreferencedAssets = assetFiles.filter((assetPath) => !referencedAssets.has(assetPath));\n assert(\n unreferencedAssets.length === 0,\n `Asset manifest contains unreferenced files: ${unreferencedAssets.join(', ')}`,\n );\n\n const extensionContents = new Map<string, Uint8Array>();\n const extensionApiManifestContents = new Map<string, Uint8Array>();\n await Promise.all(\n extensions.map(async (extension) => {\n const contents = await readFile(path.join(resolvedSourceDirectory, extension.path));\n if (validateManagedExtensions) {\n validateManagedExtensionContents(extension, contents);\n }\n extensionContents.set(extension.id, contents);\n if (extension.source?.apiManifest) {\n const apiManifestContents = await readFile(\n path.join(resolvedSourceDirectory, extension.source.apiManifest.path),\n );\n if (validateManagedExtensions) {\n validateManagedExtensionApiManifest(extension, apiManifestContents);\n }\n extensionApiManifestContents.set(extension.id, apiManifestContents);\n }\n }),\n );\n\n return {\n assetContents,\n assetReferenceCount: references.length,\n extensions,\n extensionApiManifestContents,\n extensionBundles,\n extensionContents,\n project,\n resolvedSourceDirectory,\n sourceManifest,\n };\n}\n\nexport async function inspectSb3SourceForExtensionSync(\n sourceDirectory: string,\n): Promise<InspectedSb3Source> {\n return inspectSb3Source(sourceDirectory, false);\n}\n\nexport async function validateSb3Source(sourceDirectory: string): Promise<InspectedSb3Source> {\n const source = await inspectSb3Source(sourceDirectory, true);\n await buildExtensionBundlesWithModules({\n sourceDirectory: source.resolvedSourceDirectory,\n extensionBundles: source.extensionBundles,\n extensionContents: source.extensionContents,\n extensions: source.extensions,\n project: source.project,\n });\n return source;\n}\n\nexport async function createDeterministicSb3(\n sourceDirectory: string,\n options: DeterministicSb3Options = {},\n): Promise<DeterministicSb3> {\n const {allowedAssetRoots = [], cleanUpBlocks = false, projectAssetsPath} = options;\n assert(typeof cleanUpBlocks === 'boolean', 'cleanUpBlocks must be a boolean.');\n assert(Array.isArray(allowedAssetRoots), 'allowedAssetRoots must be an array.');\n assert(\n projectAssetsPath === undefined || typeof projectAssetsPath === 'string',\n 'projectAssetsPath must be a string when provided.',\n );\n const source = await inspectSb3Source(sourceDirectory, true);\n const projectAssets: {\n archiveEntries: string[];\n assetContents: Map<string, Uint8Array>;\n assetReferenceCount: number;\n project: ProjectJson;\n summary: Readonly<ProjectAssetAdditionsSummary> | null;\n } = projectAssetsPath\n ? await applyProjectAssetAdditions({\n allowedAssetRoots,\n assetContents: source.assetContents,\n archiveEntries: source.sourceManifest.archiveEntries,\n manifestPath: projectAssetsPath,\n project: source.project,\n })\n : {\n archiveEntries: source.sourceManifest.archiveEntries,\n assetContents: source.assetContents,\n assetReferenceCount: 0,\n project: source.project,\n summary: null,\n };\n const bundled = await buildExtensionBundlesWithModules({\n sourceDirectory: source.resolvedSourceDirectory,\n extensionBundles: source.extensionBundles,\n extensionContents: source.extensionContents,\n extensions: source.extensions,\n project: projectAssets.project,\n });\n let project = structuredClone(bundled.project);\n let blockCleanUp: BlockCleanUpSummary | null = null;\n if (cleanUpBlocks) {\n const cleaned = cleanUpTurboWarpBlocks(project);\n project = cleaned.project;\n blockCleanUp = {\n movedCommentCount: cleaned.movedCommentCount,\n movedScriptCount: cleaned.movedScriptCount,\n scriptCount: cleaned.scriptCount,\n targetCount: cleaned.targetCount,\n };\n }\n const extensionUrls: Record<string, unknown> = project.extensionURLs ?? {};\n for (const extension of bundled.extensions) {\n const contents = bundled.extensionContents.get(extension.id);\n assert(contents, `Embedded extension has no contents: ${extension.id}`);\n extensionUrls[extension.id] = encodeExtensionDataUrl(extension, contents);\n }\n project.extensionURLs = extensionUrls;\n\n const archiveEntries: Record<string, Uint8Array> = {};\n for (const entryName of projectAssets.archiveEntries) {\n if (entryName === 'project.json') {\n archiveEntries[entryName] = strToU8(`${JSON.stringify(project)}\\n`);\n continue;\n }\n const contents = projectAssets.assetContents.get(entryName);\n assert(contents, `Archive entry has no contents: ${entryName}`);\n archiveEntries[entryName] = contents;\n }\n const archive = zipSync(archiveEntries, {\n level: 6,\n mtime: fixedZipTimestamp,\n });\n\n return {\n archive,\n assetCount: projectAssets.assetContents.size,\n assetReferenceCount: source.assetReferenceCount + projectAssets.assetReferenceCount,\n blockCleanUp,\n bundlePlans: bundled.bundlePlans,\n embeddedExtensionCount: bundled.extensions.length,\n entryCount: projectAssets.archiveEntries.length,\n projectAssetAdditions: projectAssets.summary,\n source,\n };\n}\n"],"mappings":"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"}
|
package/dist/types.d.ts
CHANGED
|
@@ -21,6 +21,13 @@ export interface NpmExtensionSource {
|
|
|
21
21
|
artifact: string;
|
|
22
22
|
integrity: string;
|
|
23
23
|
apiManifest?: ExtensionApiManifestSource;
|
|
24
|
+
module?: ExtensionModuleSource;
|
|
25
|
+
}
|
|
26
|
+
export interface ExtensionModuleSource {
|
|
27
|
+
artifact: string;
|
|
28
|
+
formatVersion: 1;
|
|
29
|
+
integrity: string;
|
|
30
|
+
unsandboxed: 'required' | 'optional' | 'not-needed';
|
|
24
31
|
}
|
|
25
32
|
export type ExtensionSource = GitHubExtensionSource | NpmExtensionSource;
|
|
26
33
|
export type ExtensionEncoding = 'base64' | 'percent';
|
|
@@ -38,6 +45,9 @@ export interface ExtensionBundleConfiguration {
|
|
|
38
45
|
members: string[];
|
|
39
46
|
recoveryCapsule?: boolean;
|
|
40
47
|
sandboxedNotice?: Record<string, string>;
|
|
48
|
+
blockEditorRegistrations?: boolean;
|
|
49
|
+
buildMode?: 'classic' | 'module';
|
|
50
|
+
sharedDependencies?: Record<string, string>;
|
|
41
51
|
}
|
|
42
52
|
export interface EmbeddedExtensionManifest {
|
|
43
53
|
formatVersion: number;
|
package/docs/.nojekyll
ADDED
|
File without changes
|
|
@@ -9,6 +9,111 @@ one extension.
|
|
|
9
9
|
|
|
10
10
|
## Overview
|
|
11
11
|
|
|
12
|
+
The default `classic` mode wraps completed scripts. To share their dependencies too, opt in to the
|
|
13
|
+
module build described below. The remaining classic runtime and recovery documentation also applies
|
|
14
|
+
to module bundles unless noted.
|
|
15
|
+
|
|
16
|
+
## Module builds (off by default)
|
|
17
|
+
|
|
18
|
+
Every member must provide an installed npm JavaScript entry exporting `createExtension(scratch)` and
|
|
19
|
+
`bundleModuleMetadata` (`formatVersion: 1`, `id`, `unsandboxed`). Importing it must not activate an
|
|
20
|
+
extension, register one, or connect listeners. The factory synchronously returns a fresh instance
|
|
21
|
+
using the supplied member Scratch proxy. The composite calls each factory once and registers once.
|
|
22
|
+
|
|
23
|
+
Add a `module` declaration to each member's existing npm `source`. Replace the digest placeholders
|
|
24
|
+
with the SHA-256 of the respective files:
|
|
25
|
+
|
|
26
|
+
```json
|
|
27
|
+
{
|
|
28
|
+
"provider": "npm",
|
|
29
|
+
"package": "@example/extension-one",
|
|
30
|
+
"version": "1.0.0",
|
|
31
|
+
"artifact": "dist/extension-one.js",
|
|
32
|
+
"integrity": "sha256-<base64 classic digest>",
|
|
33
|
+
"module": {
|
|
34
|
+
"artifact": "lib-module/src/bundle-module.js",
|
|
35
|
+
"formatVersion": 1,
|
|
36
|
+
"integrity": "sha256-<base64 module digest>",
|
|
37
|
+
"unsandboxed": "required"
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Select the build and exact shared versions on the bundle:
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"id": "projectbundle",
|
|
47
|
+
"name": "Project Extension Bundle",
|
|
48
|
+
"members": ["extensionone", "extensiontwo"],
|
|
49
|
+
"buildMode": "module",
|
|
50
|
+
"sharedDependencies": {"yaml": "2.9.1"},
|
|
51
|
+
"blockEditorRegistrations": true
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Install the pinned owner packages and shared dependencies in the project's `node_modules` first,
|
|
56
|
+
retaining either `pnpm-lock.yaml` or `package-lock.json`. Parent directories of the expanded source
|
|
57
|
+
are searched. The toolchain's own yaml is not a shared input. Builds do not install packages, clone
|
|
58
|
+
repositories, execute owner code, or load project build configurations or plugins. The initial module
|
|
59
|
+
scope is installed npm artifacts; GitHub sources continue to use classic mode.
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
sb3-toolchain extensions bundle app --id projectbundle --name "Project Extension Bundle" \
|
|
63
|
+
extensionone extensiontwo --build-mode module --share yaml@2.9.1
|
|
64
|
+
# Review the plan, then repeat with --yes to save it.
|
|
65
|
+
sb3-toolchain build app --output dist/project.sb3
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`bundleExtensions` and `planExtensionBundle` also accept `buildMode` and `sharedDependencies`.
|
|
69
|
+
Repeat `--share` for additional packages. GUI editor adaptation remains an explicit manifest option.
|
|
70
|
+
|
|
71
|
+
The resolver checks the selected version against each importer's declared range and uses one real
|
|
72
|
+
package under browser conditions. yaml must use its browser entry; duplicate copies or mixed Node
|
|
73
|
+
and browser graphs fail. Missing entries, mismatched package versions, classic artifacts, module
|
|
74
|
+
digests, and unsupported contracts also fail. A required sandbox guard runs before any library
|
|
75
|
+
evaluation or factory activation; without permission only the existing notice extension registers.
|
|
76
|
+
All member metadata is checked before any factory activates. If a later factory fails, prior
|
|
77
|
+
instances are disposed. The composite's `dispose()` cleans up each member once.
|
|
78
|
+
|
|
79
|
+
The `moduleBuild` report on bundle plans and `createDeterministicSb3(...).bundlePlans[]` records the
|
|
80
|
+
bundler version, browser / ES2020 settings, lock digest, member entries, loaded files and package
|
|
81
|
+
manifest digests, and shared package copy counts. `Module build inputs` in the generated JS hashes
|
|
82
|
+
this record; absolute paths are omitted. The lock is hashed as an input alongside the actual installed
|
|
83
|
+
files, so install from the lock when reproducing a build. When updating an owner, update both classic
|
|
84
|
+
and module integrity pins. A stale module pin rejects the candidate while retaining the source.
|
|
85
|
+
|
|
86
|
+
Library code and module evaluation are shared per bundle load. Parser, Composer, Document, and other
|
|
87
|
+
parse state remain independent for each input. Other bundles and separate GUI graphs are outside
|
|
88
|
+
this scope. Existing owner feature flags, IDs, opcodes, and parse options stay intact.
|
|
89
|
+
|
|
90
|
+
### Verification and rollback
|
|
91
|
+
|
|
92
|
+
Regular tests deliberately install private copies of the same yaml version under multiple members.
|
|
93
|
+
To verify the actual unpublished owner entries, build their clean checkouts first, then run:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
node scripts/prepare-module-owner-fixture.mjs /tmp/new-module-owners \
|
|
97
|
+
/path/to/turbowarp-structured-data /path/to/turbowarp-yaml-json /path/to/turbowarp-3d-scene-runtime
|
|
98
|
+
SB3_MODULE_OWNER_FIXTURE=/tmp/new-module-owners/app pnpm exec vitest run test/extension-module-owners.test.ts
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The preparation script packs local artifacts and installs production dependencies with lifecycle
|
|
102
|
+
scripts disabled. The owner test runs only with the environment variable; ordinary CI skips it.
|
|
103
|
+
It writes `module-owner-results.json` (including owner commits and input digests), `shared-yaml.js`,
|
|
104
|
+
and `shared-yaml.sb3` beside `app`. Evaluation and factory counters are injected only into the test
|
|
105
|
+
build; size and reproducibility measurements use uninstrumented output. Tests also cover parsing,
|
|
106
|
+
runtime Schema validation, editor registration and cleanup, sandbox handling, and recovery.
|
|
107
|
+
|
|
108
|
+
To roll back, omit `buildMode` or set it to `classic`, remove `sharedDependencies`, and rebuild from
|
|
109
|
+
the retained classic scripts. That path needs neither installed module dependencies nor a lock.
|
|
110
|
+
Source-based unbundling is unchanged. Direct unbundling from an SB3 still requires the separate
|
|
111
|
+
`recoveryCapsule: true` option. The capsule contains original classic scripts as data, increasing
|
|
112
|
+
artifact size even though the executing shared library has one copy. Measure sizes with it disabled.
|
|
113
|
+
Actual browser permission dialogs and GUI interaction still need the manual checks below.
|
|
114
|
+
|
|
115
|
+
## Classic overview
|
|
116
|
+
|
|
12
117
|
```mermaid
|
|
13
118
|
flowchart LR
|
|
14
119
|
subgraph Source["Expanded source (authoritative)"]
|
|
@@ -548,3 +653,22 @@ bundling, then open the generated SB3 in a fresh TurboWarp session and verify al
|
|
|
548
653
|
|
|
549
654
|
Exclude a member from the bundle and keep it as an individual extension when its compatibility
|
|
550
655
|
cannot be verified.
|
|
656
|
+
|
|
657
|
+
## Block editor registrations (off by default)
|
|
658
|
+
|
|
659
|
+
Set `blockEditorRegistrations: true` on a bundle in `embedded-extensions.json` to adapt GUI
|
|
660
|
+
registration identities to the bundled opcode namespace. This is a manifest option, not a new CLI flag.
|
|
661
|
+
The generated runtime uses `Scratch.gui.blockEditors` only when `apiVersion === 1` and preserves
|
|
662
|
+
which registration capabilities the host exposes: `registerSchema`, `registerSchemaBundle`,
|
|
663
|
+
`registerSourceEditor`, and `registerFixedInputEditor`.
|
|
664
|
+
|
|
665
|
+
`extensionId` becomes the bundle ID, `editorId` gains a `memberId__` prefix, and each full member
|
|
666
|
+
opcode becomes `bundleId_memberId__opcode`. Schema, bindings, callbacks, validation context, saved
|
|
667
|
+
values, and returned disposers retain their identity. Callbacks still receive the GUI's actual block
|
|
668
|
+
snapshot, so callbacks that inspect opcodes must accept the bundled opcode. Registrations for a
|
|
669
|
+
foreign member are rejected. Frozen host API objects are supported without mutating them.
|
|
670
|
+
|
|
671
|
+
An absent or false option preserves existing behavior. GUI-less projects, absent capabilities, and
|
|
672
|
+
unsupported API versions continue to work. No form implementation, Schema compiler, Ajv, YAML, or
|
|
673
|
+
React is added to the bundle. To roll back, disable the option and rebuild, or disable the GUI's editor
|
|
674
|
+
feature flags and reload. No data migration is needed. See the [Japanese guide](ja/extension-bundles.md).
|
package/docs/index.html
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="ja">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8" />
|
|
5
|
+
<meta name="viewport" content="width=device-width,initial-scale=1" />
|
|
6
|
+
<title>SB3 Toolchain — library documentation</title>
|
|
7
|
+
<link rel="canonical" href="https://kubohiroya.github.io/sb3-toolchain/" />
|
|
8
|
+
<style>
|
|
9
|
+
body {
|
|
10
|
+
font-family: system-ui, sans-serif;
|
|
11
|
+
line-height: 1.7;
|
|
12
|
+
max-width: 70rem;
|
|
13
|
+
margin: auto;
|
|
14
|
+
padding: 1.5rem;
|
|
15
|
+
color: #18212b;
|
|
16
|
+
background: #fafbfc;
|
|
17
|
+
}
|
|
18
|
+
nav {
|
|
19
|
+
display: flex;
|
|
20
|
+
gap: 1rem;
|
|
21
|
+
flex-wrap: wrap;
|
|
22
|
+
}
|
|
23
|
+
pre {
|
|
24
|
+
overflow: auto;
|
|
25
|
+
background: #edf1f5;
|
|
26
|
+
padding: 1rem;
|
|
27
|
+
}
|
|
28
|
+
table {
|
|
29
|
+
border-collapse: collapse;
|
|
30
|
+
width: 100%;
|
|
31
|
+
}
|
|
32
|
+
th,
|
|
33
|
+
td {
|
|
34
|
+
border: 1px solid #b8c2cc;
|
|
35
|
+
padding: 0.6rem;
|
|
36
|
+
text-align: left;
|
|
37
|
+
}
|
|
38
|
+
a {
|
|
39
|
+
color: #064ba5;
|
|
40
|
+
}
|
|
41
|
+
section {
|
|
42
|
+
scroll-margin-top: 1rem;
|
|
43
|
+
}
|
|
44
|
+
code {
|
|
45
|
+
overflow-wrap: anywhere;
|
|
46
|
+
}
|
|
47
|
+
</style>
|
|
48
|
+
</head>
|
|
49
|
+
<body>
|
|
50
|
+
<header>
|
|
51
|
+
<h1>SB3 Toolchain</h1>
|
|
52
|
+
<p><code>@kubohiroya/sb3-toolchain@0.17.0</code></p>
|
|
53
|
+
<nav aria-label="Documentation">
|
|
54
|
+
<a href="#scope">責務</a><a href="#usage">使い方</a><a href="#api">API</a
|
|
55
|
+
><a href="#schemas">Schema</a><a href="#guides">関連文書</a>
|
|
56
|
+
</nav>
|
|
57
|
+
</header>
|
|
58
|
+
<main>
|
|
59
|
+
<section id="scope">
|
|
60
|
+
<h2>責務と公開範囲</h2>
|
|
61
|
+
<p>
|
|
62
|
+
Scratch 3 /
|
|
63
|
+
TurboWarpのSB3をGit管理できる展開ソースへimportし、検証・決定的な再buildを行うCLIとJavaScript
|
|
64
|
+
APIです。埋込拡張のversion・SHA-256・API manifestの検証にも対応します。
|
|
65
|
+
</p>
|
|
66
|
+
<p>
|
|
67
|
+
このページはlibraryのドキュメントです。TurboWarp拡張の独立したpaletteやブロックは提供しません。
|
|
68
|
+
</p>
|
|
69
|
+
</section>
|
|
70
|
+
<section id="usage">
|
|
71
|
+
<h2>使い方</h2>
|
|
72
|
+
<p>公開済みの完全固定versionを使います。</p>
|
|
73
|
+
<pre><code>npm install --save-exact @kubohiroya/sb3-toolchain@0.17.0</code></pre>
|
|
74
|
+
<pre><code>sb3-toolchain import tmp/project.sb3 --output app
|
|
75
|
+
sb3-toolchain check app
|
|
76
|
+
sb3-toolchain build app --output dist/project.sb3</code></pre>
|
|
77
|
+
</section>
|
|
78
|
+
<section id="api">
|
|
79
|
+
<h2>API</h2>
|
|
80
|
+
<table>
|
|
81
|
+
<thead>
|
|
82
|
+
<tr>
|
|
83
|
+
<th>入口</th>
|
|
84
|
+
<th>責務</th>
|
|
85
|
+
</tr>
|
|
86
|
+
</thead>
|
|
87
|
+
<tbody>
|
|
88
|
+
<tr>
|
|
89
|
+
<th><code>importSb3</code></th>
|
|
90
|
+
<td>SB3を展開ソースへimportします。</td>
|
|
91
|
+
</tr>
|
|
92
|
+
<tr>
|
|
93
|
+
<th><code>validateSb3Source</code></th>
|
|
94
|
+
<td>展開ソースのアセット参照や整合性を検証します。</td>
|
|
95
|
+
</tr>
|
|
96
|
+
<tr>
|
|
97
|
+
<th><code>buildSb3</code></th>
|
|
98
|
+
<td>展開ソースからSB3をbuildします。</td>
|
|
99
|
+
</tr>
|
|
100
|
+
<tr>
|
|
101
|
+
<th><code>bundleExtensions</code></th>
|
|
102
|
+
<td>管理対象の埋込拡張を一つの権限単位へ静的bundleします。</td>
|
|
103
|
+
</tr>
|
|
104
|
+
</tbody>
|
|
105
|
+
</table>
|
|
106
|
+
<p>
|
|
107
|
+
全ての公開型・引数は<a
|
|
108
|
+
href="https://github.com/kubohiroya/sb3-toolchain/blob/main/README.ja.md"
|
|
109
|
+
>README</a
|
|
110
|
+
>と<a href="https://github.com/kubohiroya/sb3-toolchain/tree/main/src">source</a
|
|
111
|
+
>を参照してください。
|
|
112
|
+
</p>
|
|
113
|
+
</section>
|
|
114
|
+
<section id="schemas">
|
|
115
|
+
<h2>Schemaの正本と公開コピー</h2>
|
|
116
|
+
<p>
|
|
117
|
+
このCLIは独立したJSON
|
|
118
|
+
Schemaの配布元ではありません。展開ソースの形式と検証規則は以下の関連文書を参照してください。
|
|
119
|
+
</p>
|
|
120
|
+
</section>
|
|
121
|
+
<section id="guides">
|
|
122
|
+
<h2>関連文書</h2>
|
|
123
|
+
<ul>
|
|
124
|
+
<li><a href="extension-api-compatibility.md">extension-api-compatibility.md</a></li>
|
|
125
|
+
<li><a href="extension-bundles.md">extension-bundles.md</a></li>
|
|
126
|
+
<li><a href="extension-id-migration.md">extension-id-migration.md</a></li>
|
|
127
|
+
<li><a href="ja/extension-api-compatibility.md">ja/extension-api-compatibility.md</a></li>
|
|
128
|
+
<li><a href="ja/extension-bundles.md">ja/extension-bundles.md</a></li>
|
|
129
|
+
<li><a href="ja/extension-id-migration.md">ja/extension-id-migration.md</a></li>
|
|
130
|
+
<li><a href="ja/project-asset-additions.md">ja/project-asset-additions.md</a></li>
|
|
131
|
+
<li><a href="ja/source-format-v1.md">ja/source-format-v1.md</a></li>
|
|
132
|
+
<li><a href="ja/workflows.md">ja/workflows.md</a></li>
|
|
133
|
+
<li><a href="project-asset-additions.md">project-asset-additions.md</a></li>
|
|
134
|
+
<li><a href="source-format-v1.md">source-format-v1.md</a></li>
|
|
135
|
+
<li><a href="workflows.md">workflows.md</a></li>
|
|
136
|
+
<li>
|
|
137
|
+
<a href="https://github.com/kubohiroya/sb3-toolchain/blob/main/README.md"
|
|
138
|
+
>English README</a
|
|
139
|
+
>
|
|
140
|
+
</li>
|
|
141
|
+
<li>
|
|
142
|
+
<a href="https://github.com/kubohiroya/sb3-toolchain/blob/main/README.ja.md"
|
|
143
|
+
>日本語 README</a
|
|
144
|
+
>
|
|
145
|
+
</li>
|
|
146
|
+
</ul>
|
|
147
|
+
</section>
|
|
148
|
+
</main>
|
|
149
|
+
<footer>
|
|
150
|
+
<p><a href="https://github.com/kubohiroya/sb3-toolchain">GitHub source</a> · MPL-2.0</p>
|
|
151
|
+
</footer>
|
|
152
|
+
</body>
|
|
153
|
+
</html>
|
|
@@ -8,6 +8,105 @@
|
|
|
8
8
|
|
|
9
9
|
## 概要
|
|
10
10
|
|
|
11
|
+
既定の`classic`方式は完成済みJSを束ねます。依存ライブラリも共有する場合は、以下のmodule方式を明示的に選びます。
|
|
12
|
+
|
|
13
|
+
## module統合ビルド(既定OFF)
|
|
14
|
+
|
|
15
|
+
全メンバーが`./bundle-module`の契約に対応する場合、単一のbrowser向け依存graphから複合JSを生成できます。
|
|
16
|
+
入口は`createExtension(scratch)`と`bundleModuleMetadata`(`formatVersion: 1` / `id` / `unsandboxed`)をexportします。
|
|
17
|
+
import時に拡張の生成・登録・listener接続を行わず、factoryは注入されたScratchを使用して同期的に新規instanceを返します。
|
|
18
|
+
toolchainはメンバーごとのScratch proxyを渡して各factoryを1回呼び、外部への登録を複合拡張の1回にまとめます。
|
|
19
|
+
|
|
20
|
+
`embedded-extensions.json`の各メンバーの既存npm `source`へ、package内のJS入口を追加します。
|
|
21
|
+
次の例のintegrityは実際のファイルのSHA-256に置き換えてください。
|
|
22
|
+
|
|
23
|
+
```json
|
|
24
|
+
{
|
|
25
|
+
"provider": "npm",
|
|
26
|
+
"package": "@example/extension-one",
|
|
27
|
+
"version": "1.0.0",
|
|
28
|
+
"artifact": "dist/extension-one.js",
|
|
29
|
+
"integrity": "sha256-<classic JSのbase64 digest>",
|
|
30
|
+
"module": {
|
|
31
|
+
"artifact": "lib-module/src/bundle-module.js",
|
|
32
|
+
"formatVersion": 1,
|
|
33
|
+
"integrity": "sha256-<module JSのbase64 digest>",
|
|
34
|
+
"unsandboxed": "required"
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
bundle側には次を指定します。
|
|
40
|
+
|
|
41
|
+
```json
|
|
42
|
+
{
|
|
43
|
+
"id": "projectbundle",
|
|
44
|
+
"name": "Project Extension Bundle",
|
|
45
|
+
"members": ["extensionone", "extensiontwo"],
|
|
46
|
+
"buildMode": "module",
|
|
47
|
+
"sharedDependencies": {"yaml": "2.9.1"},
|
|
48
|
+
"blockEditorRegistrations": true
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
対応する固定版packageと共有yamlをプロジェクトの`node_modules`へ事前installし、`pnpm-lock.yaml`または
|
|
53
|
+
`package-lock.json`を保持します。`app`のような展開ソースの親directoryも探索対象です。
|
|
54
|
+
toolchain自身のyamlは共有入力として使用しません。ビルド時にinstall、repository clone、拡張コードや
|
|
55
|
+
project側のビルド設定・pluginの実行は行いません。初期対応はinstall済みnpm artifactで、GitHub sourceはclassicを使います。
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
sb3-toolchain extensions bundle app --id projectbundle --name "Project Extension Bundle" \
|
|
59
|
+
extensionone extensiontwo --build-mode module --share yaml@2.9.1
|
|
60
|
+
# 表示された計画を確認後、同じ指定に --yes を付けて保存する。
|
|
61
|
+
sb3-toolchain build app --output dist/project.sb3
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
APIは`bundleExtensions` / `planExtensionBundle`の`buildMode`と`sharedDependencies`でも指定できます。
|
|
65
|
+
`--share`は複数指定でき、完全な版番号を要求します。GUIの編集登録変換は従来どおりmanifestで明示選択します。
|
|
66
|
+
|
|
67
|
+
共有packageの要求範囲と選択版を照合し、browser条件で同じ実体へ解決します。yamlはbrowser入口に限定し、
|
|
68
|
+
別コピーやNode向け実装が混ざるgraphを拒否します。版・classicとの一致・module integrity・対応入口不足も診断します。
|
|
69
|
+
必要なunsandboxed権限を得られなければ、ライブラリ評価やfactory生成より前に従来の案内拡張だけを登録します。
|
|
70
|
+
実行時には全メンバーのmetadataを確認してから初期化し、途中でfactoryが失敗した場合は先行instanceをdisposeします。
|
|
71
|
+
複合拡張の`dispose()`は各メンバーを一度だけ解除します。
|
|
72
|
+
|
|
73
|
+
`createDeterministicSb3(...).bundlePlans[].moduleBuild`とbundle計画の`moduleBuild`には、bundlerの版、browser / ES2020設定、
|
|
74
|
+
lockのdigest、各入口と読み込んだ依存ファイル・package manifestのdigest、共有実体数を返します。
|
|
75
|
+
生成JSの`Module build inputs`コメントはこの入力記録のdigestです。絶対pathは記録へ含めません。
|
|
76
|
+
依存lockは入力としてhash化し、実際のinstall内容も記録するため、再現時にはlockに従ってinstallしてください。
|
|
77
|
+
ownerの更新時はclassicとmodule両方のintegrityを更新します。module pinが古い場合、更新候補の検証は失敗して既存ソースを保持します。
|
|
78
|
+
|
|
79
|
+
共有するのはbundle読込単位のライブラリ実装とmodule評価です。Parser / Composer / Document等の解析状態は
|
|
80
|
+
従来どおり入力ごとに生成し、別bundleやGUIの別graphをまたぐsingletonにはしません。
|
|
81
|
+
既存feature flag、保存ID、opcode、解析オプションは変更しません。
|
|
82
|
+
|
|
83
|
+
### 検証と切戻し
|
|
84
|
+
|
|
85
|
+
通常のテストには、同版yamlを各メンバーの下に重複配置したfixtureを含めます。
|
|
86
|
+
未公開の実owner入口を検証する場合は、3つのcleanなcheckoutを次の順番で渡します。
|
|
87
|
+
事前に各ownerをbuildしておきます。この準備scriptはローカルでpackし、lifecycle scriptを無効にしてproduction installします。
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
node scripts/prepare-module-owner-fixture.mjs /tmp/new-module-owners \
|
|
91
|
+
/path/to/turbowarp-structured-data /path/to/turbowarp-yaml-json /path/to/turbowarp-3d-scene-runtime
|
|
92
|
+
SB3_MODULE_OWNER_FIXTURE=/tmp/new-module-owners/app pnpm exec vitest run test/extension-module-owners.test.ts
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
実owner検証は環境変数の指定時に実行し、通常CIではskipします。結果・全入力digest・owner commitはfixture親の
|
|
96
|
+
`module-owner-results.json`、生成物は`shared-yaml.js` / `shared-yaml.sb3`へ保存します。
|
|
97
|
+
module評価とfactoryのcounterはテスト用transformだけに挿入し、サイズと再現性はcounterを含まない生成物で測定します。
|
|
98
|
+
解析・Schema検証・編集登録 / 解除・権限分岐・復元カプセルも検証します。
|
|
99
|
+
|
|
100
|
+
切戻しは`buildMode`を未指定または`classic`にし、`sharedDependencies`を削除して再生成します。
|
|
101
|
+
元classic JSを保持しているためmodule依存やlockなしでも生成できます。設定を削除するsourceのunbundleも従来どおりです。
|
|
102
|
+
SB3単体からの解除には`recoveryCapsule: true`を別途選択してください。カプセルは元classic JSをデータとして含むため、
|
|
103
|
+
実行される共有実装が1組でも成果物サイズは増えます。計測時はカプセルをOFFにします。
|
|
104
|
+
ブラウザ上の実際の権限dialogやGUI操作は、後述の手動検証項目で確認してください。
|
|
105
|
+
|
|
106
|
+
## classic方式の概要
|
|
107
|
+
|
|
108
|
+
以下は既定classic方式の説明です。module方式でも同じopcode / storage / 編集binding変換と復元処理を使用します。
|
|
109
|
+
|
|
11
110
|
```mermaid
|
|
12
111
|
flowchart LR
|
|
13
112
|
subgraph Source["展開ソース(信頼できる情報源)"]
|
|
@@ -526,3 +625,37 @@ bundle前後に同じプロジェクトレベルの自動テストを実行し
|
|
|
526
625
|
- TurboWarpで再保存したSB3が機能拡張ストレージを保持し、再読み込み後も動作する
|
|
527
626
|
|
|
528
627
|
互換性を検証できないメンバーはbundleから除外し、個別機能拡張として保持してください。
|
|
628
|
+
|
|
629
|
+
## ブロック編集機能の登録(既定 OFF)
|
|
630
|
+
|
|
631
|
+
`embedded-extensions.json` の対象 `extensionBundles[]` に
|
|
632
|
+
`"blockEditorRegistrations": true` を指定すると、GUI の編集機能登録も
|
|
633
|
+
バンドル後の ID に対応させます。CLI の新しいフラグは追加せず、設定ファイルから有効化します。
|
|
634
|
+
|
|
635
|
+
```json
|
|
636
|
+
{
|
|
637
|
+
"id": "projectbundle",
|
|
638
|
+
"name": "Project Bundle",
|
|
639
|
+
"members": ["alpha", "beta"],
|
|
640
|
+
"blockEditorRegistrations": true
|
|
641
|
+
}
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
起動時に `Scratch.gui.blockEditors.apiVersion === 1` を確認し、GUI が実際に公開する
|
|
645
|
+
`registerSchema` / `registerSchemaBundle` / `registerSourceEditor` /
|
|
646
|
+
`registerFixedInputEditor` に対応します。GUI 側で隠した capability は追加しません。
|
|
647
|
+
GUI がない作品、未対応の API version、未指定または false の場合は従来の経路です。
|
|
648
|
+
|
|
649
|
+
- `extensionId`: member ID → bundle ID。
|
|
650
|
+
- `editorId`: `profile` → `alpha__profile`。異なる member の同名 editor は衝突しません。
|
|
651
|
+
- `opcodes`: `alpha_edit` → `projectbundle_alpha__edit`。
|
|
652
|
+
- Schema / bindings / callbacks / context / 保存値 / 登録解除関数は変換しません。
|
|
653
|
+
|
|
654
|
+
所有者の callback に渡すブロック snapshot も GUI が読んだものを維持します。
|
|
655
|
+
callback が opcode を検査する場合、実際の bundle opcode を扱える必要があります。
|
|
656
|
+
登録時の extensionId が member ID と異なる場合や、別 member の opcode を含む場合は拒否します。
|
|
657
|
+
|
|
658
|
+
この機能は編集機能の登録を対応させるだけです。フォーム、Schema compiler、Ajv、YAML、React は
|
|
659
|
+
GUI と共通 editor の責務であり、bundle に追加しません。
|
|
660
|
+
ロールバックは設定を false にして再ビルドします。GUI の編集フラグを OFF にして再読込しても
|
|
661
|
+
編集 UI を無効化できます。ブロックの実行や保存値の移行は不要です。
|
|
@@ -169,6 +169,8 @@ APIマニフェストファイルは展開ソースの検証入力であり、SB
|
|
|
169
169
|
LABELエントリとseparatorは変更されない
|
|
170
170
|
- `recoveryCapsule`: 任意の真偽値で、既定値は`false`。追加サイズを許容でき、生成SB3単体からの直接unbundleが
|
|
171
171
|
必要な場合に限り`true`を指定する
|
|
172
|
+
- `buildMode`: 任意の`classic`(既定)または`module`。module方式では各メンバーのnpm `source.module`にJS artifact、formatVersion 1、SHA-256 integrity、明示的な`unsandboxed`要件を指定し、ownerコードを実行せず単一のbrowser依存graphをビルドする
|
|
173
|
+
- `sharedDependencies`: module方式だけで指定できるpackage名と完全な版番号の対応表。projectへlock付きで事前installし、互換な依存を同じ実体へ解決する。[module統合ビルドの説明](extension-bundles.md#module統合ビルド既定off)を参照
|
|
172
174
|
- `sandboxedNotice`: 任意のオブジェクトで、bundleがサンドボックス内で読み込まれたときの通知文を小文字の言語タグ
|
|
173
175
|
ごとに指定する。メンバーの`// Unsandboxed:`ヘッダーによってbundleが`required`または`optional`になる場合だけ
|
|
174
176
|
指定でき、省略時は内蔵の`en`と`ja`の通知文を使う。[`extension-bundles.md`](extension-bundles.md)を参照
|
package/docs/source-format-v1.md
CHANGED
|
@@ -173,6 +173,8 @@ only in the generated SB3.
|
|
|
173
173
|
- `name`: single-line name displayed in the permission prompt and extension category
|
|
174
174
|
- `members`: two or more individual extension IDs; their order defines block and menu composition order. The palette receives a decorated, metadata-bearing bundle LABEL heading and a double separator between groups, while LABEL entries and separators from the original extensions remain unchanged
|
|
175
175
|
- `recoveryCapsule`: optional boolean, default `false`. Set it to `true` only when the extra size is acceptable and direct unbundling from the generated SB3 is required
|
|
176
|
+
- `buildMode`: optional `classic` (default) or `module`. Module mode requires each member's npm `source.module` JavaScript artifact, format 1, SHA-256 integrity, and explicit `unsandboxed` requirement. It builds one browser dependency graph without executing owner code
|
|
177
|
+
- `sharedDependencies`: optional package-to-exact-version map, allowed only in module mode. The selected packages must be installed in the project with a dependency lock; compatible member imports share one real package. See the [module build guide](extension-bundles.md#module-builds-off-by-default)
|
|
176
178
|
- `sandboxedNotice`: optional object mapping lowercase language tags to the message shown when the bundle is loaded sandboxed. Allowed only when a member's `// Unsandboxed:` header makes the bundle `required` or `optional`; built-in `en` and `ja` messages apply otherwise. See [`extension-bundles.md`](extension-bundles.md#declare-unsandboxed-loading)
|
|
177
179
|
|
|
178
180
|
A member cannot belong to more than one bundle. Individual entries, individual JavaScript, `source`,
|