world-manager/docs/quick-look-plan.md

Quick Look Architecture

Summary

The app includes Quick Look thumbnail and preview extensions for Minecraft Bedrock package files:

• .mcworld
• .mcpack
• .mctemplate
• .mcaddon

Both extensions share the same package inspection and thumbnail rendering code used by the app target where possible.

Targets

Thumbnail Extension

MinecraftPackageThumbnailExtension/ThumbnailProvider.swift

• Implements QLThumbnailProvider.
• Calls MinecraftPackageInspector.inspectArchive(at:).
• Renders a CGImage with MinecraftPackageThumbnailRenderer.
• Cleans up the temporary extraction directory with MinecraftPackageInspector.cleanup.

Preview Extension

MinecraftPackagePreviewExtension/PreviewViewController.swift

• Implements QLPreviewingController.
• Inspects the selected package archive.
• Displays the package icon when one exists.
• Falls back to the generated thumbnail artwork.
• Keeps the inspection result alive while the preview is displayed, then removes temporary extraction files in deinit.

The preview is currently image-focused. MinecraftPackageQuickLookModelBuilder already builds structured facts, but the preview controller does not render those facts yet.

Shared Package Inspection

MinecraftPackageInspector is the central archive reader for Quick Look:

• Accepts .mcworld, .mcpack, .mctemplate, and .mcaddon.
• Uses ZipArchiveReader to inspect ZIP entries.
• Supports packages with content at the archive root or under one top-level folder.
• Extracts only metadata-relevant files into a temporary inspection directory.
• Resolves content type from extension and manifest metadata.
• Reads display name, icon, world metadata, and manifest metadata.

Inspection results include:

• archive URL
• temporary extraction root
• resolved content root
• content type
• display name
• icon URL
• world metadata
• manifest metadata

Callers are responsible for cleanup.

Metadata Readers

MinecraftContentMetadataReader provides shared metadata parsing:

• World display names from levelname.txt.
• Pack display names from manifest.json.
• World icons from world_icon.*.
• Pack icons from pack_icon.*.
• World metadata from level.dat through BedrockLevelMetadataDecoder.
• Manifest UUID, version, and minimum engine version.
• Pack type inference for ambiguous .mcpack and .mcaddon archives.

MinecraftPackageQuickLookModelBuilder converts inspection results into preview-friendly facts such as version, UUID, engine version, game mode, difficulty, last played date, seed, and Bedrock version.

Thumbnail Rendering

MinecraftPackageThumbnailRenderer renders square thumbnail artwork:

• If the package has an icon, it draws that icon cropped to a rounded square with a subtle border.
• If no icon is present, it draws a generated voxel-style badge with content-type-specific colors.
• Rendering is done with AppKit bitmap drawing and returns a CGImage.

Type Registration

The main app registers exported UTTypes and document roles for Minecraft package extensions in World-Manager-for-Minecraft-Info.plist.

The extension Info.plists list the same internal UTTypes under QLSupportedContentTypes:

• us.b-wells.minecraft.mcworld
• us.b-wells.minecraft.mcpack
• us.b-wells.minecraft.mctemplate
• us.b-wells.minecraft.mcaddon

Relevant Files

• World-Manager-for-Minecraft-Info.plist
• MinecraftPackageThumbnailExtension/Info.plist
• MinecraftPackageThumbnailExtension/ThumbnailProvider.swift
• MinecraftPackagePreviewExtension/Info.plist
• MinecraftPackagePreviewExtension/PreviewViewController.swift
• World Manager for Minecraft/QuickLook/MinecraftPackageTypes.swift
• World Manager for Minecraft/QuickLook/MinecraftPackageQuickLookModel.swift
• World Manager for Minecraft/QuickLook/MinecraftPackageThumbnailRenderer.swift
• World Manager for Minecraft/Services/ArchiveInspection/MinecraftPackageInspector.swift
• World Manager for Minecraft/Services/ArchiveInspection/MinecraftContentMetadataReader.swift
• World Manager for Minecraft/Services/ArchiveInspection/ZipArchiveReader.swift

Current Limitations

• Preview rendering shows only an image, not the structured metadata facts.
• .mcaddon support resolves one content root; multi-pack add-ons are not yet presented as a compound package.
• The inspector extracts only metadata files, which is intentional for Quick Look speed but means package validation is shallow.

Verification

Run:

xcodebuild \
  -project "World Manager for Minecraft.xcodeproj" \
  -scheme "World Manager for Minecraft" \
  -configuration Debug \
  build

The unit tests cover archive inspection behavior in World Manager for MinecraftTests/World_Manager_for_MinecraftTests.swift.