achilles 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97bbd095ec5feda0679a77b020f80ad70ec59b202757af4d84e1c318643a4632
-  data.tar.gz: 40bdce2ca5420c29a4be44260e2655cfbca3e6357d294aa017454c0f90b9a642
+  metadata.gz: d393e3c7e9d04d6a472ba4e41c727fffca5fa3088f5d064a08a0f9cd4b2bfcf2
+  data.tar.gz: 911efcf9ddc72755b3b26b9a8ae3d0a5538d4d33ba2f8476d6c4ae4c8aa54e8e
 SHA512:
-  metadata.gz: d21a4690c44bfeb356544370465319b6b6d969731a07aa4f4a9e462e32038a57c53f63f2e6ee05b5b3959e86d1fe7f517b48acce6ab8d08266d9dd7de8589285
-  data.tar.gz: b1a8de0b8ed2beb3d564df46e35568958989b93b1ca5f8b2d4d89a93dadb40640b1d81c5ef0a0316a7c4016f7ed29da1382ef10b86bdf1103756075a6ec11293
+  metadata.gz: a480a6ca6a9b154cdf723aa53560a1caa2a82f41f569a3e2d79dafbd80e50d1dea7a9c9b18d29f69c8eb9d693af79b358929929b9842a014645eaf939105dea5
+  data.tar.gz: 52f50f6c02b169e7d592363571da480961aa6ac52a856aaca72dc3f26f4e5c557e9b5c918e24f18bdfec6d5d37685936e49678e093ea182d4dc8730bad6d898c

data/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to Achilles will be documented in this file.
 
+## 1.1.0
+
+### Added
+
+- Added explicit `Application#start` and `Application#stop` lifecycle methods.
+- Added opt-in `Application#strictLifecycleErrors` handling for tests and
+  development.
+- Added browser system coverage for nested components inside Turbo form
+  replacement and Turbo Drive navigation.
+
+### Changed
+
+- `Application` no longer starts automatically from the constructor. Applications
+  should register component classes, then call `achilles.start()`. See
+  [docs/upgrading-to-1.1.0.md](docs/upgrading-to-1.1.0.md).
+- Elements with `data-component-class` must now have a non-empty `id`; invalid
+  component roots are skipped with a console error.
+- Component teardown now runs from child components to parent components.
+- Component parentage now follows DOM ancestry under the synthetic `Page` root.
+- Turbo lifecycle hooks are now attached by `start()` and removed by `stop()`.
+- Achilles now requires `turbo-rails` so Turbo importmap assets are available to
+  host applications.
+
 ## 1.0.0
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Code Of Conduct
+
+## Our Pledge
+
+We want Achilles to be a respectful, useful, and practical open source project.
+
+Everyone participating in the project is expected to communicate with clarity,
+patience, and respect. Disagreement is fine. Harassment, personal attacks, and
+abusive behavior are not.
+
+## Expected Behavior
+
+- Be respectful of differing experience levels and viewpoints.
+- Keep technical criticism focused on the code, design, or documentation.
+- Assume good intent, but be direct when something is unclear or risky.
+- Help keep issues and pull requests actionable.
+- Respect maintainers' time and project scope.
+
+## Unacceptable Behavior
+
+- Harassment, threats, or personal attacks.
+- Insults, slurs, or discriminatory language.
+- Public or private abuse of contributors or maintainers.
+- Publishing someone's private information without permission.
+- Repeated off-topic disruption after maintainers ask for the discussion to
+  stop or move elsewhere.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, reject pull requests, or block
+participants who violate this code of conduct.
+
+To report a concern, email:
+
+```text
+jey@jeygeethan.com
+```
+
+Reports will be reviewed privately. Please include relevant links, screenshots,
+or context when possible.
+
+## Scope
+
+This code of conduct applies to Achilles project spaces, including GitHub
+issues, pull requests, discussions, release comments, and private project
+communication with maintainers.

data/CONTRIBUTING.md

@@ -0,0 +1,122 @@
+# Contributing
+
+Thanks for taking the time to improve Achilles.
+
+Achilles is intentionally small. Contributions should keep the public API clear,
+the Rails + Turbo integration reliable, and the documentation practical for
+applications that already use the gem.
+
+## Local Setup
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the dummy Rails app:
+
+```bash
+bin/rails server
+```
+
+Open:
+
+```text
+http://localhost:3000/
+```
+
+The dummy app includes a working counter component that exercises the basic
+Achilles flow.
+
+## Test Commands
+
+Run the Rails and JavaScript lifecycle tests:
+
+```bash
+bin/rails test
+```
+
+Run the browser system test:
+
+```bash
+bin/rails test:system
+```
+
+Run JavaScript syntax checks:
+
+```bash
+for file in $(find app/javascript/achilles test/dummy/app/javascript -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+```
+
+Run the dummy app asset precompile check:
+
+```bash
+RAILS_ENV=test bin/rails app:assets:precompile
+```
+
+Run the full local verification set:
+
+```bash
+bin/rails test
+bin/rails test:system
+for file in $(find app/javascript/achilles test/dummy/app/javascript -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+RAILS_ENV=test bin/rails app:assets:precompile
+```
+
+## System Test Browser Requirements
+
+System tests use Selenium with headless Chrome.
+
+On CI, GitHub's Ubuntu runner provides Chrome. Locally, set these environment
+variables if Chrome or chromedriver are installed in non-standard locations:
+
+```bash
+CHROME_BIN=/path/to/chrome CHROMEDRIVER_PATH=/path/to/chromedriver bin/rails test:system
+```
+
+If Chrome is not available, the system test base skips browser tests cleanly.
+
+## Pull Request Guidelines
+
+- Keep changes scoped.
+- Add or update tests for behavior changes.
+- Update the README or docs for public API changes.
+- Add or update an upgrade guide for changes existing applications must make.
+- Mention breaking changes clearly in the pull request.
+- Do not introduce a new runtime dependency without explaining why it belongs in
+  a small lifecycle gem.
+- Prefer browser DOM APIs in Achilles internals.
+- Keep jQuery usage out of Achilles internals. Applications may still use jQuery
+  explicitly in their own components.
+
+## Public API Expectations
+
+Treat these as public API:
+
+- `Application`
+- `ComponentBase`
+- `ComponentsClassMapper`
+- `data-component-class`
+- `setup()`
+- `teardown()`
+- `rootElement()`
+- `rootNode()`
+- `rootElementSelector()`
+
+Changes to these APIs need tests, documentation, and changelog notes.
+
+## Release Process
+
+Use [docs/release-checklist.md](docs/release-checklist.md) for prereleases and
+final releases.
+
+Maintainer release ownership and project decision guidelines are documented in
+[MAINTAINERS.md](MAINTAINERS.md).
+
+Before releasing:
+
+- confirm CI is green
+- run the full local verification set
+- build the gem with `gem build achilles.gemspec`
+- test release candidates in at least one real application

data/MAINTAINERS.md

@@ -0,0 +1,53 @@
+# Maintainers
+
+Achilles is maintained as a small, stable Rails + Turbo lifecycle gem.
+
+The maintainer goal is to keep the public API easy to understand, the runtime
+surface small, and releases safe for applications that already depend on the
+gem.
+
+## Decision Making
+
+Maintainers should prefer changes that:
+
+- preserve the small public API
+- improve reliability across Rails, Turbo, and importmap applications
+- reduce hidden runtime dependencies
+- make migration or debugging easier for existing applications
+- include tests for changed behavior
+
+Breaking changes are acceptable when they make the project simpler, safer, or
+more predictable. They should be documented in `CHANGELOG.md`, covered by tests,
+and called out in migration notes when existing applications need code changes.
+
+## Release Ownership
+
+Before publishing a release, a maintainer should:
+
+- confirm CI is green
+- run the local verification set in `CONTRIBUTING.md`
+- follow `docs/release-checklist.md`
+- test release candidates in at least one real Rails application when behavior
+  changes affect runtime integration
+
+Patch releases should be narrow and low risk. Minor releases can add compatible
+APIs or documentation improvements. Major releases may remove deprecated
+behavior or tighten public contracts.
+
+## Security Reports
+
+Security reports should follow `SECURITY.md`. Reports are handled privately
+until there is a fix or a clear public response.
+
+## Community Standards
+
+Project participation is covered by `CODE_OF_CONDUCT.md`. Maintainers may close
+issues, reject pull requests, edit discussions, or block participants when
+needed to keep the project focused and respectful.
+
+## Adding Maintainers
+
+New maintainers should already have a history of useful issues, documentation,
+or code contributions. They should understand the project scope, support the
+public API expectations in `CONTRIBUTING.md`, and be comfortable reviewing
+changes conservatively.

data/README.md

@@ -1,12 +1,49 @@
 # Achilles
 
 Achilles is a small JavaScript lifecycle layer for Rails + Turbo applications.
-It is positioned as a simpler alternative to Stimulus for apps that prefer
-explicit component classes mapped to DOM nodes.
+It is an explicit component-class alternative to Stimulus for teams that prefer
+plain JavaScript classes mapped directly to DOM nodes.
 
 Achilles scans the page for elements with `data-component-class`, instantiates
 the matching JavaScript class, and calls `setup` and `teardown` as Turbo renders
-new pages.
+new pages or new component markup is inserted.
+
+## Why Achilles?
+
+Rails and Turbo make server-rendered interfaces productive, but many apps still
+need page-specific JavaScript for menus, forms, filters, widgets, charts, and
+small interaction islands.
+
+Achilles keeps that JavaScript close to the DOM without requiring controller
+naming conventions or a build step. You register classes explicitly, mark the
+HTML root node, and implement lifecycle methods.
+
+Use Achilles when you want:
+
+- explicit JavaScript classes instead of controller naming conventions
+- lifecycle hooks that match Turbo navigation
+- no internal jQuery dependency
+- no JavaScript build step
+- predictable setup and teardown for server-rendered UI
+- simple dynamic DOM registration through `MutationObserver`
+
+## Achilles vs Stimulus
+
+Stimulus is a strong default for many Rails apps. Achilles is intentionally
+smaller and more explicit.
+
+| Concern | Achilles | Stimulus |
+| --- | --- | --- |
+| Class registration | Explicit mapper registration | File and identifier conventions |
+| DOM marker | `data-component-class` | `data-controller` |
+| Root element API | `this.rootElement()` | `this.element` |
+| Lifecycle | `setup()` and `teardown()` | `connect()` and `disconnect()` |
+| Targets/actions | Use standard DOM APIs | Built-in targets/actions |
+| Dependency | Rails, Turbo, Importmap | Hotwire Stimulus |
+
+Choose Achilles if you want a tiny lifecycle layer with explicit class mapping.
+Choose Stimulus if you want its controller ecosystem, targets, values, actions,
+and conventions.
 
 ## Requirements
 
@@ -39,6 +76,7 @@ import { CounterComponent } from "components/counter_component";
 
 const achilles = new Application();
 achilles.componentsClassMapper.addComponentClass("CounterComponent", CounterComponent);
+achilles.start();
 ```
 
 Create components by extending `ComponentBase`:
@@ -74,13 +112,114 @@ Every component root must have a unique `id`. Achilles uses that id to register
 the component, find its root element, and avoid running setup twice for the same
 DOM node.
 
+## Dynamic Components
+
+Achilles watches the document for inserted component markup. If Turbo Streams,
+custom JavaScript, or another UI flow adds a matching element, Achilles parses
+and sets it up automatically.
+
+```erb
+<div id="notification-42" data-component-class="NotificationComponent">
+  Saved successfully
+</div>
+```
+
+```js
+import { ComponentBase } from "achilles/components/component_base";
+
+class NotificationComponent extends ComponentBase {
+  setup() {
+    this.timeout = window.setTimeout(() => {
+      this.rootElement().remove();
+    }, 3000);
+  }
+
+  teardown() {
+    window.clearTimeout(this.timeout);
+  }
+}
+
+export { NotificationComponent };
+```
+
+Register the component class once:
+
+```js
+achilles.componentsClassMapper.addComponentClass("NotificationComponent", NotificationComponent);
+```
+
+## Example App
+
+The dummy Rails app includes a working counter component. See
+[examples/README.md](examples/README.md) for the files and local run command.
+
 ## Lifecycle
 
-- `setup` runs after `turbo:load` and after new matching DOM nodes are inserted.
-- `teardown` runs before Turbo renders a new page.
-- `rootElement()` returns the DOM element for the component id.
-- `rootNode()` is an alias for `rootElement()`.
-- `rootElementSelector()` returns a CSS selector for the component id.
+- `setup()` runs after `turbo:load` and after new matching DOM nodes are inserted.
+- `teardown()` runs before Turbo renders a new page.
+- `setup()` and `teardown()` are called once per registered component instance.
+- Components that attach listeners, timers, observers, subscriptions, or widgets
+  should clean them up in `teardown()`.
+
+## API Reference
+
+### `Application`
+
+The top-level Achilles application object.
+
+```js
+import { Application } from "achilles/application/application";
+
+const achilles = new Application();
+achilles.start();
+```
+
+Useful properties:
+
+- `componentsClassMapper`: register component classes by name.
+- `componentRegistry`: inspect or manage registered component instances.
+- `timezone`: access the configured app timezone.
+
+Call `start()` after registering component classes. Call `stop()` when an
+application instance should remove its Turbo hooks and stop observing the DOM.
+
+### `ComponentsClassMapper`
+
+Maps `data-component-class` values to JavaScript classes.
+
+```js
+achilles.componentsClassMapper.addComponentClass("MenuComponent", MenuComponent);
+```
+
+### `ComponentBase`
+
+Base class for application components.
+
+```js
+import { ComponentBase } from "achilles/components/component_base";
+
+class MenuComponent extends ComponentBase {
+  setup() {}
+  teardown() {}
+}
+```
+
+Useful methods:
+
+- `setup()`: override to initialize behavior.
+- `teardown()`: override to clean up behavior before Turbo renders a new page.
+- `rootElement()`: returns the component root DOM element.
+- `rootNode()`: alias for `rootElement()`.
+- `rootElementSelector()`: returns a CSS selector for the component id.
+
+### Component Markup
+
+```erb
+<div id="account-menu" data-component-class="MenuComponent"></div>
+```
+
+The `data-component-class` value must match a class registered with
+`componentsClassMapper`.
 
 ## Timezone
 
@@ -93,18 +232,67 @@ value through `achilles.timezone.timezoneString`.
 
 If no timezone is present, Achilles falls back to `Etc/UTC`.
 
+## Upgrading From 0.1.3
+
+Achilles `1.0.0` changes `rootElement()` to return a DOM element. It no longer
+returns a jQuery object when `window.$` is present.
+
+Old jQuery-style code:
+
+```js
+this.rootElement().addClass("is-open");
+```
+
+Use DOM APIs:
+
+```js
+this.rootElement().classList.add("is-open");
+```
+
+Or wrap explicitly if the application still uses jQuery:
+
+```js
+$(this.rootElement()).addClass("is-open");
+```
+
+Applications upgrading Achilles should start with the
+[upgrade guide](docs/upgrading.md). Applications upgrading from `0.1.3` should
+also read the [v1 migration guide](docs/migrating-from-0.1.3-to-v1.md).
+
 ## Contributing
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test commands, pull request
+guidelines, and release notes. Project participation is covered by the
+[code of conduct](CODE_OF_CONDUCT.md). Maintainer responsibilities are described
+in [MAINTAINERS.md](MAINTAINERS.md).
+
 Run the test suite with:
 
 ```bash
 bin/rails test
 ```
 
-## Migration
+Run the browser system test with:
+
+```bash
+bin/rails test:system
+```
+
+Run the JavaScript syntax check with:
+
+```bash
+for file in $(find app/javascript/achilles -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+```
+
+Run the dummy app asset precompile check with:
+
+```bash
+RAILS_ENV=test bin/rails app:assets:precompile
+```
+
+## Security
 
-Applications upgrading from `0.1.3` should read the
-[v1 migration guide](docs/migrating-from-0.1.3-to-v1.md).
+Report security issues privately. See [SECURITY.md](SECURITY.md).
 
 ## License
 

data/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest minor release of Achilles `1.x` receives security fixes.
+
+| Version | Supported |
+| --- | --- |
+| `1.x` | Yes |
+| `< 1.0` | No |
+
+## Reporting A Vulnerability
+
+Please do not open a public GitHub issue for security vulnerabilities.
+
+Report security issues by email:
+
+```text
+jey@jeygeethan.com
+```
+
+Include:
+
+- affected Achilles version
+- Rails version
+- Ruby version
+- a description of the vulnerability
+- reproduction steps or proof of concept
+- whether the issue is already public
+
+## Response Expectations
+
+You should receive an acknowledgement within 7 days.
+
+If the issue is confirmed, the fix will be prepared privately when practical and
+released with a changelog entry that gives users enough information to upgrade
+without exposing unnecessary exploit details before a fix is available.
+
+## Scope
+
+Security reports are most useful when they involve Achilles behavior directly,
+including:
+
+- unsafe DOM lifecycle behavior
+- asset/importmap packaging issues
+- Rails engine integration issues
+- behavior that could cause applications to execute unintended JavaScript
+
+General application security issues in apps that use Achilles should be reported
+to those applications instead.

data/app/javascript/achilles/application/application.js

@@ -16,6 +16,7 @@ class Application {
   _componentsClassMapper;
   _hooksManager;
   _domMutationObserver;
+  _started = false;
 
   constructor() {
     // Set the application while creating the object
@@ -53,12 +54,45 @@ class Application {
     return this._page;
   }
 
+  get strictLifecycleErrors() {
+    return this.componentRegistry.strictLifecycleErrors;
+  }
+
   // Setters
   set engine(engine) {
     this._engine = engine;
   }
 
+  set strictLifecycleErrors(value) {
+    this.componentRegistry.strictLifecycleErrors = value;
+  }
+
+  start() {
+    if (this._started) {
+      return;
+    }
+
+    this._started = true;
+    this._hooksManager.start();
+    this.setup();
+  }
+
+  stop() {
+    if (!this._started) {
+      return;
+    }
+
+    this._started = false;
+    this._hooksManager.stop();
+    this.teardown();
+    this._domMutationObserver.stop();
+  }
+
   setup() {
+    if (!this._started) {
+      return;
+    }
+
     this._domMutationObserver.stop();
     this.parseHtmlAndRegisterComponents();
     this.componentRegistry.callSetupForComponent(AppConstants.PageComponentId);
@@ -71,7 +105,10 @@ class Application {
     this.componentRegistry.callTeardownForComponent(AppConstants.PageComponentId);
     // Remove/deregister all components from page except Page
     this.deregisterAllComponentsExceptPage();
-    this._domMutationObserver.start();
+
+    if (this._started) {
+      this._domMutationObserver.start();
+    }
   }
 
   parseHtmlAndRegisterComponents() {

data/app/javascript/achilles/application/dom-mutation-observer/observer.js

@@ -1,6 +1,7 @@
 class Observer {
   _mutationObserver;
   _callback;
+  _callbackScheduled = false;
 
   constructor(callback) {
     this._callback = callback;
@@ -18,10 +19,19 @@ class Observer {
 
   stop() {
     this._mutationObserver.disconnect();
+    this._callbackScheduled = false;
   }
 
   domChangedCallback(mutationsList, observer) {
-    this._callback();
+    if (this._callbackScheduled) {
+      return;
+    }
+
+    this._callbackScheduled = true;
+    queueMicrotask(() => {
+      this._callbackScheduled = false;
+      this._callback();
+    });
   }
 }
 

data/app/javascript/achilles/application/hooks-manager/turbo.js

@@ -2,25 +2,46 @@ class Turbo {
   _application;
   _setupCallback;
   _teardownCallback;
+  _setupHandler;
+  _teardownHandler;
+  _started = false;
 
   constructor(application, setupCallback, teardownCallback) {
     this._application = application;
     this._setupCallback = setupCallback;
     this._teardownCallback = teardownCallback;
-
-    this.setupEvents();
   }
 
   // Setups relevant hooks to the page for component lifecycles. This depends on the framework being used.
   // Here we are using turbo drive, so hooking into that.
-  setupEvents() {
-    document.addEventListener("turbo:load", () => {
+  start() {
+    if (this._started) {
+      return;
+    }
+
+    this._setupHandler = () => {
       this._setupCallback();
-    });
+    };
 
-    document.addEventListener("turbo:before-render", () => {
+    this._teardownHandler = () => {
       this._teardownCallback();
-    });
+    };
+
+    document.addEventListener("turbo:load", this._setupHandler);
+    document.addEventListener("turbo:before-render", this._teardownHandler);
+    this._started = true;
+  }
+
+  stop() {
+    if (!this._started) {
+      return;
+    }
+
+    document.removeEventListener("turbo:load", this._setupHandler);
+    document.removeEventListener("turbo:before-render", this._teardownHandler);
+    this._setupHandler = null;
+    this._teardownHandler = null;
+    this._started = false;
   }
 }
 

data/app/javascript/achilles/components/component_base.js

@@ -2,8 +2,7 @@ class ComponentBase {
     parentComponentId;
     id;
     defaultParams;
-    setupExecuted = false;
-    teardownExecuted = false;
+    mounted = false;
 
     constructor(id, parentComponentId = 'Page', defaultParams = []) {
         this.id = id;
@@ -17,6 +16,24 @@ class ComponentBase {
     setup() {}
     teardown() {}
 
+    get setupExecuted() {
+        return this.mounted;
+    }
+
+    set setupExecuted(value) {
+        this.mounted = value;
+    }
+
+    get teardownExecuted() {
+        return !this.mounted;
+    }
+
+    set teardownExecuted(value) {
+        if(value === true) {
+            this.mounted = false;
+        }
+    }
+
     rootElement() {
         return this.rootNode();
     }

data/app/javascript/achilles/components/component_parser.js

@@ -11,6 +11,10 @@ class ComponentParser {
         [...document.querySelectorAll('[data-component-class]')].forEach((elem) => {
             let klassName = elem.dataset.componentClass;
             if(klassName.trim() === '') { return; }
+            if(!this.hasValidId(elem)) {
+                console.error(`Component root element is missing an id. className: ${klassName} | Element:`, elem);
+                return;
+            }
 
             let klass = this._componentsClassMapper.getComponentClass(klassName);
             if(typeof klass === 'undefined' || klass === null) {
@@ -22,7 +26,7 @@ class ComponentParser {
                 return;
             }
             try {
-                let obj = new klass(elem.id, AppConstants.PageComponentId)
+                let obj = new klass(elem.id, this.parentComponentIdFor(elem))
                 this._componentRegistry.registerComponentByObj(obj);
             } catch (e) {
                 console.error(`Error parsing component. className: ${klassName} | Element ID: ${elem.id}`);
@@ -31,6 +35,22 @@ class ComponentParser {
             }
         })
     }
+
+    hasValidId(elem) {
+        return typeof elem.id === 'string' && elem.id.trim() !== '';
+    }
+
+    parentComponentIdFor(elem) {
+        let parent = elem.parentElement;
+        while(parent) {
+            if(parent.dataset?.componentClass && this.hasValidId(parent)) {
+                return parent.id;
+            }
+            parent = parent.parentElement;
+        }
+
+        return AppConstants.PageComponentId;
+    }
 }
 
 export { ComponentParser };

data/app/javascript/achilles/components/components_registry.js

@@ -3,6 +3,7 @@ import { AppConstants } from "achilles/application/app_constants";
 // Contains all the registered components in a page at the current moment
 class ComponentsRegistry {
     _registeredComponents = {};
+    strictLifecycleErrors = false;
 
     matchingElementsForId(id) {
         return [...document.querySelectorAll('[id]')].filter((elem) => elem.id === id);
@@ -25,6 +26,14 @@ class ComponentsRegistry {
             // Component is already registered. So have to call deregister and teardown
             this.teardownAndDeregister(id);
         }
+        let parentComponent = null;
+        if(parentComponentId != null) {
+            parentComponent = this.getRegisteredComponent(parentComponentId);
+            if(!parentComponent) {
+                console.error(`Parent component not found while registering component. id: ${id} | parentComponentId: ${parentComponentId}. Skipping registering component`);
+                return;
+            }
+        }
 
         this._registeredComponents[id] = {
             id: id,
@@ -34,7 +43,6 @@ class ComponentsRegistry {
             subComponents: []
         };
         if(parentComponentId != null) {
-            let parentComponent = this.getRegisteredComponent(parentComponentId);
             parentComponent.subComponents.push(id);
         }
         this.elementForId(id)?.setAttribute('data-component-registered', 'true');
@@ -51,7 +59,7 @@ class ComponentsRegistry {
             parentComponent.subComponents = parentComponent.subComponents.filter(item => item !== id);
         }
 
-        this._registeredComponents[id] = null;
+        delete this._registeredComponents[id];
         this.elementForId(id)?.removeAttribute('data-component-registered');
     }
 
@@ -68,13 +76,13 @@ class ComponentsRegistry {
             return;
         }
 
-        // Call the objs default setup if its not executed already, if not skip to their children
-        if(component.obj.setup && component.obj.setupExecuted === false) {
+        // Call the objs default setup if it is not mounted already, then continue to children
+        if(component.obj.setup && component.obj.mounted === false) {
             try{
                 component.obj.setup(...component.defaultParams);
-                component.obj.setupExecuted = true;
+                component.obj.mounted = true;
             } catch(e) {
-                console.error(e);
+                this.handleLifecycleError(e);
             }
         }
 
@@ -89,20 +97,28 @@ class ComponentsRegistry {
         if(!component || !component.obj)
             return;
 
-        // Call the objs default teardown if not already executed, otherwise skip to its children
-        if(component.obj.teardown && component.obj.teardownExecuted === false) {
+        // Call teardown for all sub view_components before their parent
+        component.subComponents.forEach((subComponentId) => {
+            this.callTeardownForComponent(subComponentId);
+        });
+
+        // Call the objs default teardown if it is currently mounted
+        if(component.obj.teardown && component.obj.mounted === true) {
             try{
                 component.obj.teardown(...component.defaultParams);
-                component.obj.teardownExecuted = true;
+                component.obj.mounted = false;
             } catch(e) {
-                console.error(e);
+                this.handleLifecycleError(e);
             }
         }
+    }
 
-        // Call teardown for all sub view_components
-        component.subComponents.forEach((subComponentId) => {
-            this.callTeardownForComponent(subComponentId);
-        });
+    handleLifecycleError(error) {
+        console.error(error);
+
+        if(this.strictLifecycleErrors) {
+            throw error;
+        }
     }
 
     teardownAndDeregister(id) {

data/docs/core-js-gaps.md

@@ -0,0 +1,26 @@
+# Core JavaScript Gaps
+
+This is the current improvement backlog for Achilles core JavaScript. API
+reference docs should wait until the structure settles.
+
+## Completed
+
+- Added an explicit `Application#start` and `Application#stop` lifecycle.
+- Made Turbo event listeners removable.
+- Validated that component roots have non-empty ids before registration.
+- Changed teardown order so child components tear down before parent components.
+- Deleted deregistered registry entries instead of leaving `null` tombstones.
+- Batched mutation observer setup work with a microtask debounce.
+- Replaced one-way lifecycle flags with a `mounted` state while keeping
+  `setupExecuted` and `teardownExecuted` as compatibility aliases.
+- Added tests for missing ids, duplicate starts, listener cleanup,
+  child-before-parent teardown, dynamic insertion batching, deregistration, and
+  remounting a reused component instance.
+- Chose a DOM ancestry model for nested components under the single synthetic
+  `Page` root.
+- Split JavaScript tests by parser, registry, application, Turbo hooks, and
+  component base responsibility.
+- Added package/file-list regression coverage for the gemspec.
+- Added opt-in strict lifecycle error handling for tests and development.
+
+## Remaining Priority Gaps

data/docs/release-checklist.md

@@ -11,7 +11,8 @@ Use this checklist for `1.0.0.rc1` and future releases.
 
 ```bash
 bin/rails test
-for file in $(find app/javascript/achilles -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
+bin/rails test:system
+for file in $(find app/javascript/achilles test/dummy/app/javascript -name '*.js' -print); do node --input-type=module --check < "$file" || exit 1; done
 RAILS_ENV=test bin/rails app:assets:precompile
 ```
 

data/docs/upgrading-to-1.1.0.md

@@ -0,0 +1,144 @@
+# Upgrading To 1.1.0
+
+This guide covers application-facing changes in Achilles `1.1.0`.
+
+## Application Startup
+
+Achilles applications must now be started explicitly.
+
+Before:
+
+```js
+import { Application } from "achilles/application/application";
+import { MenuComponent } from "components/menu_component";
+
+const achilles = new Application();
+achilles.componentsClassMapper.addComponentClass("MenuComponent", MenuComponent);
+```
+
+After:
+
+```js
+import { Application } from "achilles/application/application";
+import { MenuComponent } from "components/menu_component";
+
+const achilles = new Application();
+achilles.componentsClassMapper.addComponentClass("MenuComponent", MenuComponent);
+achilles.start();
+```
+
+Call `start()` after registering component classes. This lets applications
+control when Achilles parses the DOM and attaches Turbo lifecycle hooks.
+
+## Stopping An Application
+
+Applications that create temporary Achilles instances can now call:
+
+```js
+achilles.stop();
+```
+
+`stop()` removes Turbo lifecycle hooks and stops observing DOM mutations.
+
+Most Rails applications only need one long-lived Achilles instance and do not
+need to call `stop()` manually.
+
+## Search Checklist
+
+In each application, search for Achilles construction:
+
+```bash
+rg "new Application"
+```
+
+For every application instance, confirm component classes are registered before
+calling `start()`.
+
+## Component Root Ids
+
+Every element with `data-component-class` must have a non-empty `id`.
+
+Before:
+
+```erb
+<div data-component-class="MenuComponent"></div>
+```
+
+After:
+
+```erb
+<div id="menu" data-component-class="MenuComponent"></div>
+```
+
+Achilles uses component root ids as registry keys. Components without ids are
+skipped and reported in the browser console.
+
+Search for component roots without ids:
+
+```bash
+rg "data-component-class"
+```
+
+## Nested Components
+
+Achilles now builds the component tree from DOM ancestry.
+
+- `Page` remains the single synthetic root component.
+- A component's parent is its nearest ancestor element with
+  `data-component-class`.
+- If no component ancestor exists, the parent is `Page`.
+
+For example:
+
+```erb
+<div id="dashboard" data-component-class="DashboardComponent">
+  <div id="filters" data-component-class="FiltersComponent"></div>
+</div>
+```
+
+The component tree is:
+
+```text
+Page
+dashboard
+filters
+```
+
+## Teardown Order
+
+Component teardown now runs from children to parents.
+
+Before this change, a parent component's `teardown()` could run before its child
+components. Now child components clean up first, and the parent cleans up after
+its subtree.
+
+Review parent components whose `teardown()` removes DOM nodes, shared event
+targets, third-party widgets, or state that child components also use during
+cleanup.
+
+## Strict Lifecycle Errors
+
+By default, Achilles logs `setup()` and `teardown()` errors and keeps the page
+running.
+
+Tests and development environments can opt into strict lifecycle errors:
+
+```js
+const achilles = new Application();
+achilles.strictLifecycleErrors = true;
+```
+
+When strict mode is enabled, `setup()` and `teardown()` errors are still logged
+and then re-raised.
+
+## Manual Test Checklist
+
+After updating an application:
+
+- boot the app
+- open a page with Achilles components
+- confirm component `setup()` methods run
+- navigate with Turbo to another page and back
+- confirm `teardown()` still runs before Turbo renders a new page
+- insert any dynamic component markup the app supports
+- check the browser console for Achilles errors

data/docs/upgrading.md

@@ -0,0 +1,26 @@
+# Upgrading Achilles
+
+Use this page as the entry point for application upgrades.
+
+Achilles should have an upgrade note for every release that changes application
+setup, component markup, lifecycle behavior, or public APIs.
+
+## Current Upgrade Notes
+
+- [Upgrading to 1.1.0](upgrading-to-1.1.0.md)
+- [Migrating from 0.1.3 to v1](migrating-from-0.1.3-to-v1.md)
+
+## Upgrade Policy
+
+Before upgrading an existing application:
+
+1. Read the guide for the target version.
+2. Upgrade one application first.
+3. Run the application's test suite.
+4. Visit pages with Achilles components.
+5. Verify Turbo navigation and dynamically inserted components.
+6. Check the browser console for lifecycle, missing component class, or duplicate
+   id errors.
+
+For breaking changes, prefer testing a release candidate in a real application
+before upgrading every project.

data/lib/achilles/version.rb

@@ -1,3 +1,3 @@
 module Achilles
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/achilles.rb

@@ -1,5 +1,6 @@
 require "achilles/version"
 require "importmap-rails"
+require "turbo-rails"
 require "achilles/engine"
 
 module Achilles

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: achilles
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Jey Geethan
@@ -60,9 +60,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- MAINTAINERS.md
 - MIT-LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - app/assets/config/achilles/manifest.js
 - app/assets/stylesheets/achilles/application.css
 - app/controllers/achilles/application_controller.rb
@@ -83,8 +87,11 @@ files:
 - app/views/layouts/achilles/application.html.erb
 - config/importmap.rb
 - config/routes.rb
+- docs/core-js-gaps.md
 - docs/migrating-from-0.1.3-to-v1.md
 - docs/release-checklist.md
+- docs/upgrading-to-1.1.0.md
+- docs/upgrading.md
 - docs/v1-roadmap.md
 - lib/achilles.rb
 - lib/achilles/engine.rb