@mathiscode/pucc 1.0.0 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Jay Mathis
+
+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,6 +1,16 @@
 # Pucc
 
-Power User Console Component - A browser library that provides a console command system. 
+[![Live Demo](https://img.shields.io/badge/Live%20Demo-rebeccapurple)](https://mathiscode.github.io/pucc/)
+
+[![npm](https://img.shields.io/npm/v/@mathiscode/pucc)](https://www.npmjs.com/package/@mathiscode/pucc)
+[![Created](https://img.shields.io/github/created-at/mathiscode/pucc?style=flat&label=created&color=success)](https://github.com/mathiscode/pucc/pulse)
+[![Star on GitHub](https://img.shields.io/github/stars/mathiscode/pucc?style=flat&logo=github&label=⭐️%20stars)](https://github.com/mathiscode/pucc/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/mathiscode/pucc?style=flat&logo=github&label=🔀%20forks)](https://github.com/mathiscode/pucc/forks)
+[![GitHub watchers](https://img.shields.io/github/watchers/mathiscode/pucc?style=flat&logo=github&label=👀%20watchers)](https://github.com/mathiscode/pucc/watchers)
+[![Sponsors](https://img.shields.io/github/sponsors/mathiscode?color=red&logo=github&label=💖%20sponsors)](https://github.com/sponsors/mathiscode)
+[![Contributors](https://img.shields.io/github/contributors/mathiscode/pucc?color=yellow&logo=github&label=👥%20contributors)](https://github.com/mathiscode/pucc/graphs/contributors)
+
+Power User Console Component - A browser library that provides a console command system.
 
 Register custom commands and execute them via the browser console with a `$` prefix or via the dropdown or embedded terminal Custom Element.
 
@@ -92,40 +102,49 @@ $new customer name="John Smith" balance=5400
 
 ### Module Import (ESM)
 
+When using ESM, no global instance is created automatically. You have full control over how Pucc instances are created and used:
+
 ```javascript
 import { Pucc } from 'pucc';
 
-// When using ESM, no global instance is created automatically
-// You have full control over whether to create a global instance
-// or use terminal-only commands
-
-// Option 1: Create a global instance (like IIFE build)
+// Create a Pucc instance
+// Commands are automatically registered on window (for console access)
 const shell = new Pucc();
-shell.initialize();
-// Now commands are available: $help(), $about()
 
-// Option 2: Create a terminal-only instance
-const shell = new Pucc({ enableGlobalRegistrations: false });
-// Commands only available in terminal elements, not globally
+// Add commands - they're immediately available in console AND terminals
+shell.addCommand('greet', (args) => {
+  console.log(`Hello, ${args._[0] || 'World'}!`);
+}, 'Greet someone');
+
+// Commands are now available:
+// - In browser console: $greet('Alice') or greet('Alice')
+// - In terminal elements: greet Alice
 ```
 
-### Disabling Global Command Registrations
+### Understanding Global Registrations
 
-By default, commands are registered globally on the `window` object, making them accessible from the browser console. If you want to limit command execution to only the terminal element (avoiding global namespace pollution), you can disable global registrations:
+By default, `enableGlobalRegistrations: true` registers commands on the `window` object, making them accessible from the browser console. This does NOT affect terminal access - terminals can use any Pucc instance regardless of this setting.
 
 ```javascript
 import { Pucc } from 'pucc';
 
-// Create a Pucc instance with global registrations disabled
-const shell = new Pucc({ enableGlobalRegistrations: false });
+// Option 1: Commands available in console AND terminals (default)
+const shell = new Pucc();
+shell.addCommand('test', () => console.log('test'), 'Test command');
+// Available as: $test() in console, or "test" in terminals
 
-// Commands will only be available through the terminal
-// They will NOT be accessible via window.$commandName
-shell.addCommand('mycommand', (args) => {
-  console.log('This command is only available in the terminal');
-}, 'A terminal-only command');
+// Option 2: Commands available ONLY in terminals (not in console)
+const shell = new Pucc({ enableGlobalRegistrations: false });
+shell.addCommand('test', () => console.log('test'), 'Test command');
+// Available as: "test" in terminals only (not on window)
 ```
 
+**Key Points:**
+
+- `enableGlobalRegistrations` only controls whether commands appear on `window` (for console access)
+- Terminals can use ANY Pucc instance, regardless of this setting
+- Set to `false` if you want to avoid polluting the global namespace
+
 ### Custom Command Prefix
 
 By default, commands use the `$` prefix (e.g., `$help`, `$about`). You can customize this prefix when creating a Pucc instance:
@@ -166,19 +185,39 @@ shell.addCommand('greet', (args) => {
 
 **Note:** The prefix must be a valid JavaScript identifier (starts with a letter, underscore, or dollar sign; can only contain letters, digits, underscores, and dollar signs). The prefix is used for console commands and is automatically stripped when parsing command input. Commands can always be called with or without the prefix in the terminal.
 
-### Passing Pucc Options to Terminal Element
+### Using Terminal Elements
+
+The `<pucc-terminal>` custom element can use either:
 
-When using the `pucc-terminal` custom element, you can pass Pucc constructor options in two ways:
+1. A shared global instance (`window.Pucc`) - created automatically in IIFE builds
+2. Its own isolated instance - configured via `puccOptions`
+
+**Configuring a Terminal with Its Own Instance:**
 
 **Via attribute (for simple options):**
 
 ```html
 <pucc-terminal 
   embedded="true"
+  height="300px"
+  theme="dark"
+  prompt="# "
+  hotkey="alt+s"
+  initial-content="Welcome to my terminal!"
   pucc-options='{"enableGlobalRegistrations": false, "commandPrefix": "_"}'>
 </pucc-terminal>
 ```
 
+**Terminal Attributes:**
+
+- `embedded` - Set to `"true"` for embedded mode (always visible)
+- `height` - Terminal height (e.g., `"300px"`, `"50vh"`)
+- `theme` - Color theme (`"dark"` or `"light"`)
+- `prompt` - Custom prompt text (default: `"$ "`)
+- `hotkey` - Keyboard shortcut for dropdown terminals (e.g., `"alt+s"`, `"ctrl+shift+t"`)
+- `initial-content` - Custom initial content to display instead of the default welcome message (supports newlines with `\n`)
+- `pucc-options` - JSON string with Pucc constructor options (see below)
+
 **Via property (for full functionality, including functions):**
 
 ```javascript
@@ -204,8 +243,73 @@ terminal.puccOptions = {
 };
 ```
 
+**Adding Commands to a Terminal Element:**
+
+If a terminal uses its own instance (via `puccOptions`), you can add commands to it:
+
+```javascript
+const terminal = document.querySelector('pucc-terminal');
+
+// Get the terminal's Pucc instance
+const shell = terminal.shellInstance;
+
+if (shell) {
+  // Add commands directly to the terminal's instance
+  shell.addCommand('mycommand', (args) => {
+    console.log('Command executed in terminal');
+  }, 'My custom command');
+}
+```
+
+**Using the Global Instance:**
+
+If a terminal doesn't have `puccOptions` set, it automatically uses `window.Pucc` (if available). In this case, commands added to the global instance are available in all terminals:
+
+```javascript
+// In IIFE builds, window.Pucc is created automatically
+// In ESM builds, create it yourself:
+window.Pucc = new Pucc();
+
+// Add commands - they're available in all terminals using the global instance
+shell.addCommand('shared', () => console.log('Shared command'), 'Shared command');
+```
+
 **Note:** The `pucc-options` attribute only supports JSON-serializable options (`enableGlobalRegistrations`, `commandPrefix`). For options that include functions (`customHelpHandler`, `initialCommands`), use the `puccOptions` property instead.
 
+### Customizing Terminal Appearance with CSS
+
+The terminal component supports CSS custom properties for advanced styling:
+
+```css
+pucc-terminal {
+  --shell-bg: #1a1a1a;
+  --shell-fg: #e0e0e0;
+  --shell-accent: #00aaff;
+  --shell-border: rgba(255, 255, 255, 0.1);
+  --shell-font-family: 'Courier New', monospace;
+  --shell-font-size: 16px;
+  --shell-padding: 20px;
+  --shell-animation-duration: 0.3s;
+  --shell-border-radius: 12px;
+  --shell-shadow: 0 12px 48px rgba(0, 0, 0, 0.5);
+  --shell-backdrop-blur: 15px;
+}
+```
+
+**Available CSS Variables:**
+
+- `--shell-bg` - Background color
+- `--shell-fg` - Foreground/text color
+- `--shell-accent` - Accent color (cursor, selection)
+- `--shell-border` - Border color
+- `--shell-font-family` - Font family
+- `--shell-font-size` - Font size
+- `--shell-padding` - Padding
+- `--shell-animation-duration` - Animation duration
+- `--shell-border-radius` - Border radius
+- `--shell-shadow` - Box shadow
+- `--shell-backdrop-blur` - Backdrop blur amount (dropdown terminals only)
+
 ## API Reference
 
 ### `new Pucc(options?)`
@@ -217,42 +321,52 @@ Create a new Pucc instance.
 - `options` (object, optional): Configuration options
   - `customHelpHandler` (function, optional): Custom handler for the `help` command
   - `initialCommands` (Command[], optional): Array of commands to register on initialization
-  - `enableGlobalRegistrations` (boolean, optional): Whether to register commands globally on `window`. Defaults to `true`. Set to `false` to limit commands to the dropdown/embedded terminal only.
-  - `commandPrefix` (string, optional): Custom prefix for console commands. Defaults to `$`. Must be a valid JavaScript identifier (starts with letter, underscore, or dollar sign; can contain letters, digits, underscores, and dollar signs). Commands can be called with or without the prefix.
+  - `enableGlobalRegistrations` (boolean, optional): Whether to register commands globally on `window` for console access. Defaults to `true`. Set to `false` to avoid polluting the global namespace. **Note:** This only affects console access, not terminal access - terminals can use any instance regardless of this setting.
+  - `commandPrefix` (string, optional): Custom prefix for console commands. Defaults to `$`. Must be a valid JavaScript identifier (starts with letter, underscore, or dollar sign; can contain letters, digits, underscores, and dollar signs). Commands can be called with or without the prefix in terminals.
 
 **Example:**
 
 ```javascript
 // Default behavior (global registrations enabled, $ prefix)
 const shell = new Pucc();
+// Commands immediately available in console and terminals
 
-// Disable global registrations
+// Disable global registrations (console access only, terminals still work)
 const shell = new Pucc({ enableGlobalRegistrations: false });
+// Commands available in terminals, NOT in console
 
-// Use custom command prefix (must be a valid JavaScript identifier)
+// Use custom command prefix
 const shell = new Pucc({ commandPrefix: 'cmd_' });
-// Now commands can be called as cmd_help, cmd_about, etc.
+// Console: cmd_help(), Terminal: help or cmd_help
 ```
 
-### `Pucc.addCommand(name, handler, description)`
+### `shell.addCommand(name, handler, description)`
 
-Register a new command.
+Register a new command on a Pucc instance. The command is immediately available in terminals and (if `enableGlobalRegistrations` is true) in the console.
 
 **Parameters:**
 
 - `name` (string): Command name (without prefix)
-- `handler` (function): Command handler function `(args: ParsedArgs) => void | Promise<void>`
-- `description` (string): Command description (shown in `$help`)
+- `handler` (function): Command handler function `(args: ParsedArgs, shell?: Pucc) => void | Promise<void>`
+- `description` (string): Command description (shown in `help`)
 
 **Example:**
 
 ```javascript
-Pucc.addCommand('greet', (args) => {
+const shell = new Pucc();
+
+// Add a command - immediately available
+shell.addCommand('greet', (args) => {
   const name = args.name || args._[0] || 'World';
   console.log(`Hello, ${name}!`);
 }, 'Greet someone by name');
+
+// In console: $greet('Alice') or greet('Alice')
+// In terminal: greet Alice or greet name=Alice
 ```
 
+**Note:** In IIFE builds, you can also use `Pucc.addCommand()` which adds to the global instance automatically created.
+
 ### `ParsedArgs`
 
 The argument object passed to command handlers:
@@ -293,7 +407,7 @@ pnpm type-check
 
 ### Project Structure
 
-```
+```text
 pucc/
 ├── src/
 │   ├── index.ts              # Main entry point
@@ -302,13 +416,31 @@ pucc/
 │   │   └── CommandParser.ts  # Command parser
 │   ├── commands/
 │   │   ├── help.ts           # $help command
-│   │   └── about.ts          # $about command
-│   └── types.ts              # Type definitions
+│   │   ├── about.ts          # $about command
+│   │   └── echo.ts           # $echo command
+│   ├── components/
+│   │   ├── ShellTerminal.ts  # Terminal custom element
+│   │   └── TerminalLogger.ts # Terminal logger component
+│   ├── types.ts              # Type definitions
+│   └── demo.css              # Demo styles
 ├── config/
 │   └── build.js              # Build configuration
-└── dist/                     # Build output
+├── public/                   # Demo and development files
+├── dist/                     # Build output
+├── eslint.config.mts         # ESLint configuration
+├── tsconfig.json             # TypeScript configuration
+└── server.js                 # Development server
 ```
 
 ## License
 
-MIT
+[MIT](LICENSE)
+
+## About the Author
+
+Pucc is created and maintained by [Jay Mathis](https://github.com/mathiscode), a developer passionate about building useful tools for the web.
+
+Connect and explore:
+
+- [GitHub Profile](https://github.com/mathiscode) - Check out my other projects and contributions
+- [Website](https://jaymath.is) - Learn more about me and my work

package/dist/index.html

@@ -20,7 +20,7 @@
           <span>View on GitHub</span>
         </a>
       </div>
-      <p>A browser library that provides a console command system. Register custom commands and execute them via the browser console with a <code>$</code> (configurable) prefix or via the dropdown or embedded terminal Custom Element.</p>
+      <p>A browser library that provides a console command system. Register custom commands and execute them via the browser console with a <code>$</code> (configurable) prefix or via the dropdown or embedded terminal Custom Element (<code>pucc-terminal</code>).</p>
       <br />
       <p>This can be very useful for web apps that need to provide a console for users to interact with the app, bypassing the UI for power users.</p>
     </div>
@@ -139,7 +139,7 @@ about</code></pre>
       <div class="card">
         <h2>Module Import (ESM)</h2>
         <p>When using ESM, no global instance is created automatically. You have full control:</p>
-        <pre><code>import { Pucc } from 'pucc';
+        <pre><code>import { Pucc } from '@mathiscode/pucc';
 
 // Option 1: Create a global instance (like IIFE build)
 const shell = new Pucc();
@@ -154,7 +154,7 @@ const shell = new Pucc({ enableGlobalRegistrations: false });
       <div class="card">
         <h2>Disabling Global Registrations</h2>
         <p>Limit commands to the terminal only (avoiding global namespace pollution):</p>
-        <pre><code>import { Pucc } from 'pucc';
+        <pre><code>import { Pucc } from '@mathiscode/pucc';
 
 const shell = new Pucc({ enableGlobalRegistrations: false });
 
@@ -168,7 +168,7 @@ shell.addCommand('mycommand', (args) => {
       <div class="card">
         <h2>Custom Command Prefix</h2>
         <p>Customize the command prefix (must be a valid JavaScript identifier):</p>
-        <pre><code>import { Pucc } from 'pucc';
+        <pre><code>import { Pucc } from '@mathiscode/pucc';
 
 const shell = new Pucc({ commandPrefix: 'cmd' });
 

package/dist/pucc.esm.js

@@ -1,4 +1,4 @@
-/*! @mathiscode/pucc v1.0.0 */
+/*! @mathiscode/pucc v1.0.1 */
 
 // src/core/CommandParser.ts
 var CommandParser = class {

package/dist/pucc.js

@@ -1,4 +1,4 @@
-/*! @mathiscode/pucc v1.0.0 */
+/*! @mathiscode/pucc v1.0.1 */
 "use strict";
 (() => {
   // src/core/CommandParser.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathiscode/pucc",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "license": "MIT",
   "description": "Power User Console Component - A browser console command system library",
   "author": {