feat: implement return init from lifecycle onMount

[kanashimia]

Description

Adds this:

<lifecycle
  onMount() {
    let map = new WorldMap();
    return { map };
  }
  onUpdate() {
    this.map.setCoords(latitude, longitude);
    this.map.setZoom(zoom);
  }
  onDestroy() {
    this.map.destroy();
  }
/>

Please verify that all this is good.

Also adds debug validation for property reassignment.

Haven't been able to fix this problem:

<lifecycle
  onMount() {
    this.foo // <-- this will typecheck
    return { foo: true };
  }
>

Checklist:

• I have read the CONTRIBUTING document and have signed (or will sign) the CLA.
• I have updated/added documentation affected by my changes.
• I have added tests to cover my changes.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8cc1c93

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@marko/runtime-tags	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

Adds new test fixtures for lifecycle-tag-property-overwrite-error and lifecycle-tag-return-init. Updates _lifecycle in dom.ts so onMount may return a props object that is merged into the instance via Object.assign. In debug builds a pre-merge snapshot of the instance is taken and any returned property that would overwrite an existing property triggers a thrown error. Existing lifecycle wiring (abort handling and update handlers) remains unchanged.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main feature being implemented: allowing lifecycle onMount handlers to return initial state.
Description check	✅ Passed	The description clearly relates to the changeset, providing concrete examples of the feature and noting additional debug validation added.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/runtime-tags/src/dom/dom.ts (1)

400-414: Clarify debug snapshot variable and intent

The new onMount-return handling and debug check logic look sound and align with the described behavior (merge returned props, then fail fast if any existing key’s value changed).

Minor polish: consider renaming shapshot to snapshot on Line 400/402 for clarity and to avoid confusion when revisiting this code.

-    let shapshot = undefined;
+    let snapshot = undefined;
@@
-      shapshot = Object.assign({}, thisObj);
+      snapshot = Object.assign({}, thisObj);
@@
-      for (const [prop, prevVal] of Object.entries(shapshot!)) {
+      for (const [prop, prevVal] of Object.entries(snapshot!)) {

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d88b422 and 6863183.

⛔ Files ignored due to path filters (18)

• .changeset/eager-pets-grin.md is excluded by none and included by none
• .sizes.json is excluded by none and included by none
• .sizes/dom.js is excluded by none and included by none
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/csr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/csr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/dom.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/html.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/.name-cache.json is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/csr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/csr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/dom.expected/template.hydrate.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/dom.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/html.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/resume-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/resume.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/ssr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/ssr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/tags/lifecycle.d.marko is excluded by none and included by none

📒 Files selected for processing (5)

• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/template.marko (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/template.marko (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/test.ts (1 hunks)
• packages/runtime-tags/src/dom/dom.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1)

packages/runtime-tags/src/__tests__/utils/resolve.ts (1)

• wait (4-8)

🔇 Additional comments (4)

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/template.marko (1)

1-13: Fixture correctly exercises return-init lifecycle behavior

The template cleanly covers the new semantics (onMount returning init props merged into this and onUpdate reflecting state), and the DOM wiring via #ref/#increment matches the intended test scenario.

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/test.ts (1)

1-5: Test harness wiring looks consistent

steps and increment follow the existing fixture pattern (container-driven click), and declaration order is fine since increment is a function declaration.

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/template.marko (1)

1-6: Good minimal fixture for overwrite detection

This compact template is a clear repro for the “mutate existing property in onMount” case and should reliably exercise the new debug error path.

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1)

1-6: Runtime error test configuration looks appropriate

The steps + wait(1) pattern, along with error_runtime and skip_ssr, fits the intended “expect a client-side lifecycle error” scenario for this fixture.

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/runtime-tags/src/dom/dom.ts (1)

385-393: Fix the type signature for onMount to reflect the return value.

The type signature declares onMount?: (this: unknown) => void but Line 404 captures and uses its return value to merge properties into the instance. This type mismatch will cause incorrect type inference.

Apply this diff to fix the type signature:

 export function _lifecycle(
   scope: Scope,
   index: string | number,
   thisObj: Record<string, unknown> & {
-    onMount?: (this: unknown) => void;
+    onMount?: (this: unknown) => Record<string, unknown> | void;
     onUpdate?: (this: unknown) => void;
     onDestroy?: (this: unknown) => void;
   },
 ) {

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6863183 and 66d58a2.

⛔ Files ignored due to path filters (18)

• .changeset/eager-pets-grin.md is excluded by none and included by none
• .sizes.json is excluded by none and included by none
• .sizes/dom.js is excluded by none and included by none
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/csr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/csr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/dom.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/html.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/.name-cache.json is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/csr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/csr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/dom.expected/template.hydrate.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/dom.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/html.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/resume-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/resume.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/ssr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/ssr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/tags/lifecycle.d.marko is excluded by none and included by none

📒 Files selected for processing (5)

• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/template.marko (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/template.marko (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/test.ts (1 hunks)
• packages/runtime-tags/src/dom/dom.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/runtime-tags/src/tests/fixtures/lifecycle-tag-return-init/test.ts
• packages/runtime-tags/src/tests/fixtures/lifecycle-tag-property-overwrite-error/template.marko
• packages/runtime-tags/src/tests/fixtures/lifecycle-tag-return-init/template.marko

🧰 Additional context used

🧬 Code graph analysis (1)

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1)

packages/runtime-tags/src/__tests__/utils/resolve.ts (1)

• wait (4-8)

🔇 Additional comments (2)

packages/runtime-tags/src/dom/dom.ts (1)

406-414: Clarify: validation catches both return-value overwrites AND direct mutations.

The validation loop compares the pre-onMount snapshot with the post-Object.assign state, so it will throw an error if:

1. onMount returns a property that already exists in thisObj, OR
2. onMount directly mutates an existing property (e.g., this.x = newValue) before returning

If the intent is to only prevent overwrites from the return value, the current logic is too broad. If both cases should be prevented, the error message should clarify this.

Consider whether direct mutations within onMount should be allowed. If they should be allowed, the validation needs to compare snapshot with thisObj before the Object.assign, not after.

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1)

1-6: LGTM!

The test configuration correctly sets up a runtime error test case. The error_runtime flag indicates an error is expected during execution, and skip_ssr is appropriate since lifecycle hooks only run on the client. The minimal steps with a short wait allows the error to be caught by the test harness.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.69%. Comparing base (9c3f20a) to head (66d58a2).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2957      +/-   ##
==========================================
+ Coverage   88.40%   88.69%   +0.29%     
==========================================
  Files         373      373              
  Lines       46692    46752      +60     
  Branches     3871     3909      +38     
==========================================
+ Hits        41276    41466     +190     
+ Misses       5373     5241     -132     
- Partials       43       45       +2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 0

♻️ Duplicate comments (1)

packages/runtime-tags/src/dom/dom.ts (1)

400-414: Validate onMount’s return value before Object.assign to avoid surprising merges

Right now const newProps = thisObj.onMount?.(); Object.assign(thisObj, newProps); will happily merge anything that’s object-coercible: arrays, functions, boxed primitives, etc. That can lead to very non-obvious state (e.g. index keys from arrays/strings) and makes it harder to reason about what shapes thisObj can take after mount.

Given this is user-authored code like:

onMount(() => {
  // …
  return someValue;
})

it would be safer to treat anything other than undefined or a plain object as invalid in debug builds, and either:

• Throw a clear error, or
• Ignore the value (and maybe log/warn) rather than merging it.

This also aligns nicely with your overwrite check: it keeps the invariant that only a shallow, plain object of new fields may be added from onMount, and avoids weird interactions from accidentally returning an array or other non-plain object.

Since a similar concern was already raised on a previous revision, this is effectively reinforcing that feedback for the current version of the code.

🧹 Nitpick comments (1)

packages/runtime-tags/src/dom/dom.ts (1)

388-392: Consider tightening lifecycle this typing to better reflect thisObj

Right now the lifecycle handlers are typed as this: unknown, while thisObj is a Record<string, unknown> & { … }. That forces users into casts if they want strongly typed access to the properties you’re now allowing onMount to initialize.

Not for this PR, but as a follow-up it may be worth:

• Making _lifecycle generic over the instance shape, and
• Typing this for onMount / onUpdate / onDestroy as that generic, so the compiler can help more with the “return-init” pattern you’re introducing.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 66d58a2 and 8cc1c93.

⛔ Files ignored due to path filters (18)

• .changeset/eager-pets-grin.md is excluded by none and included by none
• .sizes.json is excluded by none and included by none
• .sizes/dom.js is excluded by none and included by none
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/csr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/csr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/dom.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/__snapshots__/html.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/.name-cache.json is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/csr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/csr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/dom.expected/template.hydrate.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/dom.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/html.expected/template.js is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/resume-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/resume.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/ssr-sanitized.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/__snapshots__/ssr.expected.md is excluded by !**/__snapshots__/** and included by **/src/**
• packages/runtime-tags/tags/lifecycle.d.marko is excluded by none and included by none

📒 Files selected for processing (5)

• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/template.marko (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/template.marko (1 hunks)
• packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-return-init/test.ts (1 hunks)
• packages/runtime-tags/src/dom/dom.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/runtime-tags/src/tests/fixtures/lifecycle-tag-return-init/test.ts
• packages/runtime-tags/src/tests/fixtures/lifecycle-tag-property-overwrite-error/template.marko
• packages/runtime-tags/src/tests/fixtures/lifecycle-tag-return-init/template.marko

🧰 Additional context used

🧬 Code graph analysis (1)

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1)

packages/runtime-tags/src/__tests__/utils/resolve.ts (1)

• wait (4-8)

🔇 Additional comments (1)

packages/runtime-tags/src/__tests__/fixtures/lifecycle-tag-property-overwrite-error/test.ts (1)

1-6: Fixture wiring looks correct for a runtime-only error case

Import, steps shape, and the error_runtime/skip_ssr flags all match the existing test-fixture pattern for client-only runtime errors; nothing to fix here.