@pie-players/pie-calculator-desmos 0.3.68 → 0.3.70

package/README.md

@@ -1,245 +1,167 @@
 # @pie-players/pie-calculator-desmos
 
-Desmos calculator provider for PIE Players - Premium graphing, scientific, and basic calculators.
+PIE's provider adapter for the Desmos Graphing, Scientific, and Four Function
+Calculator APIs.
 
-## Features
-
-- ✅ Beautiful, intuitive graphing calculators
-- ✅ Interactive expression lists
-- ✅ Scientific and basic calculator modes
-- ✅ State persistence and export
-- ⚠️ Requires Desmos API key from [desmos.com/api](https://www.desmos.com/api)
-- ⚠️ Requires internet connection
+This package contains only PIE-authored adapter code. It does not bundle,
+redistribute, cache, or self-host Desmos's `calculator.js` or other Desmos
+assets. Unless the host has already loaded a build, the provider loads the
+stable v1.12 script directly from `www.desmos.com`.
 
 ## Installation
 
 ```bash
-npm install @pie-players/pie-calculator-desmos
+bun add @pie-players/pie-calculator-desmos
 ```
 
-## How Desmos API Keys Work
-
-According to Desmos documentation, the API key should be included when loading the Desmos calculator library:
-
-```html
-<script src="https://www.desmos.com/api/v1.11/calculator.js?apiKey=YOUR_KEY"></script>
-```
-
-However, **this approach exposes your API key in client-side HTML**, which is a security risk for production applications.
-
-## Security Best Practices
-
-### ⚠️ Important Security Considerations
+## Desmos license and API key
 
-While Desmos's documentation shows the API key embedded in the script URL (client-side), this is **NOT SECURE for production** because:
+Desmos is separately licensed and is not covered by this package's MIT license.
+Obtain a key for the application at [Desmos My API](https://www.desmos.com/my-api)
+and follow the [Desmos API Terms](https://www.desmos.com/api-terms):
 
-1. Anyone can view your HTML source and see the API key
-2. The key can be copied and used by others
-3. You cannot rotate keys without redeploying your entire application
-4. You have no control over who uses your key
+- the free Trial Tier is limited to personal non-commercial use or a 90-day
+  internal evaluation for prospective commercial use;
+- production use by end users and internal business use require the Commercial
+  Tier unless a separate written agreement applies;
+- the key identifies the licensed application and must not be committed to the
+  repository or shared between unrelated applications; and
+- self-hosting is a Desmos partner option, not a general substitute for loading
+  the official CDN script.
 
-### Our Recommended Patterns
+Desmos's documented browser integration requires the key in the
+`calculator.js` URL. A browser user can therefore observe it in the network
+request. Fetching the key at runtime keeps it out of source and static bundles,
+but does not make it a server-only secret.
 
-This package supports three configuration patterns:
+For backwards compatibility, calling `initialize()` with no key still loads the
+historical unkeyed v1.12 URL when `window.Desmos` is absent. Existing clients
+therefore continue to work without new configuration. That technical fallback
+does not grant or imply a Desmos license; the deploying host remains responsible
+for obtaining the rights required for its application.
 
-#### 1. Development Mode (Direct API Key) - Testing Only
+## Provider loading
 
-Use the demo key or your own key for local development:
-
-```html
-<!-- Load Desmos with demo key -->
-<script src="https://www.desmos.com/api/v1.11/calculator.js?apiKey=REDACTED_API_KEY"></script>
-```
+Pass the application key when the licensed deployment should load Desmos from
+its official CDN:
 
 ```typescript
-import { DesmosCalculatorProvider } from '@pie-players/pie-calculator-desmos';
-
-const provider = new DesmosCalculatorProvider();
-await provider.initialize(); // Uses the globally loaded Desmos
-```
-
-⚠️ Only use your real API key like this during development!
-
-#### 2. Production Mode (Server-Side Proxy) - ✅ RECOMMENDED
+import { DesmosCalculatorProvider } from "@pie-players/pie-calculator-desmos";
 
-For production, use a server-side proxy to keep your API key secure:
-
-```typescript
 const provider = new DesmosCalculatorProvider();
 await provider.initialize({
-  proxyEndpoint: '/api/desmos/script-url' // Server returns the script URL with key
+  apiKey: runtimeConfig.desmosApiKey,
 });
 ```
 
-Your server endpoint returns a signed or time-limited URL.
-
-#### 3. Pre-loaded Library (Client-Side)
-
-If you must use client-side loading in production (not recommended), at least load the library yourself and don't pass the key through our package:
+The provider loads:
 
-```html
-<script src="https://www.desmos.com/api/v1.11/calculator.js?apiKey=YOUR_KEY"></script>
-```
-
-```typescript
-const provider = new DesmosCalculatorProvider();
-await provider.initialize(); // No key needed, uses window.Desmos
+```text
+https://www.desmos.com/api/v1.12/calculator.js?apiKey=<application-key>
 ```
 
-**Note**: This still exposes your key in HTML, but at least it's not in your JavaScript bundle.
-
-## Server-Side Proxy Implementation
-
-### Understanding the Challenge
-
-Desmos requires the API key in the script URL when loading the library. To keep your key secure while still working within Desmos's architecture, you need a server-side proxy.
-
-### Option A: Proxy the Desmos Script (Most Secure)
-
-Create a server endpoint that proxies the Desmos calculator script with your API key:
-
-#### Express.js Example
+A host may fetch the key from an authenticated, same-origin endpoint before
+calling `initialize()`. That endpoint should be limited to authorized users,
+rate-limited as appropriate, and returned with `Cache-Control: private,
+no-store`. The key still reaches those users' browsers as required by the
+Desmos API.
 
-```javascript
-// server.js
-app.get('/api/desmos/calculator.js', requireAuth, async (req, res) => {
-  if (!req.user) {
-    return res.status(401).json({ error: 'Unauthorized' });
-  }
+If a Desmos agreement permits the host to preload or self-host the API, load
+that build first and initialize without a key:
 
-  // Fetch Desmos script with your API key server-side
-  const desmosUrl = `https://www.desmos.com/api/v1.11/calculator.js?apiKey=${process.env.DESMOS_API_KEY}`;
-  const response = await fetch(desmosUrl);
-  const script = await response.text();
-
-  res.setHeader('Content-Type', 'application/javascript');
-  res.send(script);
-});
-```
-
-Then load from your proxy in the client:
+```typescript
+if (!window.Desmos) throw new Error("Authorized Desmos API build was not loaded");
 
-```html
-<script src="/api/desmos/calculator.js"></script>
+const provider = new DesmosCalculatorProvider();
+await provider.initialize();
 ```
 
-### Option B: Return Signed/Time-Limited URL
+This package deliberately has no script-proxy or self-hosting option. Do not
+copy or proxy `calculator.js` unless the application's Desmos agreement grants
+that right.
 
-Create temporary, authenticated URLs that expire:
+## Usage
 
-#### Next.js API Route Example
+Import the provider and its owner-defined per-instance configuration from this package:
 
 ```typescript
-// pages/api/desmos/script-url.ts
-import { getServerSession } from 'next-auth';
-import { sign } from 'jsonwebtoken';
-
-export default async function handler(req, res) {
-  const session = await getServerSession(req, res);
-
-  if (!session) {
-    return res.status(401).json({ error: 'Unauthorized' });
-  }
-
-  // Create a time-limited token
-  const token = sign(
-    { userId: session.user.id },
-    process.env.JWT_SECRET,
-    { expiresIn: '1h' }
-  );
-
-  // Return URL with your API key (only valid for this session)
-  res.json({
-    scriptUrl: `https://www.desmos.com/api/v1.11/calculator.js?apiKey=${process.env.DESMOS_API_KEY}`,
-    expiresAt: Date.now() + 3600000
-  });
-}
+import {
+  DesmosCalculatorProvider,
+  type DesmosCalculatorSettings,
+  type DesmosCalculatorProviderConfig,
+} from '@pie-players/pie-calculator-desmos';
 ```
 
-### Advantages of Server-Side Proxy
+`initialize()` takes the shared `CalculatorProviderInit` whole: Desmos is the one
+adapter needing a credential, so it declares no narrower init type of its own.
+`createCalculator()` takes `DesmosCalculatorProviderConfig`, which is the
+provider-neutral configuration with `settings` typed as
+`DesmosCalculatorSettings`. That is what the packaged toolkit composition
+passes.
 
-1. **Security**: API key never exposed to client in retrievable form
-2. **Authentication**: Control who can access Desmos
-3. **Rate Limiting**: Implement usage limits server-side
-4. **Usage Tracking**: Monitor calculator usage for billing
-5. **Key Rotation**: Change keys without redeploying client code
-6. **Compliance**: Meets security requirements for sensitive data
-
-### Reality Check
-
-**Important**: Even with a proxy, if the client loads the Desmos script, a determined user could still inspect network traffic and find the API key embedded in the script content. For true security:
-
-1. Consider if Desmos calculators are necessary for your use case
-2. Use provider-driven fallback strategies when a licensed graphing calculator is not required
-3. Contact Desmos at <partnerships@desmos.com> to discuss enterprise security options
-4. Implement rate limiting and usage monitoring to detect key misuse
-
-## Usage
-
-### Basic Calculator
+### Basic calculator
 
 ```typescript
-const provider = new DesmosCalculatorProvider();
-await provider.initialize({ proxyEndpoint: '/api/desmos/token' });
-
 const calculator = await provider.createCalculator(
-  'basic',
-  document.getElementById('calculator-container')
+  "basic",
+  document.getElementById("calculator-container")!,
 );
 ```
 
-### Scientific Calculator
+### Scientific calculator
 
 ```typescript
 const calculator = await provider.createCalculator(
-  'scientific',
-  document.getElementById('calculator-container'),
+  "scientific",
+  document.getElementById("calculator-container")!,
   {
-    desmos: {
+    settings: {
       degreeMode: true,
-      functionDefinition: true
-    }
-  }
+      functionDefinition: true,
+    },
+  },
 );
 ```
 
-### Graphing Calculator
+### Graphing calculator
 
 ```typescript
 const calculator = await provider.createCalculator(
-  'graphing',
-  document.getElementById('calculator-container'),
+  "graphing",
+  document.getElementById("calculator-container")!,
   {
-    desmos: {
+    settings: {
       expressions: true,
       settingsMenu: true,
       zoomButtons: true,
-      plotInequalities: true
-    }
-  }
+      plotInequalities: true,
+    },
+  },
 );
 ```
 
-### Restricted/Test Mode
-
-For assessments, you can restrict calculator features:
+### Restricted/test mode
 
 ```typescript
-const calculator = await provider.createCalculator(
-  'graphing',
-  container,
-  {
-    restrictedMode: true, // Disables settings, zoom, expressions topbar
-    desmos: {
-      restrictedFunctions: true // Additional Desmos restrictions
-    }
-  }
-);
+const calculator = await provider.createCalculator("graphing", container, {
+  restrictedMode: true,
+  settings: {
+    restrictedFunctions: true,
+  },
+});
 ```
 
-## Configuration Options
+`restrictedMode` is monotonic: it suppresses the expression topbar, the settings
+menu, the zoom buttons and links, it lands after `settings`, and a host cannot
+relax it. It deliberately leaves the expression list alone — that list is a
+`GraphingCalculator`'s only input, and hiding it left graph paper with nothing to
+plot on. A host that wants it gone passes `settings: { expressions: false }` and
+sets the rest itself.
+
+Assessment restrictions and the Desmos API tier are separate concerns. A
+restricted calculator still requires a key licensed for the application.
 
-See the `DesmosCalculatorConfig` interface in `@pie-players/pie-calculator` for all available options.
+See the `DesmosCalculatorSettings` interface exported by `@pie-players/pie-calculator-desmos` for all available options.
 
 Common options:
 
@@ -250,36 +172,21 @@ Common options:
 - `border`: Show calculator border
 - `links`: Enable links to Desmos.com
 
-## State Management
+## State management
 
 Save and restore calculator state:
 
 ```typescript
-// Export state
 const state = calculator.exportState();
-localStorage.setItem('calculator-state', JSON.stringify(state));
+localStorage.setItem("calculator-state", JSON.stringify(state));
 
-// Import state
-const savedState = JSON.parse(localStorage.getItem('calculator-state'));
+const savedState = JSON.parse(localStorage.getItem("calculator-state")!);
 calculator.importState(savedState);
 ```
 
-## Loading Desmos API
-
-The Desmos API must be loaded before initializing the provider. You can load it from CDN:
-
-```html
-<script src="https://www.desmos.com/api/v1.10/calculator.js?apiKey=REDACTED_API_KEY"></script>
-```
-
-Or load it dynamically in your application.
-
-## License
-
-This package is MIT licensed. The Desmos API requires a separate API key from Desmos.
-
 ## Links
 
-- [Desmos API Documentation](https://www.desmos.com/api)
-- [Get Desmos API Key](https://www.desmos.com/api)
+- [Desmos API v1.12 documentation](https://www.desmos.com/api/v1.12/docs/index.html)
+- [Desmos API Terms](https://www.desmos.com/api-terms)
+- [Desmos My API](https://www.desmos.com/my-api)
 - [PIE Calculator Base Package](https://www.npmjs.com/package/@pie-players/pie-calculator)

package/dist/desmos-provider.d.ts

@@ -4,20 +4,54 @@
  *
  * Supports: Basic, Scientific, and Graphing calculators
  * Based on Desmos API v1.12+
- * Requires: Desmos API key (obtain from https://www.desmos.com/api)
+ * Requires: A Desmos API key when this provider loads the API from desmos.com
  *
- * SECURITY BEST PRACTICE:
- * - Development: Pass apiKey directly for local testing
- * - Production: Use proxyEndpoint to keep API key server-side
+ * Desmos's documented browser integration places the key in the calculator.js
+ * URL. A runtime credential endpoint can keep the key out of source and static
+ * bundles, but cannot keep it secret from a browser that loads the API.
+ */
+import type { Calculator, CalculatorProvider, CalculatorProviderCapabilities, CalculatorProviderConfig, CalculatorProviderInit, CalculatorType } from "@pie-players/pie-calculator";
+/** Desmos API options accepted through `CalculatorProviderConfig.settings`. */
+export interface DesmosCalculatorSettings extends Record<string, unknown> {
+    border?: boolean;
+    degreeMode?: boolean | "degree" | "radian";
+    decimalToFraction?: boolean;
+    links?: boolean;
+    settingsMenu?: boolean;
+    expressions?: boolean;
+    zoomButtons?: boolean;
+    expressionsTopbar?: boolean;
+    notes?: boolean;
+    folders?: boolean;
+    images?: boolean;
+    qwertyKeyboard?: boolean;
+    restrictedFunctions?: boolean;
+    plotSingleVariableImplicitEquations?: boolean;
+    distributions?: boolean;
+    plotImplicits?: boolean;
+    plotInequalities?: boolean;
+    geometryComputationFunctions?: boolean;
+    sliders?: boolean;
+    tables?: boolean;
+    expressionsCollapsed?: boolean;
+    administerSecretFolders?: boolean;
+    lockViewport?: boolean;
+    functionDefinition?: boolean;
+    brailleExpressionDownload?: boolean;
+    keypad?: boolean;
+    graphpaper?: boolean;
+    additionalFunctions?: string | string[];
+}
+/**
+ * Per-instance configuration accepted by the Desmos calculator provider.
  *
- * Example server-side proxy (Express.js):
- * ```
- * app.get('/api/desmos/token', requireAuth, (req, res) => {
- *   res.json({ apiKey: process.env.DESMOS_API_KEY });
- * });
- * ```
+ * Identical to the provider-neutral shape apart from naming what `settings`
+ * holds, which the neutral seam deliberately leaves as `Record<string,
+ * unknown>`.
  */
-import type { Calculator, CalculatorProvider, CalculatorProviderCapabilities, CalculatorProviderConfig, CalculatorType } from "@pie-players/pie-calculator";
+export interface DesmosCalculatorProviderConfig extends Omit<CalculatorProviderConfig, "settings"> {
+    settings?: DesmosCalculatorSettings;
+}
 declare global {
     interface Window {
         Desmos?: any;
@@ -33,33 +67,20 @@ export declare class DesmosCalculatorProvider implements CalculatorProvider {
     readonly version = "1.12";
     private initialized;
     private apiKey?;
-    private proxyEndpoint?;
-    private isDevelopment;
+    private readonly instances;
     private onTelemetry;
     private emitTelemetry;
-    /**
-     * Get the configured API key
-     * @internal Used internally by calculator instances
-     */
-    getApiKey(): string | undefined;
     /**
      * Dynamically load the Desmos calculator library
      * @private
      */
     private loadDesmosScript;
-    /**
-     * Initialize Desmos library
-     * @param config Configuration with API key (development) or proxy endpoint (production)
-     */
-    initialize(config?: {
-        apiKey?: string;
-        proxyEndpoint?: string;
-        onTelemetry?: (eventName: string, payload?: Record<string, unknown>) => void | Promise<void>;
-    }): Promise<void>;
+    /** Initialize Desmos with provider-level credentials and instrumentation. */
+    initialize(config?: CalculatorProviderInit): Promise<void>;
     /**
      * Create a calculator instance
      */
-    createCalculator(type: CalculatorType, container: HTMLElement, config?: CalculatorProviderConfig): Promise<Calculator>;
+    createCalculator(type: CalculatorType, container: HTMLElement, config?: DesmosCalculatorProviderConfig): Promise<Calculator>;
     /**
      * Check if type is supported
      */

package/dist/desmos-provider.js

@@ -4,18 +4,11 @@
  *
  * Supports: Basic, Scientific, and Graphing calculators
  * Based on Desmos API v1.12+
- * Requires: Desmos API key (obtain from https://www.desmos.com/api)
+ * Requires: A Desmos API key when this provider loads the API from desmos.com
  *
- * SECURITY BEST PRACTICE:
- * - Development: Pass apiKey directly for local testing
- * - Production: Use proxyEndpoint to keep API key server-side
- *
- * Example server-side proxy (Express.js):
- * ```
- * app.get('/api/desmos/token', requireAuth, (req, res) => {
- *   res.json({ apiKey: process.env.DESMOS_API_KEY });
- * });
- * ```
+ * Desmos's documented browser integration places the key in the calculator.js
+ * URL. A runtime credential endpoint can keep the key out of source and static
+ * bundles, but cannot keep it secret from a browser that loads the API.
  */
 /**
  * Desmos Calculator Provider Implementation
@@ -31,8 +24,16 @@ export class DesmosCalculatorProvider {
     version = "1.12";
     initialized = false;
     apiKey;
-    proxyEndpoint;
-    isDevelopment = false;
+    /*
+     * Every calculator this provider handed out and that has not destroyed itself.
+     *
+     * `destroy()` is a host's one call to release the provider, and without this it
+     * released only the provider's own fields: every calculator it created stayed
+     * mounted, with its vendor instance alive and its container populated. A host
+     * that swaps providers, or tears a section down without walking its calculators
+     * first, leaked all of them.
+     */
+    instances = new Set();
     onTelemetry;
     async emitTelemetry(eventName, payload) {
         try {
@@ -42,29 +43,20 @@ export class DesmosCalculatorProvider {
             console.warn("[DesmosProvider] telemetry callback failed:", error);
         }
     }
-    /**
-     * Get the configured API key
-     * @internal Used internally by calculator instances
-     */
-    getApiKey() {
-        return this.apiKey;
-    }
     /**
      * Dynamically load the Desmos calculator library
      * @private
      */
-    async loadDesmosScript() {
+    async loadDesmosScript(apiKey) {
         return new Promise((resolve, reject) => {
             const script = document.createElement("script");
-            // Include API key in script URL if available
-            const scriptUrl = this.apiKey
-                ? `https://www.desmos.com/api/v1.12/calculator.js?apiKey=${this.apiKey}`
-                : "https://www.desmos.com/api/v1.12/calculator.js";
-            script.src = scriptUrl;
+            const scriptUrl = new URL("https://www.desmos.com/api/v1.12/calculator.js");
+            if (apiKey)
+                scriptUrl.searchParams.set("apiKey", apiKey);
+            script.src = scriptUrl.toString();
             script.async = true;
             script.onload = () => {
                 if (window.Desmos) {
-                    console.log("[DesmosProvider] Desmos API loaded successfully");
                     resolve();
                 }
                 else {
@@ -77,11 +69,8 @@ export class DesmosCalculatorProvider {
             document.head.appendChild(script);
         });
     }
-    /**
-     * Initialize Desmos library
-     * @param config Configuration with API key (development) or proxy endpoint (production)
-     */
-    async initialize(config) {
+    /** Initialize Desmos with provider-level credentials and instrumentation. */
+    async initialize(config = {}) {
         if (this.initialized)
             return;
         this.onTelemetry = config?.onTelemetry;
@@ -89,15 +78,9 @@ export class DesmosCalculatorProvider {
         if (typeof window === "undefined") {
             throw new Error("Desmos calculators can only be initialized in the browser");
         }
-        // Determine if we're in development mode
-        this.isDevelopment =
-            process.env.NODE_ENV === "development" ||
-                typeof process === "undefined" ||
-                !process.env.NODE_ENV;
-        // Configure API access pattern
-        if (config?.proxyEndpoint) {
-            // Production pattern: server-side proxy
-            this.proxyEndpoint = config.proxyEndpoint;
+        this.apiKey = config.apiKey?.trim() || undefined;
+        const proxyEndpoint = config.proxyEndpoint?.trim();
+        if (proxyEndpoint) {
             const authStartedAt = Date.now();
             await this.emitTelemetry("pie-tool-backend-call-start", {
                 toolId: "calculator",
@@ -105,19 +88,21 @@ export class DesmosCalculatorProvider {
                 operation: "proxy-auth-fetch",
             });
             try {
-                const response = await fetch(config.proxyEndpoint);
+                const response = await fetch(proxyEndpoint);
                 if (!response.ok) {
-                    throw new Error(`Proxy endpoint returned ${response.status}`);
+                    throw new Error(`Runtime endpoint returned ${response.status}`);
                 }
-                const data = await response.json();
-                this.apiKey = data.apiKey;
+                const body = (await response.json());
+                if (typeof body.apiKey !== "string" || !body.apiKey.trim()) {
+                    throw new Error("Runtime endpoint did not return a non-empty apiKey");
+                }
+                this.apiKey = body.apiKey.trim();
                 await this.emitTelemetry("pie-tool-backend-call-success", {
                     toolId: "calculator",
                     backend: "desmos",
                     operation: "proxy-auth-fetch",
                     duration: Date.now() - authStartedAt,
                 });
-                console.log("[DesmosProvider] Initialized with server-side proxy (SECURE)");
             }
             catch (error) {
                 await this.emitTelemetry("pie-tool-backend-call-error", {
@@ -128,31 +113,14 @@ export class DesmosCalculatorProvider {
                     errorType: "CalculatorProxyAuthError",
                     message: error instanceof Error ? error.message : String(error),
                 });
-                throw new Error(`[DesmosProvider] Failed to fetch API key from proxy: ${error}`);
-            }
-        }
-        else if (config?.apiKey) {
-            // Development pattern: direct API key
-            this.apiKey = config.apiKey;
-            // Security warning in production
-            if (!this.isDevelopment) {
-                console.error("⚠️ [DesmosProvider] SECURITY WARNING: API key exposed in client-side code!\n" +
-                    "This is insecure for production. Use proxyEndpoint instead.\n" +
-                    "See: https://pie-players.dev/docs/calculator-desmos#security");
-            }
-            else {
-                console.log("[DesmosProvider] Initialized with direct API key (DEVELOPMENT MODE)");
+                throw new Error(`[DesmosProvider] Failed to fetch API key from runtime endpoint: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
-        else {
-            // No API key provided
-            console.warn("[DesmosProvider] No API key or proxy endpoint provided.\n" +
-                "Production usage requires authentication. Obtain API key from https://www.desmos.com/api\n" +
-                "Recommended: Use proxyEndpoint for production, apiKey for development only.");
-        }
         // Load Desmos API if not already loaded
         if (!window.Desmos) {
-            console.log("[DesmosProvider] Loading Desmos API library...");
+            if (!this.apiKey) {
+                console.warn("[DesmosProvider] Loading the legacy unkeyed Desmos URL for compatibility. Configure an application API key for licensed deployments.");
+            }
             const libraryLoadStartedAt = Date.now();
             await this.emitTelemetry("pie-tool-library-load-start", {
                 toolId: "calculator",
@@ -160,7 +128,7 @@ export class DesmosCalculatorProvider {
                 operation: "desmos-script-load",
             });
             try {
-                await this.loadDesmosScript();
+                await this.loadDesmosScript(this.apiKey);
                 await this.emitTelemetry("pie-tool-library-load-success", {
                     toolId: "calculator",
                     backend: "desmos",
@@ -192,7 +160,9 @@ export class DesmosCalculatorProvider {
         if (!this.supportsType(type)) {
             throw new Error(`Desmos does not support calculator type: ${type}`);
         }
-        return new DesmosCalculator(this, type, container, config, this.apiKey);
+        const calculator = new DesmosCalculator(this, type, container, config, () => this.instances.delete(calculator));
+        this.instances.add(calculator);
+        return calculator;
     }
     /**
      * Check if type is supported
@@ -204,7 +174,12 @@ export class DesmosCalculatorProvider {
      * Cleanup
      */
     destroy() {
+        // A copy: each `destroy()` calls back to remove itself from the set.
+        for (const instance of [...this.instances])
+            instance.destroy();
+        this.instances.clear();
         this.initialized = false;
+        this.apiKey = undefined;
         this.onTelemetry = undefined;
     }
     /**
@@ -221,16 +196,32 @@ export class DesmosCalculatorProvider {
         };
     }
 }
+/**
+ * Credentials are provider-level (`initialize()`), never per-instance options.
+ *
+ * `DesmosCalculatorSettings` carries an index signature, so `settings` still
+ * *accepts* both names from a caller that has not moved them yet. Desmos treats
+ * an unknown option as an error, and a key there reaches nothing that would use
+ * it, so both are dropped before `settings` reaches the vendor constructor.
+ */
+const CREDENTIAL_KEYS = ["apiKey", "proxyEndpoint"];
+function stripCredentialKeys(config) {
+    for (const key of CREDENTIAL_KEYS)
+        delete config[key];
+}
 /**
  * Desmos Calculator Instance
  */
 class DesmosCalculator {
+    onDestroy;
     provider;
     type;
     Desmos;
     calculator;
     container;
-    constructor(provider, type, container, config, apiKey) {
+    destroyed = false;
+    constructor(provider, type, container, config, onDestroy) {
+        this.onDestroy = onDestroy;
         this.provider = provider;
         this.type = type;
         this.container = container;
@@ -238,21 +229,41 @@ class DesmosCalculator {
         if (!this.Desmos) {
             throw new Error("Desmos API not available");
         }
-        this._initializeCalculator(config, apiKey);
+        this._initializeCalculator(config);
     }
-    _initializeCalculator(config, apiKey) {
-        // Merge Desmos-specific config with defaults
+    _initializeCalculator(config) {
+        const isGraphing = this.type === "graphing";
         const desmosConfig = {
-            ...(config?.desmos || {}),
-            apiKey: apiKey || config?.desmos?.apiKey,
+            degreeMode: true,
+            settingsMenu: isGraphing,
+            qwertyKeyboard: false,
+            notes: isGraphing,
+            folders: isGraphing,
+            sliders: isGraphing,
+            tables: isGraphing,
+            ...(config?.settings || {}),
         };
-        // Apply restricted mode if specified
+        stripCredentialKeys(desmosConfig);
+        /*
+         * Restricted mode is monotonic: it lands after the host's own `settings` and a
+         * host cannot relax it, which is the same contract the Cortex adapter states
+         * for its own flag. It suppresses chrome a learner has no use for mid-item and
+         * routes out of the tool.
+         *
+         * `expressions: false` is deliberately not among them. It removes the whole
+         * expression list, which on a `GraphingCalculator` is the only way to enter a
+         * function, so a restricted graphing calculator was graph paper with nothing to
+         * plot on it — the call this package's own README documents. Basic and
+         * scientific never noticed: `expressions` is a graphing option their
+         * constructors ignore. A host that does want the list gone passes
+         * `settings: { expressions: false }` and sets the flags below itself, since
+         * those are honoured whenever `restrictedMode` is not what overrides them.
+         */
         if (config?.restrictedMode) {
             Object.assign(desmosConfig, {
                 expressionsTopbar: false,
                 settingsMenu: false,
                 zoomButtons: false,
-                expressions: false,
                 links: false,
             });
         }
@@ -270,7 +281,6 @@ class DesmosCalculator {
             default:
                 throw new Error(`Unsupported calculator type: ${this.type}`);
         }
-        console.log(`[DesmosCalculator] Created ${this.type} calculator`);
     }
     getValue() {
         // For graphing calculator, get the state
@@ -361,10 +371,13 @@ class DesmosCalculator {
         }
     }
     destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
         if (this.calculator && this.calculator.destroy) {
             this.calculator.destroy();
         }
         this.container.replaceChildren();
-        console.log("[DesmosCalculator] destroyed");
+        this.onDestroy();
     }
 }

package/dist/index.d.ts

@@ -4,3 +4,4 @@
  * Desmos calculator provider - High-quality graphing calculators.
  */
 export { DesmosCalculatorProvider } from "./desmos-provider.js";
+export type { DesmosCalculatorProviderConfig, DesmosCalculatorSettings, } from "./desmos-provider.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-calculator-desmos",
-	"version": "0.3.68",
+	"version": "0.3.70",
 	"description": "Desmos calculator provider for PIE Assessment Toolkit - High-quality graphing calculators",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -17,6 +17,7 @@
 	],
 	"scripts": {
 		"build": "tsc",
+		"test": "bun test tests",
 		"typecheck": "tsc --noEmit"
 	},
 	"keywords": [
@@ -38,7 +39,7 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@pie-players/pie-calculator": "0.3.68"
+		"@pie-players/pie-calculator": "0.3.70"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3"