@rbxts/toucan-debugger 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Over
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @rbxts/toucan-debugger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A visual debugger plugin for [Toucan](https://github.com/OverlineJunior/toucan).
+
+It is currently very early in development and cannot observe the server. It can however:
+
+- List every entity-like along its id and type icon;
+- Display `ChildOf` hierarchies;
+- Measure system runtimes (they're under schedules).
+
+## Installation
+
+```sh
+npm install @rbxts/toucan-debugger
+```
+
+> [!IMPORTANT]
+> The version of Toucan your game uses must be the same as the one this debugger plugin uses. This package currently targets `@rbxts/toucan` `0.6.0`.
+
+## Usage
+
+Pass the plugin to your scheduler before calling `run()`. It must be used on the client.
+
+```ts
+import toucanDebugger, { themes } from "@rbxts/toucan-debugger";
+
+// Passing a theme is optional — defaults to black.
+scheduler().usePlugin(toucanDebugger, themes.black).run();
+```

package/out/collapsible.d.ts

@@ -0,0 +1,7 @@
+import type { Theme } from './themes';
+export declare const Collapsible: import("@rbxts/toucan").Component<{
+    toggleButton: GuiButton;
+    chevron: ImageLabel;
+    body: GuiObject;
+}>;
+export declare function updateCollapsible(theme: Theme): void;

package/out/collapsible.luau

@@ -0,0 +1,47 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _toucan = TS.import(script, TS.getModule(script, "@rbxts", "toucan").out)
+local component = _toucan.component
+local query = _toucan.query
+local Collapsible = component("Collapsible")
+-- TODO: This is temporary - use `useEvent` or another approach.
+local Done = component("Done")
+local function updateCollapsible(theme)
+	query(Collapsible):forEach(function(e, _param)
+		local toggleButton = _param.toggleButton
+		local chevron = _param.chevron
+		local body = _param.body
+		local _exp = body:GetChildren()
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		local _callback = function(c)
+			return c:IsA("GuiObject")
+		end
+		for _k, _v in _exp do
+			if _callback(_v, _k - 1, _exp) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		local hasContent = _result
+		chevron.Visible = hasContent
+		body.Visible = if hasContent then body.Visible else false
+		if not e:has(Done) then
+			-- Start closed.
+			body.Visible = false
+			toggleButton.MouseButton1Click:Connect(function()
+				if not hasContent then
+					return nil
+				end
+				body.Visible = not body.Visible
+				chevron.Image = if body.Visible then theme.icons.chevronDown else theme.icons.chevronRight
+			end)
+			e:set(Done)
+		end
+	end)
+end
+return {
+	updateCollapsible = updateCollapsible,
+	Collapsible = Collapsible,
+}

package/out/drawEntityEntries.d.ts

@@ -0,0 +1,4 @@
+import type { Theme } from './themes';
+export declare const EntryFor: import("@rbxts/toucan").Component<undefined>;
+export declare function drawEntityEntries(theme: Theme): void;
+export declare function bindEntityEntryCleanup(): void;

package/out/drawEntityEntries.luau

@@ -0,0 +1,97 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _toucan = TS.import(script, TS.getModule(script, "@rbxts", "toucan").out)
+local Builtin = _toucan.Builtin
+local component = _toucan.component
+local pair = _toucan.pair
+local query = _toucan.query
+local _instance = TS.import(script, script.Parent, "instance")
+local Frame = _instance.Frame
+local ScrollingFrame = _instance.ScrollingFrame
+local _entityEntry = TS.import(script, script.Parent, "ui", "explorer", "entityEntry")
+local entityEntry = _entityEntry.default
+local NoEntry = _entityEntry.NoEntry
+local EntityList = TS.import(script, script.Parent, "ui", "explorer", "entityList").EntityList
+local EntryFor = component("EntryFor")
+local seen = {}
+local function canPlaceEntry(e)
+	local _condition = not e:has(NoEntry)
+	if _condition then
+		local _id = e.id
+		_condition = not (seen[_id] ~= nil)
+	end
+	return _condition
+end
+local function drawEntityEntries(theme)
+	local placeEntriesDeep
+	placeEntriesDeep = function(e, _param)
+		local parentEntt = _param[1]
+		local parentInst = _param[2]
+		local _binding = entityEntry(e, theme)
+		local _binding_1 = _binding[1]
+		local entryEntt = _binding_1[1]
+		local entryInst = _binding_1[2]
+		local body = _binding[2]
+		entryEntt:set(pair(Builtin.ChildOf, parentEntt))
+		entryEntt:set(pair(EntryFor, e))
+		entryInst.Parent = parentInst
+		local _id = e.id
+		seen[_id] = true
+		local _exp = e:children()
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _callback = function(c)
+			return canPlaceEntry(c)
+		end
+		local _length = 0
+		for _k, _v in _exp do
+			if _callback(_v, _k - 1, _exp) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		-- ▼ ReadonlyArray.forEach ▼
+		local _callback_1 = function(c)
+			return placeEntriesDeep(c, { entryEntt, body })
+		end
+		for _k, _v in _newValue do
+			_callback_1(_v, _k - 1, _newValue)
+		end
+		-- ▲ ReadonlyArray.forEach ▲
+	end
+	local _binding = query(ScrollingFrame):with(EntityList):collect()[1]
+	local containerEntt = _binding[1]
+	local containerInst = _binding[2]
+	local enttKinds = { Builtin.Entity, Builtin.Component, Builtin.Resource }
+	-- ▼ ReadonlyArray.forEach ▼
+	local _callback = function(enttKind)
+		query(enttKind):filter(function(e)
+			return canPlaceEntry(e) and e:parent() == nil
+		end):forEach(function(e)
+			return placeEntriesDeep(e, { containerEntt, containerInst })
+		end)
+	end
+	for _k, _v in enttKinds do
+		_callback(_v, _k - 1, enttKinds)
+	end
+	-- ▲ ReadonlyArray.forEach ▲
+end
+local function bindEntityEntryCleanup()
+	EntryFor:onRemoved(function(entry, _v, despawned)
+		if despawned then
+			return nil
+		end
+		local frame = entry:get(Frame)
+		if not frame then
+			return nil
+		end
+		frame:Destroy()
+		entry:despawn()
+	end)
+end
+return {
+	drawEntityEntries = drawEntityEntries,
+	bindEntityEntryCleanup = bindEntityEntryCleanup,
+	EntryFor = EntryFor,
+}

package/out/index.d.ts

@@ -0,0 +1,18 @@
+import type { Scheduler } from '@rbxts/toucan';
+import { type Theme } from './themes';
+export { type Theme, themes } from './themes';
+/**
+ * Spawns a visual debugger.
+ *
+ * @remarks
+ * Throws if used on the server.
+ *
+ * @example
+ * ```ts
+ * import toucanDebugger, { themes } from '@rbxts/toucan-debugger'
+ *
+ * // Passing a theme is optional — defaults to black.
+ * scheduler().usePlugin(toucanDebugger, themes.black).run()
+ * ```
+ */
+export default function toucanDebugger(scheduler: Scheduler, theme?: Theme): void;

package/out/init.luau

@@ -0,0 +1,52 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local _services = TS.import(script, TS.getModule(script, "@rbxts", "services"))
+local Players = _services.Players
+local RunService = _services.RunService
+local updateCollapsible = TS.import(script, script, "collapsible").updateCollapsible
+local _drawEntityEntries = TS.import(script, script, "drawEntityEntries")
+local bindEntityEntryCleanup = _drawEntityEntries.bindEntityEntryCleanup
+local drawEntityEntries = _drawEntityEntries.drawEntityEntries
+local themes = TS.import(script, script, "themes").themes
+local explorerPanel = TS.import(script, script, "ui").default
+local updateRuntimeLabel = TS.import(script, script, "updateRuntimeLabel").updateRuntimeLabel
+exports.themes = TS.import(script, script, "themes").themes
+local function setupDebuggerPanel(parent, theme)
+	explorerPanel(parent, theme)
+end
+--[[
+	*
+	 * Spawns a visual debugger.
+	 *
+	 * @remarks
+	 * Throws if used on the server.
+	 *
+	 * @example
+	 * ```ts
+	 * import toucanDebugger, { themes } from '@rbxts/toucan-debugger'
+	 *
+	 * // Passing a theme is optional — defaults to black.
+	 * scheduler().usePlugin(toucanDebugger, themes.black).run()
+	 * ```
+	 
+]]
+local function toucanDebugger(scheduler, theme)
+	if theme == nil then
+		theme = themes.black
+	end
+	if RunService:IsServer() then
+		error("Toucan's debugger can only be used on the client")
+	end
+	local client = Players.LocalPlayer
+	local playerGui = client:WaitForChild("PlayerGui")
+	scheduler:useSystem("preStartup", setupDebuggerPanel, {
+		args = { playerGui, theme },
+	}):useSystem("preStartup", bindEntityEntryCleanup):useSystemChain("last", { { drawEntityEntries, {
+		args = { theme },
+	} }, { updateCollapsible, {
+		args = { theme },
+	} }, updateRuntimeLabel })
+end
+exports.default = toucanDebugger
+return exports

package/out/instance.d.ts

@@ -0,0 +1,63 @@
+import { type Component, type Entity } from '@rbxts/toucan';
+export declare const Frame: Component<Frame>;
+export declare const ScreenGui: Component<ScreenGui>;
+export declare const ScrollingFrame: Component<ScrollingFrame>;
+export declare const ImageButton: Component<ImageButton>;
+export declare const ImageLabel: Component<ImageLabel>;
+export declare const TextLabel: Component<TextLabel>;
+export declare const UIPadding: Component<UIPadding>;
+export declare const UIListLayout: Component<UIListLayout>;
+export declare const UIFlexItem: Component<UIFlexItem>;
+export declare const UISizeConstraint: Component<UISizeConstraint>;
+export declare const UIAspectRatioConstraint: Component<UIAspectRatioConstraint>;
+export declare const UICorner: Component<UICorner>;
+export declare const UIStroke: Component<UIStroke>;
+declare const SUPPORTED_INSTANCES: {
+    Frame: Component<Frame>;
+    ScreenGui: Component<ScreenGui>;
+    ScrollingFrame: Component<ScrollingFrame>;
+    ImageButton: Component<ImageButton>;
+    ImageLabel: Component<ImageLabel>;
+    TextLabel: Component<TextLabel>;
+    UIPadding: Component<UIPadding>;
+    UIListLayout: Component<UIListLayout>;
+    UIFlexItem: Component<UIFlexItem>;
+    UISizeConstraint: Component<UISizeConstraint>;
+    UIAspectRatioConstraint: Component<UIAspectRatioConstraint>;
+    UICorner: Component<UICorner>;
+    UIStroke: Component<UIStroke>;
+};
+type SupportedInstances = typeof SUPPORTED_INSTANCES;
+export type EntityInstance<I extends Instance = Instance> = [Entity, I];
+type Child = EntityInstance | Entity | false | undefined;
+type InstanceProperties<T extends Instance> = Partial<WritableInstanceProperties<T>> & {
+    child?: Child;
+    children?: Child[];
+    callback?: (entity: Entity, instance: T) => void;
+    Name?: string;
+};
+/**
+ * Spawns an entity paired with a new instance of the given `className`, automatically setting the corresponding component and parenting any children.
+ *
+ * Giving the instance a `Name` will also give its entity a `Label` of the same name.
+ *
+ * @remarks
+ * Not every instance is supported, as there needs to be a corresponding component for it. If there's an instance you need that isn't supported, consider contributing.
+ *
+ * @example
+ * let textLabel: TextLabel
+ *
+ * const [btnEntt, btnInst] = entityFor('ImageButton', {
+ *     Size: new UDim2(0, 100, 0, 40),
+ *     Parent: playerGui,
+ *     child: entityFor('TextLabel', {
+ *         Text: 'Click me',
+ *         callback: (entt, inst) => {
+ *             entt.set(SpecialLabel)
+ *             textLabel = inst
+ *         },
+ *     }),
+ * })
+ */
+export declare function entityFor<T extends keyof SupportedInstances>(className: T, properties?: InstanceProperties<CreatableInstances[T]>): EntityInstance<CreatableInstances[T]>;
+export {};

package/out/instance.luau

@@ -0,0 +1,138 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _toucan = TS.import(script, TS.getModule(script, "@rbxts", "toucan").out)
+local Builtin = _toucan.Builtin
+local component = _toucan.component
+local EntityLike = _toucan.EntityLike
+local entity = _toucan.entity
+local pair = _toucan.pair
+local Frame = component("Frame")
+local ScreenGui = component("ScreenGui")
+local ScrollingFrame = component("ScrollingFrame")
+local ImageButton = component("ImageButton")
+local ImageLabel = component("ImageLabel")
+local TextLabel = component("TextLabel")
+local UIPadding = component("UIPadding")
+local UIListLayout = component("UIListLayout")
+local UIFlexItem = component("UIFlexItem")
+local UISizeConstraint = component("UISizeConstraint")
+local UIAspectRatioConstraint = component("UIAspectRatioConstraint")
+local UICorner = component("UICorner")
+local UIStroke = component("UIStroke")
+local SUPPORTED_INSTANCES = {
+	Frame = Frame,
+	ScreenGui = ScreenGui,
+	ScrollingFrame = ScrollingFrame,
+	ImageButton = ImageButton,
+	ImageLabel = ImageLabel,
+	TextLabel = TextLabel,
+	UIPadding = UIPadding,
+	UIListLayout = UIListLayout,
+	UIFlexItem = UIFlexItem,
+	UISizeConstraint = UISizeConstraint,
+	UIAspectRatioConstraint = UIAspectRatioConstraint,
+	UICorner = UICorner,
+	UIStroke = UIStroke,
+}
+local RESERVED_PROPERTIES = { "child", "children", "callback" }
+--[[
+	*
+	 * Spawns an entity paired with a new instance of the given `className`, automatically setting the corresponding component and parenting any children.
+	 *
+	 * Giving the instance a `Name` will also give its entity a `Label` of the same name.
+	 *
+	 * @remarks
+	 * Not every instance is supported, as there needs to be a corresponding component for it. If there's an instance you need that isn't supported, consider contributing.
+	 *
+	 * @example
+	 * let textLabel: TextLabel
+	 *
+	 * const [btnEntt, btnInst] = entityFor('ImageButton', {
+	 *     Size: new UDim2(0, 100, 0, 40),
+	 *     Parent: playerGui,
+	 *     child: entityFor('TextLabel', {
+	 *         Text: 'Click me',
+	 *         callback: (entt, inst) => {
+	 *             entt.set(SpecialLabel)
+	 *             textLabel = inst
+	 *         },
+	 *     }),
+	 * })
+	 
+]]
+local function entityFor(className, properties)
+	if properties == nil then
+		properties = {}
+	end
+	local _result = properties
+	if _result ~= nil then
+		_result = _result.Name
+	end
+	local _condition = _result
+	if _condition == nil then
+		_condition = className
+	end
+	local entt = entity(_condition)
+	local inst = Instance.new(className)
+	entt:set(SUPPORTED_INSTANCES[className], inst)
+	for k, v in pairs(properties) do
+		if table.find(RESERVED_PROPERTIES, k) ~= nil then
+			continue
+		end
+		inst[k] = v
+	end
+	local parentChild = function(child, entt, inst)
+		if not child then
+			return nil
+		end
+		if TS.instanceof(child, EntityLike) then
+			child:set(pair(Builtin.ChildOf, entt))
+		else
+			local _binding = child
+			local childEntt = _binding[1]
+			local childInst = _binding[2]
+			childEntt:set(pair(Builtin.ChildOf, entt))
+			childInst.Parent = inst
+		end
+	end
+	local _result_1 = properties
+	if _result_1 ~= nil then
+		_result_1 = _result_1.child
+	end
+	parentChild(_result_1, entt, inst)
+	local _result_2 = properties
+	if _result_2 ~= nil then
+		_result_2 = _result_2.children
+	end
+	local _condition_1 = _result_2
+	if _condition_1 == nil then
+		_condition_1 = {}
+	end
+	for _, child in _condition_1 do
+		parentChild(child, entt, inst)
+	end
+	local _result_3 = properties
+	if _result_3 ~= nil then
+		_result_3 = _result_3.callback
+		if _result_3 ~= nil then
+			_result_3(entt, inst)
+		end
+	end
+	return { entt, inst }
+end
+return {
+	entityFor = entityFor,
+	Frame = Frame,
+	ScreenGui = ScreenGui,
+	ScrollingFrame = ScrollingFrame,
+	ImageButton = ImageButton,
+	ImageLabel = ImageLabel,
+	TextLabel = TextLabel,
+	UIPadding = UIPadding,
+	UIListLayout = UIListLayout,
+	UIFlexItem = UIFlexItem,
+	UISizeConstraint = UISizeConstraint,
+	UIAspectRatioConstraint = UIAspectRatioConstraint,
+	UICorner = UICorner,
+	UIStroke = UIStroke,
+}

package/out/themes/black.d.ts

@@ -0,0 +1,3 @@
+import type { Theme } from '.';
+declare const blackTheme: Theme;
+export default blackTheme;

package/out/themes/black.luau

@@ -0,0 +1,50 @@
+-- Compiled with roblox-ts v3.0.0
+local FONT_INTER = "rbxassetid://12187365364"
+local blackTheme = {
+	colors = {
+		content = Color3.fromRGB(255, 255, 255),
+		contentMuted = Color3.fromRGB(130, 130, 130),
+		contentInverse = Color3.fromRGB(0, 0, 0),
+		surface1 = Color3.fromRGB(0, 0, 0),
+		surface2 = Color3.fromRGB(16, 16, 16),
+		surface3 = Color3.fromRGB(24, 24, 24),
+		border = Color3.fromRGB(64, 64, 64),
+		borderMuted = Color3.fromRGB(32, 32, 32),
+		client = Color3.fromRGB(40, 140, 255),
+		server = Color3.fromRGB(40, 255, 55),
+		err = Color3.fromRGB(255, 40, 40),
+	},
+	icons = {
+		chevronRight = "rbxassetid://84839472552140",
+		chevronRightBold = "rbxassetid://78446529333772",
+		chevronDown = "rbxassetid://123273356220210",
+		chevronDownBold = "rbxassetid://71570100619926",
+		entity = "rbxassetid://117106064006931",
+		component = "rbxassetid://132097048540989",
+		system = "rbxassetid://104146467001055",
+		schedule = "rbxassetid://73049254764861",
+		plugin = "rbxassetid://85799610981034",
+	},
+	fonts = {
+		black = Font.new(FONT_INTER, Enum.FontWeight.Heavy),
+		bold = Font.new(FONT_INTER, Enum.FontWeight.Bold),
+		regular = Font.new(FONT_INTER, Enum.FontWeight.Regular),
+		extraLightItalic = Font.new(FONT_INTER, Enum.FontWeight.ExtraLight, Enum.FontStyle.Italic),
+	},
+	fontSizes = {
+		tiny = 10,
+		small = 12,
+		large = 16,
+		huge = 36,
+	},
+	paddingSizes = {
+		small = UDim.new(nil, 3),
+		medium = UDim.new(nil, 6),
+		large = UDim.new(nil, 9),
+	},
+	explorerIndent = 20,
+}
+local default = blackTheme
+return {
+	default = default,
+}

package/out/themes/index.d.ts

@@ -0,0 +1,49 @@
+export declare const ROBLOX_TOPBAR_HEIGHT = 58;
+export interface Theme {
+    colors: {
+        content: Color3;
+        contentMuted: Color3;
+        contentInverse: Color3;
+        surface1: Color3;
+        surface2: Color3;
+        surface3: Color3;
+        border: Color3;
+        borderMuted: Color3;
+        client: Color3;
+        server: Color3;
+        err: Color3;
+    };
+    icons: {
+        chevronRight: string;
+        chevronRightBold: string;
+        chevronDown: string;
+        chevronDownBold: string;
+        entity: string;
+        component: string;
+        system: string;
+        schedule: string;
+        plugin: string;
+    };
+    fonts: {
+        black: Font;
+        bold: Font;
+        regular: Font;
+        extraLightItalic: Font;
+    };
+    fontSizes: {
+        tiny: number;
+        small: number;
+        large: number;
+        huge: number;
+    };
+    paddingSizes: {
+        small: UDim;
+        medium: UDim;
+        large: UDim;
+    };
+    explorerIndent: number;
+}
+export declare const themes: {
+    black: Theme;
+    white: Theme;
+};

package/out/themes/init.luau

@@ -0,0 +1,13 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local blackTheme = TS.import(script, script, "black").default
+local whiteTheme = TS.import(script, script, "white").default
+local ROBLOX_TOPBAR_HEIGHT = 58
+local themes = {
+	black = blackTheme,
+	white = whiteTheme,
+}
+return {
+	ROBLOX_TOPBAR_HEIGHT = ROBLOX_TOPBAR_HEIGHT,
+	themes = themes,
+}

package/out/themes/white.d.ts

@@ -0,0 +1,3 @@
+import type { Theme } from '.';
+declare const whiteTheme: Theme;
+export default whiteTheme;

package/out/themes/white.luau

@@ -0,0 +1,50 @@
+-- Compiled with roblox-ts v3.0.0
+local FONT_INTER = "rbxassetid://12187365364"
+local whiteTheme = {
+	colors = {
+		content = Color3.fromRGB(0, 0, 0),
+		contentMuted = Color3.fromRGB(125, 125, 125),
+		contentInverse = Color3.fromRGB(255, 255, 255),
+		surface1 = Color3.fromRGB(255, 255, 255),
+		surface2 = Color3.fromRGB(240, 240, 240),
+		surface3 = Color3.fromRGB(230, 230, 230),
+		border = Color3.fromRGB(190, 190, 190),
+		borderMuted = Color3.fromRGB(223, 223, 223),
+		client = Color3.fromRGB(0, 110, 230),
+		server = Color3.fromRGB(0, 170, 30),
+		err = Color3.fromRGB(220, 30, 30),
+	},
+	icons = {
+		chevronRight = "rbxassetid://84839472552140",
+		chevronRightBold = "rbxassetid://78446529333772",
+		chevronDown = "rbxassetid://123273356220210",
+		chevronDownBold = "rbxassetid://71570100619926",
+		entity = "rbxassetid://117106064006931",
+		component = "rbxassetid://132097048540989",
+		system = "rbxassetid://104146467001055",
+		schedule = "rbxassetid://73049254764861",
+		plugin = "rbxassetid://85799610981034",
+	},
+	fonts = {
+		black = Font.new(FONT_INTER, Enum.FontWeight.Heavy),
+		bold = Font.new(FONT_INTER, Enum.FontWeight.Bold),
+		regular = Font.new(FONT_INTER, Enum.FontWeight.Regular),
+		extraLightItalic = Font.new(FONT_INTER, Enum.FontWeight.ExtraLight, Enum.FontStyle.Italic),
+	},
+	fontSizes = {
+		tiny = 10,
+		small = 12,
+		large = 16,
+		huge = 36,
+	},
+	paddingSizes = {
+		small = UDim.new(nil, 3),
+		medium = UDim.new(nil, 6),
+		large = UDim.new(nil, 9),
+	},
+	explorerIndent = 20,
+}
+local default = whiteTheme
+return {
+	default = default,
+}

package/out/ui/explorer/dashboard.d.ts

@@ -0,0 +1,3 @@
+import { type EntityInstance } from '../../instance';
+import type { Theme } from '../../themes';
+export default function dashboard(theme: Theme): EntityInstance<Frame>;

package/out/ui/explorer/dashboard.luau

@@ -0,0 +1,14 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local entityFor = TS.import(script, script.Parent.Parent.Parent, "instance").entityFor
+local function dashboard(theme)
+	return entityFor("Frame", {
+		Name = "dashboard",
+		AutomaticSize = Enum.AutomaticSize.Y,
+		BackgroundColor3 = theme.colors.surface1,
+		LayoutOrder = 0,
+	})
+end
+return {
+	default = dashboard,
+}

package/out/ui/explorer/entityEntry.d.ts

@@ -0,0 +1,5 @@
+import { type EntityLike } from '@rbxts/toucan';
+import { type EntityInstance } from '../../instance';
+import type { Theme } from '../../themes';
+export declare const NoEntry: import("@rbxts/toucan").Component<undefined>;
+export default function entityEntry(entity: EntityLike, theme: Theme): [EntityInstance<Frame>, Frame];

package/out/ui/explorer/entityEntry.luau

@@ -0,0 +1,182 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _toucan = TS.import(script, TS.getModule(script, "@rbxts", "toucan").out)
+local Builtin = _toucan.Builtin
+local component = _toucan.component
+local pair = _toucan.pair
+local Collapsible = TS.import(script, script.Parent.Parent.Parent, "collapsible").Collapsible
+local entityFor = TS.import(script, script.Parent.Parent.Parent, "instance").entityFor
+local RuntimeLabelFor = TS.import(script, script.Parent.Parent.Parent, "updateRuntimeLabel").RuntimeLabelFor
+local HEADER_HEIGHT = 20
+local NoEntry = component("NoEntry")
+local function getEntityIcon(entity, theme)
+	if entity:has(Builtin.Component) then
+		return theme.icons.component
+	end
+	if entity:has(Builtin.System) then
+		return theme.icons.system
+	end
+	if entity:has(Builtin.Schedule) then
+		return theme.icons.schedule
+	end
+	if entity:has(Builtin.Plugin) then
+		return theme.icons.plugin
+	end
+	return theme.icons.entity
+end
+local function makeHeader(entity, theme, callback)
+	local chevron
+	local header = entityFor("ImageButton", {
+		Name = "header",
+		Size = UDim2.new(1, 0, 0, HEADER_HEIGHT),
+		BackgroundColor3 = theme.colors.surface2,
+		LayoutOrder = 0,
+		children = { entityFor("UIListLayout", {
+			FillDirection = Enum.FillDirection.Horizontal,
+			SortOrder = Enum.SortOrder.LayoutOrder,
+			Padding = theme.paddingSizes.medium,
+		}), entityFor("UIPadding", {
+			PaddingBottom = theme.paddingSizes.small,
+			PaddingTop = theme.paddingSizes.small,
+			PaddingLeft = theme.paddingSizes.small,
+			PaddingRight = theme.paddingSizes.small,
+		}), entityFor("UICorner", {
+			CornerRadius = theme.paddingSizes.medium,
+		}), entityFor("UIStroke", {
+			Color = theme.colors.border,
+		}), entityFor("Frame", {
+			Name = "left",
+			Size = UDim2.fromScale(0, 1),
+			BackgroundTransparency = 1,
+			children = { entityFor("UIListLayout", {
+				FillDirection = Enum.FillDirection.Horizontal,
+				SortOrder = Enum.SortOrder.LayoutOrder,
+				Padding = theme.paddingSizes.medium,
+			}), entityFor("UIFlexItem", {
+				FlexMode = Enum.UIFlexMode.Fill,
+			}), entityFor("ImageLabel", {
+				Name = "icon",
+				Image = getEntityIcon(entity, theme),
+				ImageColor3 = theme.colors.contentMuted,
+				Size = UDim2.fromScale(0, 1),
+				BackgroundTransparency = 1,
+				LayoutOrder = 0,
+				child = entityFor("UIAspectRatioConstraint", {
+					AspectType = Enum.AspectType.ScaleWithParentSize,
+					DominantAxis = Enum.DominantAxis.Height,
+				}),
+			}), entityFor("TextLabel", {
+				Name = "id",
+				Text = `#{entity.id}`,
+				FontFace = theme.fonts.regular,
+				TextSize = theme.fontSizes.small,
+				TextXAlignment = Enum.TextXAlignment.Left,
+				TextColor3 = theme.colors.contentMuted,
+				Size = UDim2.new(0, 33.5, 1, 0),
+				BackgroundTransparency = 1,
+				LayoutOrder = 1,
+			}), entityFor("TextLabel", {
+				Name = "label",
+				Text = entity:toString(),
+				FontFace = theme.fonts.regular,
+				TextSize = theme.fontSizes.small,
+				TextXAlignment = Enum.TextXAlignment.Left,
+				TextColor3 = theme.colors.content,
+				Size = UDim2.new(0, 40, 1, 0),
+				AutomaticSize = Enum.AutomaticSize.X,
+				BackgroundTransparency = 1,
+				LayoutOrder = 2,
+			}), entity:has(Builtin.System) and entityFor("TextLabel", {
+				Name = "runtime",
+				Text = "?",
+				FontFace = theme.fonts.extraLightItalic,
+				TextSize = theme.fontSizes.tiny,
+				TextXAlignment = Enum.TextXAlignment.Left,
+				TextYAlignment = Enum.TextYAlignment.Bottom,
+				TextColor3 = theme.colors.contentMuted,
+				Size = UDim2.new(0, 35, 1, 0),
+				BackgroundTransparency = 1,
+				LayoutOrder = 3,
+				callback = function(e)
+					return e:set(pair(RuntimeLabelFor, entity))
+				end,
+			}) },
+		}), entityFor("ImageLabel", {
+			Name = "chevron",
+			Size = UDim2.fromScale(0, 1),
+			Position = UDim2.fromScale(0.8, 0),
+			BackgroundTransparency = 1,
+			Image = theme.icons.chevronRight,
+			callback = function(_e, inst)
+				chevron = inst
+			end,
+			child = entityFor("UIAspectRatioConstraint", {
+				AspectType = Enum.AspectType.ScaleWithParentSize,
+				DominantAxis = Enum.DominantAxis.Height,
+			}),
+		}) },
+	})
+	callback(header[2], chevron)
+	return header
+end
+local function entityEntry(entity, theme)
+	local header
+	local chevron
+	local body
+	local entry = entityFor("Frame", {
+		Name = `entityEntry: {entity}`,
+		Size = UDim2.fromScale(0, 0),
+		AutomaticSize = Enum.AutomaticSize.Y,
+		Transparency = 1,
+		children = { entityFor("UIListLayout", {
+			FillDirection = Enum.FillDirection.Vertical,
+			SortOrder = Enum.SortOrder.LayoutOrder,
+			Padding = theme.paddingSizes.medium,
+		}), makeHeader(entity, theme, function(hdr, chv)
+			header = hdr
+			chevron = chv
+		end), entityFor("Frame", {
+			Name = "body",
+			Size = UDim2.fromScale(1, 0),
+			AutomaticSize = Enum.AutomaticSize.Y,
+			Transparency = 1,
+			LayoutOrder = 1,
+			callback = function(_e, inst)
+				body = inst
+			end,
+			children = { entityFor("UIListLayout", {
+				FillDirection = Enum.FillDirection.Vertical,
+				HorizontalFlex = Enum.UIFlexAlignment.Fill,
+				SortOrder = Enum.SortOrder.LayoutOrder,
+				Padding = theme.paddingSizes.medium,
+			}), entityFor("UIPadding", {
+				PaddingLeft = UDim.new(0, theme.explorerIndent),
+			}) },
+		}) },
+	})
+	entry[1]:set(Collapsible, {
+		toggleButton = header,
+		chevron = chevron,
+		body = body,
+	})
+	-- Without this, `drawEntities` would add entries infinitely, crashing the game.
+	local addNoEntryRecursive
+	addNoEntryRecursive = function(e)
+		e:set(NoEntry)
+		local _exp = e:children()
+		-- ▼ ReadonlyArray.forEach ▼
+		local _callback = function(c)
+			return addNoEntryRecursive(c)
+		end
+		for _k, _v in _exp do
+			_callback(_v, _k - 1, _exp)
+		end
+		-- ▲ ReadonlyArray.forEach ▲
+	end
+	addNoEntryRecursive(entry[1])
+	return { entry, body }
+end
+return {
+	default = entityEntry,
+	NoEntry = NoEntry,
+}

package/out/ui/explorer/entityList.d.ts

@@ -0,0 +1,4 @@
+import { type EntityInstance } from '../../instance';
+import type { Theme } from '../../themes';
+export declare const EntityList: import("@rbxts/toucan").Component<undefined>;
+export default function entityList(theme: Theme): EntityInstance<ScrollingFrame>;

package/out/ui/explorer/entityList.luau

@@ -0,0 +1,36 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local component = TS.import(script, TS.getModule(script, "@rbxts", "toucan").out).component
+local entityFor = TS.import(script, script.Parent.Parent.Parent, "instance").entityFor
+local EntityList = component("EntityList")
+local function entityList(theme)
+	return entityFor("ScrollingFrame", {
+		Name = "entityList",
+		CanvasSize = UDim2.fromScale(0, 0),
+		AutomaticCanvasSize = Enum.AutomaticSize.Y,
+		ScrollBarThickness = 0,
+		BackgroundColor3 = theme.colors.surface1,
+		BorderColor3 = theme.colors.border,
+		LayoutOrder = 1,
+		callback = function(e)
+			return e:set(EntityList)
+		end,
+		children = { entityFor("UIFlexItem", {
+			FlexMode = Enum.UIFlexMode.Fill,
+		}), entityFor("UIListLayout", {
+			FillDirection = Enum.FillDirection.Vertical,
+			HorizontalFlex = Enum.UIFlexAlignment.Fill,
+			SortOrder = Enum.SortOrder.LayoutOrder,
+			Padding = theme.paddingSizes.medium,
+		}), entityFor("UIPadding", {
+			PaddingLeft = theme.paddingSizes.medium,
+			PaddingRight = theme.paddingSizes.medium,
+			PaddingTop = theme.paddingSizes.large,
+			PaddingBottom = theme.paddingSizes.large,
+		}) },
+	})
+end
+return {
+	default = entityList,
+	EntityList = EntityList,
+}

package/out/ui/explorer/index.d.ts

@@ -0,0 +1,3 @@
+import { type EntityInstance } from '../../instance';
+import type { Theme } from '../../themes';
+export default function explorer(theme: Theme): EntityInstance<Frame>;

package/out/ui/explorer/init.luau

@@ -0,0 +1,22 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local entityFor = TS.import(script, script.Parent.Parent, "instance").entityFor
+local dashboard = TS.import(script, script, "dashboard").default
+local entityList = TS.import(script, script, "entityList").default
+local function explorer(theme)
+	return entityFor("Frame", {
+		Name = "explorer",
+		Size = UDim2.new(1, 0, 1, -35),
+		Transparency = 1,
+		LayoutOrder = 1,
+		children = { entityFor("UIFlexItem", {
+			FlexMode = Enum.UIFlexMode.Fill,
+		}), entityFor("UIListLayout", {
+			HorizontalFlex = Enum.UIFlexAlignment.Fill,
+			SortOrder = Enum.SortOrder.LayoutOrder,
+		}), dashboard(theme), entityList(theme) },
+	})
+end
+return {
+	default = explorer,
+}

package/out/ui/footer.d.ts

@@ -0,0 +1,3 @@
+import { type EntityInstance } from '../instance';
+import type { Theme } from '../themes';
+export default function footer(theme: Theme): EntityInstance<Frame>;

package/out/ui/footer.luau

@@ -0,0 +1,15 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local entityFor = TS.import(script, script.Parent.Parent, "instance").entityFor
+local function footer(theme)
+	return entityFor("Frame", {
+		Name = "footer",
+		Size = UDim2.new(1, 0, 0, 25),
+		BackgroundColor3 = theme.colors.surface1,
+		BorderColor3 = theme.colors.border,
+		LayoutOrder = 2,
+	})
+end
+return {
+	default = footer,
+}

package/out/ui/hero.d.ts

@@ -0,0 +1,3 @@
+import { type EntityInstance } from '../instance';
+import { type Theme } from '../themes';
+export default function hero(theme: Theme): EntityInstance<Frame>;

package/out/ui/hero.luau

@@ -0,0 +1,28 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local entityFor = TS.import(script, script.Parent.Parent, "instance").entityFor
+local ROBLOX_TOPBAR_HEIGHT = TS.import(script, script.Parent.Parent, "themes").ROBLOX_TOPBAR_HEIGHT
+local function hero(theme)
+	return entityFor("Frame", {
+		Name = "hero",
+		Size = UDim2.new(1, 0, 0, ROBLOX_TOPBAR_HEIGHT),
+		BackgroundTransparency = 1,
+		LayoutOrder = 0,
+		children = { entityFor("UIPadding", {
+			PaddingRight = theme.paddingSizes.medium,
+		}), entityFor("TextLabel", {
+			Name = "title",
+			Text = "Toucan",
+			FontFace = theme.fonts.black,
+			Size = UDim2.new(1, 0, 1, 0),
+			TextXAlignment = Enum.TextXAlignment.Right,
+			TextYAlignment = Enum.TextYAlignment.Bottom,
+			TextColor3 = theme.colors.contentInverse,
+			TextSize = theme.fontSizes.huge,
+			BackgroundTransparency = 1,
+		}) },
+	})
+end
+return {
+	default = hero,
+}

package/out/ui/index.d.ts

@@ -0,0 +1,2 @@
+import type { Theme } from '../themes';
+export default function explorerPanel(parent: Instance, theme: Theme): void;

package/out/ui/init.luau

@@ -0,0 +1,29 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local entityFor = TS.import(script, script.Parent, "instance").entityFor
+local explorer = TS.import(script, script, "explorer").default
+local footer = TS.import(script, script, "footer").default
+local hero = TS.import(script, script, "hero").default
+local function explorerPanel(parent, theme)
+	entityFor("ScreenGui", {
+		Name = "toucanExplorer",
+		Parent = parent,
+		IgnoreGuiInset = true,
+		children = { entityFor("Frame", {
+			Name = "panel",
+			Position = UDim2.fromScale(0, 0),
+			Size = UDim2.new(0, 300, 1, 0),
+			BackgroundColor3 = theme.colors.surface2,
+			BorderColor3 = theme.colors.border,
+			BackgroundTransparency = 0.15,
+			children = { entityFor("UIListLayout", {
+				FillDirection = Enum.FillDirection.Vertical,
+				HorizontalFlex = Enum.UIFlexAlignment.Fill,
+				SortOrder = Enum.SortOrder.LayoutOrder,
+			}), hero(theme), explorer(theme), footer(theme) },
+		}) },
+	})
+end
+return {
+	default = explorerPanel,
+}

package/out/updateRuntimeLabel.d.ts

@@ -0,0 +1,2 @@
+export declare const RuntimeLabelFor: import("@rbxts/toucan").Component<undefined>;
+export declare function updateRuntimeLabel(): void;

package/out/updateRuntimeLabel.luau

@@ -0,0 +1,37 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _toucan = TS.import(script, TS.getModule(script, "@rbxts", "toucan").out)
+local Builtin = _toucan.Builtin
+local component = _toucan.component
+local pair = _toucan.pair
+local query = _toucan.query
+local TextLabel = TS.import(script, script.Parent, "instance").TextLabel
+local UPDATE_INTERVAL = 0.5
+local RuntimeLabelFor = component("RuntimeLabelFor")
+local lastRun = 0
+local function formatRuntime(ms)
+	if ms >= 1 then
+		return `{math.round(ms * 10) / 10}ms`
+	end
+	local us = ms * 1000
+	local usRounded = math.round(us * 10) / 10
+	local showDecimal = usRounded < 10
+	return if showDecimal then `{usRounded}µs` else `{math.round(us)}µs`
+end
+local function updateRuntimeLabel()
+	local now = os.clock()
+	-- TODO: use something like `useThrottle` once its plugin gets published.
+	if now - lastRun < UPDATE_INTERVAL then
+		return nil
+	end
+	lastRun = now
+	query(TextLabel):with(pair(RuntimeLabelFor, Builtin.Wildcard)):forEach(function(e, label)
+		local systemEntt = e:targetOf(RuntimeLabelFor)
+		local system = systemEntt:get(Builtin.System)
+		label.Text = formatRuntime(system.runtimeMs)
+	end)
+end
+return {
+	updateRuntimeLabel = updateRuntimeLabel,
+	RuntimeLabelFor = RuntimeLabelFor,
+}

package/package.json

@@ -1,6 +1,40 @@
 {
-  "name": "@rbxts/toucan-debugger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@rbxts/toucan-debugger",
+	"version": "1.0.1",
+	"description": "",
+	"main": "out/init.lua",
+	"scripts": {
+		"setup": "bun i && bun i --cwd test && rokit install",
+		"build": "rbxtsc",
+		"dev": "concurrently -n \"LIB,TEST,ROJO\" -c \"blue,magenta,yellow\" \"rbxtsc -w\" \"rbxtsc -p test -w\" \"rojo serve test/default.project.json\"",
+		"prepublishOnly": "npm run build",
+		"lint": "biome check --write .",
+		"format": "biome format --write .",
+		"predev": "rbxtsc && rbxtsc -p test",
+		"preinstall": "npx only-allow bun"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"type": "commonjs",
+	"types": "out/index.d.ts",
+	"files": [
+		"out",
+		"!**/*.tsbuildinfo"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.0",
+		"@rbxts/compiler-types": "^3.0.0-types.0",
+		"@rbxts/types": "^1.0.959",
+		"concurrently": "^10.0.3",
+		"roblox-ts": "^3.0.0",
+		"typescript": "^5.9.3"
+	},
+	"dependencies": {
+		"@rbxts/services": "^1.6.0",
+		"@rbxts/toucan": "0.6.0"
+	}
+}