.inspatialdocrules

MUST ALWAYS use js doc documentation where every instance of a generated code snippet assumes the user doesn't know anything about anything, and therefore explains everything like a beginner. 

IMPORTANT: MUST NOT complicate itself with buzzwords or tech jargon and MUST read naturally. 

IMPORTANT: MUST include correct indentations, markdown elements for visual cohesion like reading a blog, where the core function MUST ALWAYS be highlighted by the biggest heading, followed by a succinct descriptive one-line summary as a subheading, before getting to the main explanation.

IMPORTANT: The documentation must be consistent and well-formatted.  

IMPORTANT: If a kind of symbol e.g (class, constant, event, external, file, function, memeber, mixin, module, namespace, typedef etc...) or code warrants an explanation not inclusive of the base or core definition then highlight that explanation on `NOTE:...`, also if there's a buzzword or word that deviates from the path of simplicity (if for any reason has to) e.g an industry term or something along those lines then highlight the word or words in `Terminology: ...` explaining and breaking the term from first principles like a beginner.

IMPORTANT: When the documentation refers to another symbol within/outside the package, library or project then make it easy for users to navigate throughout the docs, by linking using appropraite linking tags e.g @link, @linkcode, @linkplain and @tutorial.

IMPORTANT: Use tags like @param, @returns, @throws and @typeParam to provide more information about specific parts of the symbol.

IMPORTANT: Provide good type information

IMPORTANT: ALWAYS document every symbol in the package, library or project exports, i.e class, constant, event, external, file, function, memeber, mixin, module, namespace, typedef etc.... For classes and interfaces for example, you should document the symbol itself, each method or property on it, including constructors

**InSpatial Core Packages**
- @inspatial/util
- @inspatial/xr
- @inspatial/kit
- @inspatial/run
- @inspatial/cache
- @inspatial/env
- @inspatial/router
- @inspatial/server
- @inspatial/ecs
- @inspatial/iss
- @inspatial/tw
- @inspatial/theme
- @inspatial/cli
- @inspatial/test
- @inspatial/vfx
- @inspatial/icon
- @inspatial/inmoji
- @inspatial/kv
- @inspatial/db
- @inspatial/cms
- @inspatial/orm
- @inspatial/auth
- @inspatial/vault
- @inspatial/ratelimit
- @inspatial/infetch
- @inspatial/cron
- @inspatial/live
- @inspatial/deploy

**Heading Section**
- MUST be the symbol name 
- MUST always start with a capital letter
- MUST start  with a demonstrative pronoun or determiner or definite article e.g (This or the) and then followed by an appropriate or optional verb followed by the name (symbol name)

**Subheading Section**
- MUST be a one-line summary of what the symbol does
- MUST be a clear, concise and descriptive summary of what the symbol does

**Explanation Section**
- MUST explain the symbol's purpose and functionality
- MUST use everyday language and real-world comparisons
- MUST follow a logical progression from simple to complex concepts
- MUST avoid technical jargon unless necessary (use Terminology section for technical terms)
- Prefer 50 - 100 words for basic operations (e.g., simple calculations, single transformations)
    - Structure:
    1. One-sentence summary
    2. Real-world analogy
    3. Basic usage explanation
    4. Common use case
- Prefer 150 - 300 words for operations with multiple steps or configurations
    - Structure:
    1. Summary paragraph
    2. Extended analogy
    3. Key features explanation
    4. Common scenarios
    5. Basic considerations
- Prefer 400 - 1000 words for advanced operations, algorithms, or systems
    - Structure:
    1. Executive summary
    2. Detailed analogy
    3. Core concept breakdown
    4. Feature explanations
    5. Usage scenarios
    6. Important considerations
    7. Common pitfalls
    8. Best practices

**Category Name - @category (required)**
- The category name is the name of the InSpatial core package, library or project that the symbol belongs to e.g if @inspatial/util category name will be InSpatial Util. 

**Access - @access (required)**
- Defaults to public

**When the feature was added - @since (required)**
- check the current working directory where the symbol is defined for a deno.json or package.json to the current version of the package and apply the correct version. 
- Use the version checker utility {@linkcode getPackageVersion} from @inspatial/util/getPackageVersion to fetch the version from your project files.

**Examples Section**
- MUST include minimum 2 examples for every symbol
- For moderately complex symbols: up to 5 examples
- For complex symbols: up to 10 examples
  - Complexity is determined by:
    - Number of parameters
    - Different possible configurations
    - Edge cases to cover
    - Common usage patterns
- MUST be relatable, concise and demonstrate the most common use cases
- MUST have a clear purpose, use real-life analogies and scenarios
- MUST use TypeScript by default for better type safety

**Import Pattern Requirement**
- MUST use direct file imports for better tree shaking
  ```typescript
  // ✅ Recommended: Direct file import
  import { functionName } from '@inspatial/package/function.ts';
  
  // ❌ Avoid: Package-level import
  import { functionName } from '@inspatial/package';
  ```

**Performance Section**
- Add a performance section if the symbol is performance critical
- Focuse on practical optimizations

IMPORTANT: Prefer this visual hierarchy and template whenever possible.
/**
 * # FunctionName (preferably a verb starts with a capital letter)
 * @summary #### clear, one-line description of what this does
 * 
 * The `FunctionName`. Think of it like [insert real-world analogy].
 * The explanation continues with natural, conversational language that anyone can understand.
 * 
 * @since ${await getPackageVersion()}   // Automatically detected from deno.json/package.json
 * @category CategoryName
 * @module ModuleName
 * @kind <kindName>
 * @access <package|private|protected|public>
 * 
 * ### 💡 Core Concepts
 * - Explain the main ideas behind this function
 * - Break down complex ideas into simple terms
 * - Use everyday analogies where possible
 * 
 * {@tutorial core-concepts-deep-dive} // Deep dive into the core concepts
 *
 * ### 🎯 Prerequisites
 * Before you start:
 * - What you need to know
 * - What should be set up
 * - Any dependencies required
 * 
 * ### 📚 Terminology
 * > **Term1**: Here's what this means in simple words...
 * > **Term2**: Another technical term explained simply...
 * 
 * ### ⚠️ Important Notes
 * <details>
 * <summary>Click to learn more about edge cases</summary>
 * 
 * > [!NOTE]
 * > Important information about specific scenarios
 * 
 * > [!NOTE]
 * > Additional considerations to keep in mind
 * </details>
 * 
 * ### 📝 Type Definitions
 * ```typescript
 * interface TypeName {
 *   property: string;  // Explain what this property is for
 *   optional?: number; // Explain when this might be needed
 * }
 * ```
 * {@tutorial working-with-types} // Guide to using types effectively
 * 
 * @param {Type} paramName - Start with a verb (e.g., "Stores", "Calculates", "Finds")
 *    Continued explanation with real-world examples.
 *    Can span multiple lines for clarity.
 * 
 * @typeParam T - If using generics, explain like teaching a newcomer
 * 
 * ### 🎮 Usage
 * #### Installation
 * ```bash
 * # Deno
 * deno add jsr:@inspatial/package-name
 * ```
 * {@tutorial installation-and-setup} // Complete setup guide
 *
 * ####  Examples
 * Here's how you might use this in real life:
 * 
 * @example
 * ### Example 1: Your First Shopping Cart
 * ```typescript
 * // Let's create a simple shopping list, just like you would at a grocery store
 * const groceries = [
 *   { name: "Bread", price: 3 },    // A loaf of bread
 *   { name: "Milk", price: 4 }      // A carton of milk
 * ];
 * 
 * // Now, let's calculate how much you need to pay
 * const totalCost = functionName(groceries);
 * 
 * // The function adds it up for you: $3 + $4 = $7
 * console.log(`Your total is: ${totalCost}`); // Output: Your total is: $7
 * 
 * // Want to know the total with tax included? Just like at a real store!
 * const totalWithTax = functionName(groceries, { includeTax: true });
 * console.log(`Total with tax: ${totalWithTax}`); // Output: Total with tax: $7.70
 * ```
 * 
 * @example
 * ### Example 2: Handling Special Cases
 * ```typescript
 * // Sometimes your shopping cart might be empty
 * // (like when you realize you forgot your shopping list at home!)
 * const emptyCart = [];
 * const emptyTotal = functionName(emptyCart);
 * console.log(emptyTotal); // Output: 0 (No items = no cost)
 * 
 * // Or maybe some items have pricing errors
 * // (like when the price tag is missing or damaged)
 * const itemsWithProblems = [
 *   { name: "Apple", price: 1 },        // This price is fine
 *   { name: "Orange", price: null },    // Oops, missing price tag!
 *   { name: "Banana", price: -2 }       // Wait, negative price? That's not right!
 * ];
 * 
 * // Don't worry! The function handles these problems gracefully
 * const validTotal = functionName(itemsWithProblems);
 * console.log(`Total for valid items: ${validTotal}`); // Output: Total for valid items: $1
 * ```
 * 
 * @example
 * ### Example 3: Planning a Birthday Party 🎉
 * ```typescript
 * // Let's calculate party supplies with some special discounts
 * const partySupplies = [
 *   { name: "Birthday Cake", price: 30 },   // Every party needs a cake!
 *   { name: "Balloons", price: 10 },        // A bunch of colorful balloons
 *   { name: "Party Hats", price: 15 }       // Fun party hats for everyone
 * ];
 * 
 * // Let's make it a special deal with:
 * // - 20% birthday discount
 * // - Prices rounded to make it easier to handle cash
 * // - Show prices in your local currency
 * const partyOptions = {
 *   currency: "USD",               // Using US dollars
 *   discount: 0.2,                // 20% birthday discount
 *   roundToNearest: 1             // Round to nearest dollar
 * };
 * 
 * const partyTotal = functionName(partySupplies, partyOptions);
 * 
 * // The function does all the math for you:
 * // 1. Adds up all items: $30 + $10 + $15 = $55
 * // 2. Applies 20% discount: $55 - (55 × 20%) = $44
 * console.log(`Party total with birthday discount: ${partyTotal}`);
 * // Output: Party total with birthday discount: $44
 * ```
 * 
 * ### ⚡ Performance Tips (if applicable)
 * <details>
 * <summary>Click to learn about performance</summary>
 * 
 * - Best practices for optimal performance
 * - When to use alternatives
 * - Resource usage considerations
 * </details>
 * 
 * {@tutorial performance-optimization} // Comprehensive performance guide
 * 
 * ### ❌ Common Mistakes
 * <details>
 * <summary>Click to see what to avoid</summary>
 * 
 * - Mistake 1: What not to do and why
 * - Mistake 2: Common pitfall and how to avoid it
 * </details>
 * 
 * {@tutorial troubleshooting} // Common problems and solutions
 * 
 * @throws {ErrorType}
 * Explains when and why errors might occur in plain language.
 * For example: "This will show an error if you try to check out with an empty cart"
 * 
 * @returns {ReturnType}
 * Explains what you get back, using real-world analogies.
 * For example: "You'll get back a receipt with all your items and the total"
 * 
 * ### 🔧 Runtime Support
 * - ✅ Node.js
 * - ✅ Deno
 * - ✅ Bun
 * 
 * {@tutorial understanding-runtime} // Runtime guides
 * 
 * ### ♿ Accessibility (if applicable)
 * <details>
 * <summary>Click to see accessibility features</summary>
 * 
 * - Considerations for screen readers
 * - Keyboard navigation support
 * - ARIA attributes (if applicable)
 * - Color contrast guidelines
 * </details>
 * 
 * {@tutorial accessibility-best-practices} // Complete accessibility guide
 * 
 * ### 🔄 Migration Guide (if applicable)
 * <details>
 * <summary>Click to see version changes</summary>
 * 
 * If you're upgrading from an older version:
 * - What's changed
 * - How to update your code
 * - Breaking changes
 * </details>
 * 
 * {@tutorial migration-walkthrough} // Step-by-step migration guide
 * 
 * ### 🔗 Related Resources (if applicable)
 * 
 * #### Internal References
 * - {@link OtherFunction} - Here's how this relates to what you're looking at
 * - {@linkcode RelatedClass} - Another helpful tool you might want to use
 * 
 * #### External Resources
 * 
 * @external GitHub
 * {@link https://github.com/inspatiallabs/inspatial-core GitHub Repository}
 * Source code and issue tracking 
 * 
 * #### Community Resources
 * @external Discord
 * {@link https://discord.gg/inspatiallabs Discord Community}
 * Join our community for support and discussions
 * 
 * @external Twitter
 * {@link https://x.com/inspatiallabs Twitter}
 * Follow us for updates and announcements
 * 
 * @external LinkedIn
 * {@link https://www.linkedin.com/company/inspatiallabs LinkedIn}
 * Follow us for updates and announcements
 */

// The actual implementation would go here
<kindName> name ...