npm - @webspellchecker/wproofreader-learnosity - Versions diffs - 1.2.1 - Mend

@webspellchecker/wproofreader-learnosity 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/CHANGELOG.md +49 -0
package/LICENSE +190 -0
package/README.md +172 -0
package/dist/wproofreader-learnosity.min.js +2 -0
package/package.json +50 -0
package/src/index.d.ts +106 -0
package/src/index.js +502 -0

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,49 @@
+# Changelog
+All notable changes to `@webspellchecker/wproofreader-learnosity`.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+## [1.2.1]
+### Features
+- **Published to npm.** `@webspellchecker/wproofreader-learnosity` is now available on the public npm registry. v1.2.1 is functionally identical to v1.2.0; the bump exists to mark the npm publication event so the jsDelivr URL documented in the README resolves.
+## [1.2.0]
+### Features
+- **Two install paths.** Existing ESM via npm, plus a new IIFE bundle (`dist/wproofreader-learnosity.min.js`) served from jsDelivr, exposing `window.LearnosityWProofreader.init` for host apps that load the connector via a `<script>` tag (PHP, Python, Java, ASP.NET, Ruby, classic HTML). About 5 KB minified, no runtime dependencies. Built with esbuild via `npm run build`; produced automatically at `npm publish` time via the `prepack` hook.
+## [1.1.0]
+### Features
+- **Self-hosted WProofreader support.** `init()` accepts self-hosted service options (`serviceProtocol`, `serviceHost`, `servicePort`, `servicePath`) under the `wproofreader` block instead of (or alongside) `serviceId`, so customers running the WProofreader Server on their own infrastructure (Docker, Helm, on-prem) integrate without a Cloud service ID. Either `wproofreader.serviceId` or `wproofreader.serviceHost` activates `init()`.
+## [1.0.0]
+Initial public release.
+### Features
+- **Drop-in initialisation.** A single `LearnosityWProofreader.init({ wproofreader: { serviceId } })` call from a host app is enough to start proofreading inside Learnosity widgets. Idempotent: subsequent calls update the live configuration.
+- **ESM npm package.** Default export imported as `import LearnosityWProofreader from '@webspellchecker/wproofreader-learnosity'`; the call site mirrors the import shape.
+- **All three Learnosity APIs supported.** Questions API (`longtextV2` rich-text responses), Author API (every rich-text field across the authoring UI), and Items API (`assess` rendering type).
+- **Two-tier options.** WProofreader runtime options live under a nested `wproofreader` block and are forwarded to WProofreader unchanged (including unknown future options); connector-only fields (`surfaces`, `enableShorttext`, `customSelectors`, `bundleUrl`) live at the top level. The two groups never collide.
+- **Per-editor surface filter.** The `surfaces` option (default `['author']`) walks each editor's ancestry to detect which Learnosity API placed it (`lrn-author*` → Author, `lrn_player*` → Items, otherwise → Questions) and skips editors whose surface is not allowed. Multi-API pages are handled correctly. Opt in to assessment proofreading explicitly with `['questions', 'items', 'author']`.
+- **Assessment-safe default.** The default `surfaces: ['author']` keeps proofreading off in student-facing assessments unless the host app derives an explicit opt-in from server-side activity metadata.
+- **Locale-aware default.** `wproofreader.lang` reads from the host page's `<html lang>` (with `-` normalised to `_`), so a French page proofreads in French without extra config. Falls back to `en_US` when the page does not set a `lang` or sets a bare un-regioned one like `en`.
+- **TypeScript definitions** at `src/index.d.ts`, exposed via `package.json` `types` and `exports.types`. `WProofreaderOptions` has an `[other: string]: unknown` index signature so unknown WProofreader options still type-check.
+- **Lifecycle cleanup.** A scoped `MutationObserver` watches for editors appearing and disappearing. WProofreader instances are destroyed when their host elements leave the DOM, so single-page-app hosts that rebuild Learnosity widgets do not leak instances.
+- **Targeted attachment, not autoSearch.** Attaches only to editors inside a Learnosity-rendered subtree (any ancestor with a class starting with `lrn`, plus optional caller-supplied selectors). The host app's own editables are left untouched.
+- **`customSelectors` escape hatch.** Caller-supplied ancestor selectors extend the Learnosity scope for unusual host apps without giving up the built-in scoping for the rest.
+- **Optional `shorttext` surface.** Off by default. When `enableShorttext: true`, the connector also attaches to `<input type="text">` inside Learnosity scope.
+- **Configurable WProofreader bundle URL** via `bundleUrl`, for customers running WProofreader from a non-default CDN host.
+- **Apache-2.0 licensed.**
+[1.2.1]: https://github.com/WebSpellChecker/wproofreader-learnosity/releases/tag/v1.2.1
+[1.2.0]: https://github.com/WebSpellChecker/wproofreader-learnosity/releases/tag/v1.2.0
+[1.1.0]: https://github.com/WebSpellChecker/wproofreader-learnosity/releases/tag/v1.1.0
+[1.0.0]: https://github.com/WebSpellChecker/wproofreader-learnosity/releases/tag/v1.0.0

package/LICENSE ADDED Viewed

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+   1. Definitions.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+   END OF TERMS AND CONDITIONS
+   Copyright 2026 WebSpellChecker LLC
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+       http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/README.md ADDED Viewed

@@ -0,0 +1,172 @@
+# @webspellchecker/wproofreader-learnosity
+WProofreader for Learnosity. Spelling, grammar and style assistance inside Learnosity rich-text widgets, with one function call.
+> v1.2.1. Apache-2.0. TypeScript definitions included. Two install paths: npm (ESM) and CDN (IIFE). Cloud and self-hosted WProofreader. Per-editor surface filter, lifecycle cleanup, locale-aware defaults, optional escape hatches for unusual host apps.
+## Install
+The connector offers two install paths. The runtime API is identical, `LearnosityWProofreader.init({...})` in both.
+### Via npm (Node host apps)
+```bash
+npm install @webspellchecker/wproofreader-learnosity
+```
+```js
+import LearnosityWProofreader from '@webspellchecker/wproofreader-learnosity';
+LearnosityWProofreader.init({
+  wproofreader: { serviceId: 'YOUR_WPROOFREADER_SERVICE_ID' }
+});
+```
+### Via `<script>` tag (non-Node host apps)
+For host apps where adding a bundler is overkill (classic HTML, PHP, Python, Java, ASP.NET, Ruby), load the connector from jsDelivr:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webspellchecker/wproofreader-learnosity@1.2.1/dist/wproofreader-learnosity.min.js"></script>
+<script>
+  LearnosityWProofreader.init({
+    wproofreader: { serviceId: 'YOUR_WPROOFREADER_SERVICE_ID' }
+  });
+</script>
+```
+The bundle exposes a single global, `window.LearnosityWProofreader`, with the same `init` method. About 5 KB minified, no runtime dependencies. jsDelivr serves from npm, so the pinned URL above resolves once the package is published.
+## Quickstart
+```js
+import LearnosityWProofreader from '@webspellchecker/wproofreader-learnosity';
+// Before Learnosity widgets render.
+LearnosityWProofreader.init({
+  wproofreader: { serviceId: 'YOUR_WPROOFREADER_SERVICE_ID' }
+});
+// Initialise Learnosity as normal. The connector attaches to longtextV2 editors automatically.
+LearnosityApp.init(signedRequest, {
+  readyListener() { console.log('Learnosity ready'); },
+  errorListener(err) { console.error(err); }
+});
+```
+`init()` is idempotent: calling it again updates the live configuration without reloading the WProofreader bundle.
+## Getting a service ID
+WProofreader is a commercial service from WebSpellChecker. The service ID passed to `init({ wproofreader: { serviceId } })` is your account's activation key.
+- **Free trial**: <https://webspellchecker.com/free-trial/> issues a service ID for evaluation.
+- **Paid subscription** converts the trial to a production licence with the domain set you need.
+- **Domain locking**: every service ID is bound to a list of allowed origins. Whitelist your production and development domains in the WebSpellChecker dashboard; otherwise the spell-check API returns 403 for those origins.
+If you run WProofreader on your own infrastructure (Docker, Helm, on-prem) you skip the service ID entirely. See [Self-hosted WProofreader](#self-hosted-wproofreader) below.
+## Self-hosted WProofreader
+For customers running the [WProofreader Server](https://hub.docker.com/r/webspellchecker/wproofreader) on their own infrastructure (Docker, Helm, on-prem), pass the service connection options inside the `wproofreader` block instead of (or alongside) `serviceId`. Every property on `wproofreader` is forwarded to WProofreader unchanged:
+```js
+LearnosityWProofreader.init({
+  wproofreader: {
+    serviceProtocol: 'https',
+    serviceHost: 'localhost',
+    servicePort: 443,
+    servicePath: '/wscservice/api'
+  },
+  bundleUrl: 'https://localhost/wscservice/wscbundle/wscbundle.js'
+});
+```
+Either `wproofreader.serviceId` or `wproofreader.serviceHost` must be set; otherwise `init()` no-ops with a console warning.
+## Configuration
+`init()` takes a single options object with two groups: a nested `wproofreader` sub-object (forwarded to WProofreader unchanged) and connector-only fields at the top level.
+### WProofreader options (under `wproofreader`)
+These pass straight through to WProofreader's runtime config. The tables below cover the frequently-used ones; the full surface is documented in [Documentation and support](#documentation-and-support).
+| Option            | Default                              | Notes                                                  |
+|-------------------|--------------------------------------|--------------------------------------------------------|
+| `serviceId`       | _none_                               | WProofreader Cloud service ID. Domain-locked server-side. Required for the Cloud path. Omit when using a self-hosted deployment. |
+| `serviceProtocol` | _none_                               | Self-hosted: `'http'` or `'https'`. |
+| `serviceHost`     | _none_                               | Self-hosted: WProofreader server hostname. Presence of `serviceHost` (or `serviceId`) is what activates `init()`. |
+| `servicePort`     | _none_                               | Self-hosted: port. |
+| `servicePath`     | _none_                               | Self-hosted: URL path to the WProofreader API. |
+| `enableGrammar`   | `true`                               | Grammar checking on top of spell checking. |
+| `autocorrect`     | `true`                               | Suggested replacement on typo accept. |
+| `lang`            | host page's `<html lang>`, or `en_US`| Read from `<html lang>` with `-` normalised to `_` (e.g. `en-US` → `en_US`). Falls back to `en_US` if the page does not set a `lang` or sets a bare un-regioned one (`en`, `fr`), because WProofreader expects region-qualified codes. Pass explicitly to override. |
+If neither `wproofreader.serviceId` nor `wproofreader.serviceHost` is set, `init()` no-ops with a console warning so the host app can call it unconditionally.
+### Connector options (top level)
+| Option            | Default       | Notes                                                  |
+|-------------------|---------------|--------------------------------------------------------|
+| `surfaces`        | `['author']`  | Subset of `['questions','items','author']`. **Per-editor** filter: each editor's ancestry is walked for surface-specific markers (`lrn-author*` → author, `lrn_player*` → items, otherwise → questions); editors whose surface is not in the allowed list are skipped. Default is Author only, for assessment integrity. Opt in to assessment proofreading explicitly with `['questions', 'items', 'author']`. |
+| `enableShorttext` | `false`       | Also attach to `shorttext` inputs (`<input type="text">`) inside Learnosity scope. Off by default because plain text inputs are usually short and proofreading them is noisy. |
+| `customSelectors` | `[]`          | Extra ancestor CSS selectors that count as "inside Learnosity scope" for unusual host apps. Each entry is matched via `element.matches`. |
+| `bundleUrl`       | (default CDN) | Override the WProofreader bundle URL for non-default CDNs or self-hosted servers. |
+### Examples
+```js
+// Authoring-only (the default). No-ops on assessment pages.
+LearnosityWProofreader.init({
+  wproofreader: { serviceId: '...' }
+});
+// All three surfaces, including assessment. The host app should derive this
+// from server-side activity metadata so it cannot be flipped from the console.
+LearnosityWProofreader.init({
+  wproofreader: { serviceId: '...' },
+  surfaces: ['questions', 'items', 'author']
+});
+// Unusual host app that wraps Learnosity inside its own container class.
+LearnosityWProofreader.init({
+  wproofreader: { serviceId: '...' },
+  customSelectors: ['.my-host-app-learnosity-region']
+});
+```
+## Supported surfaces
+| Learnosity API | Surface                       |
+|----------------|-------------------------------|
+| Questions API  | `longtextV2` (rich-text essay) |
+| Author API     | All rich-text fields          |
+| Items API      | `assess` rendering type       |
+`shorttext` (plain text input) is opt-in via `enableShorttext: true`.
+## Supported Learnosity versions
+Tested manually against the `latest-lts` channel. The connector tracks editor placement via the `lrn`-prefixed class convention plus a small per-surface marker set; class-rename changes between LTS releases are an isolated update in `src/index.js`.
+## Documentation and support
+- **WProofreader product page**: <https://webspellchecker.com/wsc-proofreader/>
+- **Configuration reference** (every WProofreader option beyond what this connector documents): <https://webspellchecker.com/docs/api/wscbundle/Options.html>
+- **WProofreader SDK source** (the underlying library the connector wraps): <https://github.com/WebSpellChecker/wproofreader-sdk-js>
+- **Self-hosted server image**: <https://hub.docker.com/r/webspellchecker/wproofreader>
+- **Contact and commercial enquiries**: <https://webspellchecker.com/contact-us/>
+## Tests
+```bash
+npm install
+npm test
+```
+`npm test` runs the unit suite under `node --test`.
+## License
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/wproofreader-learnosity.min.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ var LearnosityWProofreader=(()=>{var l=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var S=Object.getOwnPropertyNames;var A=Object.prototype.hasOwnProperty;var E=(e,t)=>{for(var n in t)l(e,n,{get:t[n],enumerable:!0})},v=(e,t,n,o)=>{if(t&&typeof t=="object"\|\|typeof t=="function")for(let r of S(t))!A.call(e,r)&&r!==n&&l(e,r,{get:()=>t[r],enumerable:!(o=L(t,r))\|\|o.enumerable});return e};var g=e=>v(l({},"__esModule",{value:!0}),e);var k={};E(k,{default:()=>D});var _="https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js",C=["questions","items","author"],O={questions:"LearnosityApp",items:"LearnosityItems",author:"LearnosityAuthor"},I=["author"],x=3e4,T=100,h=!1,p=null,f=new WeakSet,d=new WeakMap;function U(e){e=e\|\|{};let t=e.wproofreader\|\|{};if(!t.serviceId&&!t.serviceHost){typeof console<"u"&&console.warn&&console.warn("[wproofreader-learnosity] No wproofreader.serviceId or wproofreader.serviceHost provided. Proofreading will not activate. Pass serviceId for WProofreader Cloud, or serviceHost (plus serviceProtocol, servicePort, servicePath) for a self-hosted deployment.");return}let n=P(e);if(h){Object.assign(window.WEBSPELLCHECKER_CONFIG,n.wproofreader),Object.assign(p,n);return}window.WEBSPELLCHECKER_CONFIG=n.wproofreader,p=n,q(e.bundleUrl\|\|_),W(n),h=!0}function P(e){let t=e.wproofreader\|\|{};return{wproofreader:{...t,enableGrammar:t.enableGrammar!==!1,autocorrect:t.autocorrect!==!1,lang:t.lang\|\|F()},surfaces:R(e.surfaces),enableShorttext:e.enableShorttext===!0,customSelectors:Array.isArray(e.customSelectors)?e.customSelectors.slice():[]}}function F(){if(typeof document>"u")return"en_US";let e=document.documentElement;if(!e\|\|!e.lang)return"en_US";let t=e.lang;return t.indexOf("-")===-1&&t.indexOf("_")===-1?"en_US":t.replace("-","_")}function R(e){return Array.isArray(e)?e.filter(function(t){return C.indexOf(t)!==-1}):I.slice()}function B(e){if(typeof window>"u"\|\|e.length===0)return!1;for(let t=0;t<e.length;t++){let n=O[e[t]];if(n&&typeof window[n]<"u")return!0}return!1}function N(e){let t=e&&e.parentElement;for(;t;){let n=t.classList;if(n&&n.length)for(let o=0;o<n.length;o++){let r=n[o];if(r.indexOf("lrn-author")===0)return"author";if(r.indexOf("lrn_player")===0)return"items"}t=t.parentElement}return"questions"}function m(e,t){let n=e&&e.parentElement;for(;n;){let o=n.classList;if(o)for(let r=0;r<o.length;r++){let i=o[r];if(i==="learnosity-response"\|\|i.indexOf("lrn")===0)return!0}if(t&&t.length&&n.matches)for(let r=0;r<t.length;r++)try{if(n.matches(t[r]))return!0}catch{}n=n.parentElement}return!1}function q(e){if(typeof document>"u"\|\|document.querySelector("script[data-wproofreader-bundle]"))return;let t=document.createElement("script");t.src=e,t.async=!0,t.dataset.wproofreaderBundle="",document.head.appendChild(t)}function W(e){if(typeof document>"u")return;let t=function(o){G(o,e)};t(document),new MutationObserver(function(o){for(let r=0;r<o.length;r++){let i=o[r];if(i.type==="childList"){let s=i.addedNodes;for(let a=0;a<s.length;a++){let c=s[a];c&&c.nodeType===1&&t(c)}let u=i.removedNodes;for(let a=0;a<u.length;a++){let c=u[a];c&&c.nodeType===1&&H(c)}}else if(i.type==="attributes"&&i.attributeName==="contenteditable"){let s=i.target;s&&y(s,e)&&m(s,e.customSelectors)&&b(s,e)}}}).observe(document.body\|\|document.documentElement,{childList:!0,subtree:!0,attributes:!0,attributeFilter:["contenteditable"]})}function G(e,t){if(!e\|\|!e.querySelectorAll)return;let n=[];y(e,t)&&n.push(e);let o=e.querySelectorAll(j(t));for(let r=0;r<o.length;r++)n.push(o[r]);for(let r=0;r<n.length;r++){let i=n[r];m(i,t.customSelectors)&&b(i,t)}}function j(e){let t='iframe, [contenteditable]:not([contenteditable="false"])';return e.enableShorttext&&(t+=', input[type="text"], input:not([type])'),t}function y(e,t){return!e\|\|e.nodeType!==1?!1:e.tagName==="IFRAME"?!0:e.tagName==="INPUT"&&t.enableShorttext?(e.getAttribute("type")\|\|"text").toLowerCase()==="text":!e.hasAttribute\|\|!e.hasAttribute("contenteditable")?!1:e.getAttribute("contenteditable")!=="false"}function b(e,t){if(!e\|\|f.has(e)\|\|!B(t.surfaces))return;let n=N(e);if(t.surfaces.indexOf(n)===-1)return;f.add(e);let o=function(){M("WEBSPELLCHECKER",function(i){let s=Object.assign({},t.wproofreader,{container:e});try{i.init(s,function(u){u&&d.set(e,u)})}catch{}})};if(e.tagName&&e.tagName.toLowerCase()==="iframe"){let i=null;try{i=e.contentDocument}catch{}i&&i.readyState==="complete"?o():e.addEventListener("load",o,{once:!0})}else o()}function H(e){if(e&&(f.has(e)&&w(e),e.querySelectorAll)){let t=e.querySelectorAll('iframe, [contenteditable], input[type="text"], input:not([type])');for(let n=0;n<t.length;n++)f.has(t[n])&&w(t[n])}}function w(e){let t=d.get(e);if(t){try{typeof t.destroy=="function"&&t.destroy()}catch{}d.delete(e)}f.delete(e)}function M(e,t){if(typeof window>"u")return;if(window[e]){t(window[e]);return}let n=setInterval(function(){window[e]&&(clearInterval(n),clearTimeout(o),t(window[e]))},T),o=setTimeout(function(){clearInterval(n),typeof console<"u"&&console.warn&&console.warn("[wproofreader-learnosity] window."+e+" never appeared. Proofreading will not activate.")},x)}var D={init:U};return g(k);})();
2	+ LearnosityWProofreader=LearnosityWProofreader.default;

package/package.json ADDED Viewed

@@ -0,0 +1,50 @@
+{
+  "name": "@webspellchecker/wproofreader-learnosity",
+  "version": "1.2.1",
+  "description": "WProofreader for Learnosity. Spelling, grammar and style assistance inside Learnosity rich-text widgets.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "build": "esbuild src/index.js --bundle --format=iife --global-name=LearnosityWProofreader '--footer:js=LearnosityWProofreader=LearnosityWProofreader.default;' --minify --outfile=dist/wproofreader-learnosity.min.js",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "^0.23.0"
+  },
+  "keywords": [
+    "learnosity",
+    "wproofreader",
+    "webspellchecker",
+    "spell-check",
+    "grammar",
+    "ckeditor"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://github.com/WebSpellChecker/wproofreader-learnosity",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WebSpellChecker/wproofreader-learnosity.git"
+  },
+  "private": false,
+  "license": "Apache-2.0",
+  "dependencies": {
+    "user": "0.0.0"
+  }
+}

package/src/index.d.ts ADDED Viewed

@@ -0,0 +1,106 @@
+/**
+ * Type definitions for @webspellchecker/wproofreader-learnosity.
+ * Hand-written to match src/index.js. Keep in sync.
+ */
+/**
+ * Learnosity API surfaces the connector knows how to scope to. Each editor's
+ * ancestry is walked for surface-specific markers; editors whose surface is
+ * not in the allowed list are skipped.
+ */
+export type Surface = 'questions' | 'items' | 'author';
+/**
+ * Runtime options forwarded to WProofreader unchanged. The connector does
+ * not enforce any schema beyond `serviceId` / `serviceHost` activation, so
+ * any other WProofreader option may also be set.
+ */
+export interface WProofreaderOptions {
+  /**
+   * WProofreader Cloud service ID. Domain-locked server-side. Required for
+   * the Cloud path. Omit when using a self-hosted deployment.
+   */
+  serviceId?: string;
+  /** Self-hosted: protocol. */
+  serviceProtocol?: 'http' | 'https';
+  /**
+   * Self-hosted: WProofreader server hostname. Presence of `serviceHost` (or
+   * `serviceId`) activates `init()`.
+   */
+  serviceHost?: string;
+  /** Self-hosted: port. */
+  servicePort?: number | string;
+  /** Self-hosted: URL path to the WProofreader API (e.g. `/wscservice/api`). */
+  servicePath?: string;
+  /** Default `true`. */
+  enableGrammar?: boolean;
+  /** Default `true`. */
+  autocorrect?: boolean;
+  /**
+   * Default: the host page's `<html lang>` attribute, with `-` normalised to
+   * `_` (e.g. `en-US` becomes `en_US`). Falls back to `en_US` if the page
+   * does not set a `lang` or sets a bare un-regioned one (WProofreader
+   * requires region-qualified codes).
+   */
+  lang?: string;
+  /**
+   * Forward-compatible escape hatch: any other property is passed through to
+   * WProofreader's runtime config unchanged. Useful for WProofreader options
+   * the connector does not enumerate explicitly.
+   */
+  [other: string]: unknown;
+}
+export interface InitOptions {
+  /** WProofreader runtime options. Forwarded to WProofreader unchanged. */
+  wproofreader?: WProofreaderOptions;
+  /**
+   * Subset of `['questions','items','author']`. Default `['author']` for
+   * assessment integrity. The connector walks each editor's ancestry to
+   * detect which Learnosity API placed it (`lrn-author*` → author,
+   * `lrn_player*` → items, otherwise → questions) and skips editors whose
+   * surface is not in the allowed list. Opt in to assessment proofreading
+   * explicitly with `['questions', 'items', 'author']`.
+   */
+  surfaces?: ReadonlyArray<Surface>;
+  /**
+   * Default `false`. Also attach to `shorttext` inputs (`<input type="text">`)
+   * inside Learnosity scope.
+   */
+  enableShorttext?: boolean;
+  /**
+   * Extra ancestor CSS selectors that count as "inside Learnosity scope" for
+   * unusual host apps. Each entry is matched via `element.matches`.
+   */
+  customSelectors?: ReadonlyArray<string>;
+  /** Override the WProofreader bundle URL for non-default CDNs or self-hosted servers. */
+  bundleUrl?: string;
+}
+/**
+ * Public API surface. The default export is the namespace object; the call
+ * site mirrors that shape.
+ */
+export interface LearnosityWProofreader {
+  /**
+   * Initialise the connector. Should be called before Learnosity widgets
+   * render. Safe to call multiple times: subsequent calls update the live
+   * configuration without reloading the WProofreader bundle.
+   */
+  init(options?: InitOptions): void;
+}
+declare const LearnosityWProofreader: LearnosityWProofreader;
+export default LearnosityWProofreader;

package/src/index.js ADDED Viewed

@@ -0,0 +1,502 @@
+/**
+ * WProofreader connector for Learnosity.
+ *
+ * Targeted attachment to Learnosity-rendered editables, scoped by an ancestry
+ * walk for any `lrn`-prefixed class plus optional caller-supplied selectors.
+ * Per-editor `surfaces` filter (default `['author']`) covers assessment
+ * integrity by excluding Questions and Items by default; the host app opts in
+ * explicitly. Cleans up WProofreader instances when their host elements are
+ * removed from the DOM (single-page apps that rebuild Learnosity widgets do
+ * not leak).
+ *
+ * Usage in a host app:
+ *
+ *   import LearnosityWProofreader from '@webspellchecker/wproofreader-learnosity';
+ *
+ *   LearnosityWProofreader.init({
+ *     wproofreader: { serviceId: 'YOUR_WPROOFREADER_SERVICE_ID' }
+ *   });
+ *
+ *   LearnosityApp.init(signedRequest, callbacks);
+ */
+const DEFAULT_BUNDLE_URL =
+  'https://svc.webspellchecker.net/spellcheck31/wscbundle/wscbundle.js';
+/*
+ * Surfaces the connector recognises. `SURFACE_GLOBALS` maps each to the
+ * `window` global Learnosity exposes for that API. Used in two places:
+ *   - `isAnyAllowedSurfaceLoaded`: cheap page-level gate; skip everything if
+ *     no allowed-surface global has loaded yet.
+ *   - `detectSurface`: per-editor classification via DOM-ancestor markers,
+ *     so multi-API pages are filtered correctly.
+ */
+const ALLOWED_SURFACES = ['questions', 'items', 'author'];
+const SURFACE_GLOBALS = {
+  questions: 'LearnosityApp',
+  items: 'LearnosityItems',
+  author: 'LearnosityAuthor'
+};
+/*
+ * Default surfaces. Author only, because Questions and Items render
+ * student-facing assessments where spell-check can compromise the activity
+ * itself. Host apps that want proofreading in those contexts opt in
+ * explicitly with `surfaces: ['questions', 'items', 'author']`.
+ */
+const DEFAULT_SURFACES = ['author'];
+/*
+ * Maximum wait for `window.WEBSPELLCHECKER` to appear after the bundle
+ * `<script>` is injected. The bundle loads async, so it may not be on
+ * `window` by the time the first editor needs attaching. After this timeout,
+ * `whenAvailable` logs a console warning and stops waiting.
+ */
+const GLOBAL_WAIT_TIMEOUT_MS = 30000;
+const GLOBAL_POLL_INTERVAL_MS = 100;
+let initialized = false;
+let currentConnectorConfig = null;
+const attachedContainers = new WeakSet();
+const containerToInstance = new WeakMap();
+/**
+ * Initialise the connector. Should be called before Learnosity widgets render.
+ * Safe to call multiple times: subsequent calls update the live configuration
+ * without reloading the WProofreader bundle or re-binding the observer.
+ *
+ * Options are split into two groups:
+ *   - `wproofreader`: passed through to WProofreader unchanged (its runtime
+ *     options surface). `serviceId` for Cloud or `serviceHost` for self-hosted
+ *     activates the connector; without one of these, init() no-ops with a
+ *     console warning.
+ *   - Top-level keys: connector-only configuration (`surfaces`,
+ *     `enableShorttext`, `customSelectors`, `bundleUrl`).
+ *
+ * @param {Object}    [options]
+ * @param {Object}    [options.wproofreader]                    WProofreader runtime options.
+ *                                                              Forwarded to WProofreader unchanged.
+ * @param {string}    [options.wproofreader.serviceId]          WProofreader Cloud service ID.
+ *                                                              Required for the Cloud path. Omit
+ *                                                              when using a self-hosted deployment
+ *                                                              (see `serviceHost`).
+ * @param {string}    [options.wproofreader.serviceProtocol]    Self-hosted: 'http' or 'https'.
+ * @param {string}    [options.wproofreader.serviceHost]        Self-hosted: hostname of the
+ *                                                              WProofreader server. Presence of
+ *                                                              `serviceHost` (or `serviceId`)
+ *                                                              activates init().
+ * @param {number}    [options.wproofreader.servicePort]        Self-hosted: port.
+ * @param {string}    [options.wproofreader.servicePath]        Self-hosted: URL path to the
+ *                                                              WProofreader API (e.g.
+ *                                                              '/wscservice/api').
+ * @param {boolean}   [options.wproofreader.enableGrammar]      Default true.
+ * @param {boolean}   [options.wproofreader.autocorrect]        Default true.
+ * @param {string}    [options.wproofreader.lang]               Default: the host page's
+ *                                                              `<html lang>` attribute, with `-`
+ *                                                              normalised to `_` (e.g. `en-US`
+ *                                                              becomes `en_US`). Falls back to
+ *                                                              `en_US` if the page does not set a
+ *                                                              `lang` or sets a bare un-regioned
+ *                                                              one (WProofreader requires
+ *                                                              region-qualified codes).
+ * @param {string[]}  [options.surfaces]                        Connector-only. Subset of
+ *                                                              ['questions','items','author'].
+ *                                                              Default: `['author']`
+ *                                                              (assessment-safe). The connector
+ *                                                              walks each editor's ancestry to
+ *                                                              detect which Learnosity API placed
+ *                                                              it (`lrn-author*` → author,
+ *                                                              `lrn_player*` → items, otherwise →
+ *                                                              questions) and skips editors whose
+ *                                                              surface is not in the allowed list.
+ * @param {boolean}   [options.enableShorttext]                 Connector-only. Default false. When
+ *                                                              true, also attach to `shorttext`
+ *                                                              inputs (`<input type="text">`)
+ *                                                              inside Learnosity scope. Off by
+ *                                                              default because plain text inputs
+ *                                                              are often short and proofreading
+ *                                                              them feels noisy.
+ * @param {string[]}  [options.customSelectors]                 Connector-only. Extra ancestor CSS
+ *                                                              selectors that count as "inside
+ *                                                              Learnosity scope" for unusual host
+ *                                                              apps.
+ * @param {string}    [options.bundleUrl]                       Connector-only. Override the
+ *                                                              WProofreader bundle URL.
+ */
+function init(options) {
+  options = options || {};
+  const wp = options.wproofreader || {};
+  if (!wp.serviceId && !wp.serviceHost) {
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn(
+        '[wproofreader-learnosity] No wproofreader.serviceId or wproofreader.serviceHost ' +
+        'provided. Proofreading will not activate. Pass serviceId for WProofreader Cloud, or ' +
+        'serviceHost (plus serviceProtocol, servicePort, servicePath) for a self-hosted deployment.'
+      );
+    }
+    return;
+  }
+  const config = buildConfig(options);
+  if (initialized) {
+    // Idempotent: update the live WProofreader config in place so the observer's
+    // captured config keeps the same identity, while WProofreader's bundle picks
+    // up the new values next time it reads `window.WEBSPELLCHECKER_CONFIG`.
+    Object.assign(window.WEBSPELLCHECKER_CONFIG, config.wproofreader);
+    Object.assign(currentConnectorConfig, config);
+    return;
+  }
+  /*
+   * WProofreader's bundle reads its runtime config from
+   * `window.WEBSPELLCHECKER_CONFIG` when it boots, so the object must exist
+   * before the bundle `<script>` runs. `autoSearch` is intentionally absent
+   * from the config: we attach explicitly via `observeLearnosity` below so
+   * attachment stays scoped to Learnosity-rendered editors only.
+   */
+  window.WEBSPELLCHECKER_CONFIG = config.wproofreader;
+  currentConnectorConfig = config;
+  loadBundle(options.bundleUrl || DEFAULT_BUNDLE_URL);
+  observeLearnosity(config);
+  initialized = true;
+}
+/*
+ * Two-tier config:
+ *   - `wproofreader`: everything WProofreader's bundle reads from
+ *     `window.WEBSPELLCHECKER_CONFIG`. Spread-then-default so any unknown
+ *     option (self-hosted service*, future WProofreader knobs) flows through
+ *     unchanged, while our defaults (enableGrammar, autocorrect, lang) apply
+ *     only when the caller did not supply them.
+ *   - Top-level: connector-only fields the observer reads (surfaces,
+ *     enableShorttext, customSelectors). `bundleUrl` is consumed by
+ *     `loadBundle()` directly from `options` and is not stored here.
+ */
+function buildConfig(options) {
+  const wp = options.wproofreader || {};
+  return {
+    wproofreader: {
+      ...wp,
+      enableGrammar: wp.enableGrammar !== false,
+      autocorrect: wp.autocorrect !== false,
+      lang: wp.lang || defaultLang()
+    },
+    surfaces: normalizeSurfaces(options.surfaces),
+    enableShorttext: options.enableShorttext === true,
+    customSelectors: Array.isArray(options.customSelectors) ? options.customSelectors.slice() : []
+  };
+}
+/*
+ * Default WProofreader language. Read from the host page's `<html lang>` so a
+ * Learnosity activity rendered into a French page proofreads in French without
+ * the host app having to pass `lang` explicitly. Normalise `en-US` style to
+ * `en_US` (WProofreader's expected separator).
+ *
+ * WProofreader requires a region-qualified code: bare `en` is rejected with
+ * "Language 'en' is unsupported or doesn't exist." So we only use the host
+ * page's lang when it includes a region; otherwise we fall back to `en_US`.
+ */
+function defaultLang() {
+  if (typeof document === 'undefined') return 'en_US';
+  const html = document.documentElement;
+  if (!html || !html.lang) return 'en_US';
+  const lang = html.lang;
+  if (lang.indexOf('-') === -1 && lang.indexOf('_') === -1) return 'en_US';
+  return lang.replace('-', '_');
+}
+/*
+ * Coerce caller input into a valid subset of ALLOWED_SURFACES. Non-arrays
+ * fall back to DEFAULT_SURFACES; unrecognised entries are dropped silently.
+ */
+function normalizeSurfaces(input) {
+  if (!Array.isArray(input)) return DEFAULT_SURFACES.slice();
+  return input.filter(function (s) { return ALLOWED_SURFACES.indexOf(s) !== -1; });
+}
+/*
+ * Cheap page-level pre-check: is any allowed-surface Learnosity global on the
+ * page at all? If not, no point doing any per-editor work.
+ */
+function isAnyAllowedSurfaceLoaded(surfaces) {
+  if (typeof window === 'undefined') return false;
+  if (surfaces.length === 0) return false;
+  for (let i = 0; i < surfaces.length; i++) {
+    const g = SURFACE_GLOBALS[surfaces[i]];
+    if (g && typeof window[g] !== 'undefined') return true;
+  }
+  return false;
+}
+/*
+ * Per-editor surface detection. Walks the editor's ancestry looking for the
+ * smallest set of class names that distinguish each Learnosity API in the
+ * rendered DOM. Markers confirmed from `Learnosity/learnosity-apis-css`:
+ *
+ *   - Author API uses the hyphenated `lrn-author` / `lrn-author-*` prefix
+ *     exclusively (no other API does).
+ *   - Items API (Assess) wraps its player in `.lrn_player`, also unique.
+ *   - Everything else `lrn_*` falls through to Questions API as the catch-all.
+ *
+ * Best effort. If Learnosity renames these between LTS versions, the update
+ * is isolated to this function. The `customSelectors` option is the escape
+ * hatch for unusual host apps.
+ */
+function detectSurface(el) {
+  let cur = el && el.parentElement;
+  while (cur) {
+    const list = cur.classList;
+    if (list && list.length) {
+      for (let i = 0; i < list.length; i++) {
+        const cls = list[i];
+        if (cls.indexOf('lrn-author') === 0) return 'author';
+        if (cls.indexOf('lrn_player') === 0) return 'items';
+      }
+    }
+    cur = cur.parentElement;
+  }
+  return 'questions';
+}
+/*
+ * Learnosity rewrites the host-page placeholder span during render and does
+ * not preserve our `learnosity-response` class on the result. So instead of
+ * scoping by a single anchor class, we walk up the DOM from each candidate
+ * editable and check for any ancestor whose class matches Learnosity's
+ * conventions ("learnosity-response" exact, or any class starting with "lrn").
+ * Caller-supplied selectors (customSelectors) extend the scope for unusual
+ * host apps without giving up the Learnosity-internal scoping for the rest.
+ */
+function hasLearnosityAncestor(el, customSelectors) {
+  let cur = el && el.parentElement;
+  while (cur) {
+    const list = cur.classList;
+    if (list) {
+      for (let i = 0; i < list.length; i++) {
+        const cls = list[i];
+        if (cls === 'learnosity-response' || cls.indexOf('lrn') === 0) return true;
+      }
+    }
+    if (customSelectors && customSelectors.length && cur.matches) {
+      for (let j = 0; j < customSelectors.length; j++) {
+        try { if (cur.matches(customSelectors[j])) return true; } catch (_) { /* bad selector */ }
+      }
+    }
+    cur = cur.parentElement;
+  }
+  return false;
+}
+/*
+ * Inject the WProofreader bundle `<script>` exactly once per page. The
+ * `data-wproofreader-bundle` attribute serves as the idempotency marker.
+ */
+function loadBundle(url) {
+  if (typeof document === 'undefined') return;
+  if (document.querySelector('script[data-wproofreader-bundle]')) return;
+  const script = document.createElement('script');
+  script.src = url;
+  script.async = true;
+  script.dataset.wproofreaderBundle = '';
+  document.head.appendChild(script);
+}
+/*
+ * Watch the document for editables appearing or disappearing inside Learnosity
+ * scope. On addition, attach. On removal, detach so SPA hosts that rebuild
+ * Learnosity widgets do not leak WProofreader instances.
+ */
+function observeLearnosity(config) {
+  if (typeof document === 'undefined') return;
+  const scanRoot = function (root) { scanForEditables(root, config); };
+  scanRoot(document);
+  const observer = new MutationObserver(function (mutations) {
+    for (let i = 0; i < mutations.length; i++) {
+      const m = mutations[i];
+      if (m.type === 'childList') {
+        const added = m.addedNodes;
+        for (let j = 0; j < added.length; j++) {
+          const node = added[j];
+          if (node && node.nodeType === 1 /* ELEMENT_NODE */) scanRoot(node);
+        }
+        const removed = m.removedNodes;
+        for (let k = 0; k < removed.length; k++) {
+          const node = removed[k];
+          if (node && node.nodeType === 1) detachInSubtree(node);
+        }
+      } else if (m.type === 'attributes' && m.attributeName === 'contenteditable') {
+        const el = m.target;
+        if (el && matchesCandidate(el, config) && hasLearnosityAncestor(el, config.customSelectors)) {
+          attachToContainer(el, config);
+        }
+      }
+    }
+  });
+  observer.observe(document.body || document.documentElement, {
+    childList: true,
+    subtree: true,
+    // Catch editors whose `contenteditable` flips to truthy after insertion.
+    attributes: true,
+    attributeFilter: ['contenteditable']
+  });
+}
+/*
+ * Find every editable under `root` that sits inside a Learnosity-rendered
+ * subtree, and attach. `root` can be the document or a freshly-added subtree.
+ */
+function scanForEditables(root, config) {
+  if (!root || !root.querySelectorAll) return;
+  const candidates = [];
+  if (matchesCandidate(root, config)) candidates.push(root);
+  const inside = root.querySelectorAll(candidateSelector(config));
+  for (let i = 0; i < inside.length; i++) candidates.push(inside[i]);
+  for (let i = 0; i < candidates.length; i++) {
+    const el = candidates[i];
+    if (hasLearnosityAncestor(el, config.customSelectors)) attachToContainer(el, config);
+  }
+}
+/*
+ * Selector for "could plausibly be an editable WProofreader should attach to."
+ * Always includes iframes (CKEditor classic) and truthy contenteditables.
+ * Includes plain text inputs only when enableShorttext is on.
+ */
+function candidateSelector(config) {
+  let s = 'iframe, [contenteditable]:not([contenteditable="false"])';
+  if (config.enableShorttext) s += ', input[type="text"], input:not([type])';
+  return s;
+}
+/*
+ * Element-level equivalent of `candidateSelector`. Used by the
+ * attribute-mutation branch of `observeLearnosity`, where we already have the
+ * target element and don't want to re-query the DOM.
+ */
+function matchesCandidate(el, config) {
+  if (!el || el.nodeType !== 1) return false;
+  if (el.tagName === 'IFRAME') return true;
+  if (el.tagName === 'INPUT' && config.enableShorttext) {
+    const t = (el.getAttribute('type') || 'text').toLowerCase();
+    return t === 'text';
+  }
+  if (!el.hasAttribute || !el.hasAttribute('contenteditable')) return false;
+  return el.getAttribute('contenteditable') !== 'false';
+}
+/*
+ * Initialise WProofreader against a container element. Three gates before we
+ * actually attach:
+ *   - dedupe against `attachedContainers` (no double-attaches across observer
+ *     events).
+ *   - page-level pre-check: at least one allowed-surface Learnosity global
+ *     must be loaded.
+ *   - per-editor surface filter: `detectSurface(container)` must be in
+ *     `config.surfaces`.
+ * Then, for an iframe whose document is not yet loaded, defer until the
+ * `load` event so WProofreader sees the editable body. WProofreader's bundle
+ * may still be loading, so we also wait for `window.WEBSPELLCHECKER` to
+ * appear. The returned instance is tracked so we can destroy it later when
+ * the host element is removed.
+ */
+function attachToContainer(container, config) {
+  if (!container || attachedContainers.has(container)) return;
+  if (!isAnyAllowedSurfaceLoaded(config.surfaces)) return;
+  const surface = detectSurface(container);
+  if (config.surfaces.indexOf(surface) === -1) return;
+  attachedContainers.add(container);
+  const go = function () {
+    whenAvailable('WEBSPELLCHECKER', function (WSC) {
+      const initArgs = Object.assign({}, config.wproofreader, { container: container });
+      try {
+        WSC.init(initArgs, function (instance) {
+          if (instance) containerToInstance.set(container, instance);
+        });
+      } catch (_) { /* WProofreader handled the failure internally */ }
+    });
+  };
+  const isIframe = container.tagName && container.tagName.toLowerCase() === 'iframe';
+  if (isIframe) {
+    let doc = null;
+    try { doc = container.contentDocument; } catch (_) { /* cross-origin */ }
+    if (doc && doc.readyState === 'complete') {
+      go();
+    } else {
+      container.addEventListener('load', go, { once: true });
+    }
+  } else {
+    go();
+  }
+}
+/*
+ * Walk a removed subtree, find any container we previously attached, destroy
+ * its WProofreader instance, and forget it. WeakSet/WeakMap don't enumerate,
+ * so we re-walk the DOM with `has()` checks instead.
+ */
+function detachInSubtree(root) {
+  if (!root) return;
+  if (attachedContainers.has(root)) detachFromContainer(root);
+  if (root.querySelectorAll) {
+    // Match the broadest possible candidate selector so we catch anything we
+    // could have attached to under any config.
+    const candidates = root.querySelectorAll('iframe, [contenteditable], input[type="text"], input:not([type])');
+    for (let i = 0; i < candidates.length; i++) {
+      if (attachedContainers.has(candidates[i])) detachFromContainer(candidates[i]);
+    }
+  }
+}
+/*
+ * Destroy the WProofreader instance attached to `container` and forget the
+ * mapping. Safe to call on containers we never attached to.
+ */
+function detachFromContainer(container) {
+  const inst = containerToInstance.get(container);
+  if (inst) {
+    try {
+      if (typeof inst.destroy === 'function') inst.destroy();
+    } catch (_) { /* swallow */ }
+    containerToInstance.delete(container);
+  }
+  attachedContainers.delete(container);
+}
+/*
+ * Resolve a global once it appears on `window`, with a hard timeout so a
+ * missing script does not leak an interval forever.
+ */
+function whenAvailable(globalName, callback) {
+  if (typeof window === 'undefined') return;
+  if (window[globalName]) { callback(window[globalName]); return; }
+  const interval = setInterval(function () {
+    if (window[globalName]) {
+      clearInterval(interval);
+      clearTimeout(timeout);
+      callback(window[globalName]);
+    }
+  }, GLOBAL_POLL_INTERVAL_MS);
+  const timeout = setTimeout(function () {
+    clearInterval(interval);
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn('[wproofreader-learnosity] window.' + globalName +
+        ' never appeared. Proofreading will not activate.');
+    }
+  }, GLOBAL_WAIT_TIMEOUT_MS);
+}
+/*
+ * Public API. Exported as a default object so the import shape mirrors the
+ * call site:
+ *
+ *   import LearnosityWProofreader from '@webspellchecker/wproofreader-learnosity';
+ *   LearnosityWProofreader.init({ wproofreader: { serviceId: '...' } });
+ */
+export default { init };