NativeScript · NathanWalker · Aug 9, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.agent/skills/feat/SKILL.md b/.agent/skills/feat/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: feat
+description: Build a feature or enhancement end-to-end (GitHub issue or free-text description → plan → implement → test → PR). Use anytime you need to add functionality to a package in this workspace.
+argument-hint: [issue-number-or-description]
+---
+
+# Feature Workflow
+
+Conventions this workflow depends on (read the ones your change touches before writing code):
+
+- [CorePlatformModules.md](./references/CorePlatformModules.md) — required before touching `packages/core` (platform-split files, handwritten `.d.ts`).
+- [CodeComments.md](./references/CodeComments.md) — comment rules for all TypeScript edits.
+- [WritingUnitTests.md](./references/WritingUnitTests.md) — test expectations and environment constraints.
+- [CONTRIBUTING.md](./references/CONTRIBUTING.md) — commit message format.
+
+## Phase 1: Understand
+
+- If given a GitHub issue number, fetch it: `gh issue view <number> --json title,body,labels,comments`. Otherwise treat the input as a free-text description; if empty, ask for one.
+- Summarize the user-facing goal, acceptance criteria, and edge cases before touching code.
+
+## Phase 2: Ground in the codebase
+
+- Find an existing module or feature similar to what you are building and use it as the pattern to follow — reference it by path in your plan.
+- Map the touch surface: which package, which modules, and for `packages/core` whether the change lands in `-common.ts`, both platform files, or all three — plus the neighboring `.d.ts`.
+
+## Phase 3: Plan
+
+Present a short plan before implementing: files to create/edit with a one-liner each, the test strategy, and any public API changes (these require `.d.ts` updates). Prefer the simplest solution that reuses existing patterns.
+
+## Phase 4: Implement
+
+- Follow the referenced conventions. Keep `.ios.ts` / `.android.ts` in parity; never leave one side diverged.
+- Public API changes update the neighboring `.d.ts` in the same change, with JSDoc in the `.d.ts`.
+
+## Phase 5: Test
+
+- Add or extend colocated `*.spec.ts` specs for shared-logic changes.
+- Run the focused tests first (`npx nx run core:test -t 'Name'`), then the full package target (`npx nx run core:test`) — it must be green.
+- Behavior that needs the real native runtime is covered in `apps/automated`, not unit tests; note it for the PR's manual test scenarios instead.
+
+## Phase 6: Finish
+
+- Format: `npx nx format:write`.
+- Commit with the conventional format, e.g. `feat(core): <subject>`.
+- Open the PR with `gh`, following [the PR template](../../../.github/PULL_REQUEST_TEMPLATE.md): reference the issue and include tests for the change.
diff --git a/.agent/skills/feat/references/CONTRIBUTING.md b/.agent/skills/feat/references/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../../../tools/notes/CONTRIBUTING.md
diff --git a/.agent/skills/feat/references/CodeComments.md b/.agent/skills/feat/references/CodeComments.md
@@ -0,0 +1 @@
+../../../../tools/notes/CodeComments.md
diff --git a/.agent/skills/feat/references/CorePlatformModules.md b/.agent/skills/feat/references/CorePlatformModules.md
@@ -0,0 +1 @@
+../../../../tools/notes/CorePlatformModules.md
diff --git a/.agent/skills/feat/references/WritingUnitTests.md b/.agent/skills/feat/references/WritingUnitTests.md
@@ -0,0 +1 @@
+../../../../tools/notes/WritingUnitTests.md
diff --git a/.agent/skills/fix/SKILL.md b/.agent/skills/fix/SKILL.md
@@ -0,0 +1,45 @@
+---
+name: fix
+description: Debug and fix a bug end-to-end (GitHub issue or free-text report → trace → root cause → fix → test → PR). Use anytime you need to fix broken, throwing, or misbehaving code in this workspace.
+argument-hint: [issue-number-or-description]
+---
+
+# Bug Fix Workflow
+
+Conventions this workflow depends on (read the ones your change touches before writing code):
+
+- [CorePlatformModules.md](./references/CorePlatformModules.md) — required before touching `packages/core` (platform-split files, handwritten `.d.ts`).
+- [CodeComments.md](./references/CodeComments.md) — comment rules for all TypeScript edits.
+- [WritingUnitTests.md](./references/WritingUnitTests.md) — test expectations and environment constraints.
+- [CONTRIBUTING.md](./references/CONTRIBUTING.md) — commit message format.
+
+## Phase 1: Get the bug
+
+- If given a GitHub issue number, fetch it: `gh issue view <number> --json title,body,labels,comments`. Otherwise collect the report from the user.
+- Extract the reproduction steps, environment (platform, versions), and any stack trace or error message — these point at the files to read first.
+
+## Phase 2: Trace the code path
+
+- Follow the failure from entry point to the error site. For `packages/core`, read BOTH platform files — a bug on one platform often means the implementations diverged.
+- Keep claims honest: distinguish what you proved by reading code (quote `file:line`) from what you suspect. Do not present a hunch as the root cause.
+
+## Phase 3: Root cause
+
+- Confirm the mechanism before fixing. When the logic is unit-testable, write a failing spec that reproduces the bug — it becomes the proof and the regression guard.
+- Grep for the same pattern elsewhere in the package; a bug rarely lives in only one place. List every instance found.
+
+## Phase 4: Fix
+
+- Apply the smallest change that fixes the root cause, not the symptom. Fix all instances found in the spread check.
+- Keep `.ios.ts` / `.android.ts` in parity; if the fix changes a public API, update the neighboring `.d.ts` in the same change.
+
+## Phase 5: Verify
+
+- The failing spec from Phase 3 must go green, and the full package target (`npx nx run core:test`) must pass.
+- Behavior only observable on a real device/simulator belongs in `apps/automated`; note it for the PR's manual test scenarios.
+
+## Phase 6: Finish
+
+- Format: `npx nx format:write`.
+- Commit with the conventional format, e.g. `fix(core): <subject>`.
+- Open the PR with `gh`, following [the PR template](../../../.github/PULL_REQUEST_TEMPLATE.md): reference the issue and include the regression test.
diff --git a/.agent/skills/fix/references/CONTRIBUTING.md b/.agent/skills/fix/references/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../../../tools/notes/CONTRIBUTING.md
diff --git a/.agent/skills/fix/references/CodeComments.md b/.agent/skills/fix/references/CodeComments.md
@@ -0,0 +1 @@
+../../../../tools/notes/CodeComments.md
diff --git a/.agent/skills/fix/references/CorePlatformModules.md b/.agent/skills/fix/references/CorePlatformModules.md
@@ -0,0 +1 @@
+../../../../tools/notes/CorePlatformModules.md
diff --git a/.agent/skills/fix/references/WritingUnitTests.md b/.agent/skills/fix/references/WritingUnitTests.md
@@ -0,0 +1 @@
+../../../../tools/notes/WritingUnitTests.md
diff --git a/.agent/skills/refactor/SKILL.md b/.agent/skills/refactor/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: refactor
+description: Restructure existing code without changing behavior (scope → baseline tests → small verified steps → PR). Use anytime you need to clean up, reorganize, or simplify code in this workspace.
+argument-hint: [scope-or-description]
+---
+
+# Refactor Workflow
+
+Conventions this workflow depends on (read the ones your change touches before writing code):
+
+- [CorePlatformModules.md](./references/CorePlatformModules.md) — required before touching `packages/core` (platform-split files, handwritten `.d.ts`).
+- [CodeComments.md](./references/CodeComments.md) — comment rules for all TypeScript edits.
+- [WritingUnitTests.md](./references/WritingUnitTests.md) — test expectations and environment constraints.
+- [CONTRIBUTING.md](./references/CONTRIBUTING.md) — commit message format.
+
+## Phase 1: Scope
+
+- Define what is being restructured and, explicitly, what "unchanged behavior" means for it: same public API, same observable behavior on both platforms.
+- Public API changes are NOT refactors — if the `.d.ts` surface must change, stop and confirm the scope with the user first.
+
+## Phase 2: Baseline
+
+- Run the affected package's tests BEFORE touching anything (`npx nx run core:test`); they must be green.
+- Where the code being restructured has no spec coverage, add specs first to lock in current behavior — they are the safety net for every step that follows.
+
+## Phase 3: Restructure in small steps
+
+- Work in small, independently green steps; run the focused tests between steps.
+- Keep `.ios.ts` / `.android.ts` in parity at every step — moving shared logic into `-common.ts` is a common refactor here, and both platform files must be updated together.
+- Delete dead and commented-out code you uncover; do not carry it along.
+
+## Phase 4: Finish
+
+- Full package target green (`npx nx run core:test`), then format: `npx nx format:write`.
+- Commit with the conventional format, e.g. `refactor(core): <subject>`.
+- Open the PR with `gh`, following [the PR template](../../../.github/PULL_REQUEST_TEMPLATE.md); state that behavior is unchanged and how that was verified.
diff --git a/.agent/skills/refactor/references/CONTRIBUTING.md b/.agent/skills/refactor/references/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../../../tools/notes/CONTRIBUTING.md
diff --git a/.agent/skills/refactor/references/CodeComments.md b/.agent/skills/refactor/references/CodeComments.md
@@ -0,0 +1 @@
+../../../../tools/notes/CodeComments.md
diff --git a/.agent/skills/refactor/references/CorePlatformModules.md b/.agent/skills/refactor/references/CorePlatformModules.md
@@ -0,0 +1 @@
+../../../../tools/notes/CorePlatformModules.md
diff --git a/.agent/skills/refactor/references/WritingUnitTests.md b/.agent/skills/refactor/references/WritingUnitTests.md
@@ -0,0 +1 @@
+../../../../tools/notes/WritingUnitTests.md
diff --git a/.agent/skills/unit-testing/SKILL.md b/.agent/skills/unit-testing/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: unit-testing
+description: How to run and write unit tests in this workspace (Vitest, colocated .spec.ts files, mocked native globals). Use when writing, changing, or running tests.
+---
+
+# Unit Testing
+
+Tests are `*.spec.ts` files colocated with the source they cover, written with Vitest and run per package through Nx. See [WritingUnitTests.md](./references/WritingUnitTests.md) for the full guide.
+
+## Running
+
+```bash
+npx nx run core:test              # all core tests
+npx nx run core:test -t 'Name'    # isolate by describe/it name
+npx nx run core:test --watch      # watch mode
+```
+
+Use `-t` to run only the tests related to your change first; run the full package target before finishing.
+
+## Writing
+
+- Use the standard Vitest API (`describe`, `it`, `expect`, `beforeEach`, `vi`). Globals are enabled, so imports from `vitest` are optional — match the style of neighboring specs.
+- Place the spec next to the module: `packages/core/xml/index.spec.ts` covers `packages/core/xml/index.ts`.
+- Every behavior change in shared (non-platform-specific) logic should add or extend a spec.
+
+## Environment Constraints
+
+- Tests run in Node, not on a device. `packages/core/vitest.setup.ts` stubs the platform globals (`__IOS__`, `__ANDROID__`, minimal `NSObject`-style mocks) so modules can load — real iOS/Android APIs do NOT exist here.
+- If a test needs more native surface, extend the mocks in `vitest.setup.ts`; do not stub natives inline per spec.
+- Behavior that depends on the real native runtime cannot be unit tested — it belongs in the `apps/automated` e2e suite, which requires a simulator/emulator. Do not attempt to run it unless explicitly asked.
+- Keep tests deterministic: no network calls, no timing-sensitive assertions without fake timers (`vi.useFakeTimers()`).
diff --git a/.agent/skills/unit-testing/references/WritingUnitTests.md b/.agent/skills/unit-testing/references/WritingUnitTests.md
@@ -0,0 +1 @@
+../../../../tools/notes/WritingUnitTests.md
diff --git a/.claude/skills b/.claude/skills
@@ -0,0 +1 @@
+../.agent/skills
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,70 @@
+# AGENTS.md - NativeScript
+
+This is the source code for NativeScript — `@nativescript/core` and related packages. This guide outlines standard practices for AI agents working in this repository.
+
+## Environment
+
+- Use `npm` for package management. First-time setup: `npm run setup` (cleans and installs).
+- This is an [Nx](https://nx.dev) workspace. Run targets with `npx nx run <project>:<target>`, e.g. `npx nx run core:test`.
+- `npm start` opens an interactive menu of every workspace command (type to filter, ENTER to run). Each entry maps to an Nx command you can also run directly.
+
+## Repository Layout
+
+- `packages/core` — `@nativescript/core`, the framework itself (UI, styling, application lifecycle, native bridging).
+- `packages/webpack5` — `@nativescript/webpack` build tooling.
+- `packages/vite` — `@nativescript/vite` build tooling.
+- `packages/types-ios`, `packages/types-android`, `packages/types-minimal`, `packages/types` — native platform TypeScript declarations.
+- `packages/ui-mobile-base` — native (Java/Objective-C) UI base components.
+- `packages/winter-tc` — WinterTC (web-interoperable runtime) compliance.
+- `apps/toolbox` — preferred playground for local development and debugging core. Simple; use this most often.
+- `apps/automated` — automated e2e test suite that runs on a device/simulator.
+- `apps/ui` — more sophisticated test app for UI scenarios.
+
+## Key Documentation
+
+- [Development Workflow](tools/notes/DevelopmentWorkflow.md): definitive guide for setup, running tests, and test apps.
+- [Coding Conventions](tools/notes/CodingConvention.md): style guide (tabs width 2, single quotes, semicolons, same-line braces).
+- [Code Comments](tools/notes/CodeComments.md): comment rules for all TypeScript edits (minimal, JSDoc on public API only).
+- [Core Platform Modules](tools/notes/CorePlatformModules.md): required reading before touching `packages/core` modules (`.ios.ts`/`.android.ts` split, handwritten `.d.ts`).
+- [Contributing / Commit Guidelines](tools/notes/CONTRIBUTING.md): commit message format used to generate changelogs.
+- [Writing Unit Tests](tools/notes/WritingUnitTests.md): expectations for test coverage with changes.
+
+## Agent Skills
+
+Repository skills live in `.agent/skills/<skill-name>/SKILL.md` — each is a workflow for one kind of task (feat, fix, refactor, ...), with YAML frontmatter (`name`, `description`). Before starting a task a skill's description covers, read that SKILL.md and follow it. (`.claude/skills` is a symlink to `.agent/skills` so Claude Code discovers them automatically.)
+
+- [feat](.agent/skills/feat/SKILL.md) — build a feature end-to-end (issue → plan → implement → test → PR).
+- [fix](.agent/skills/fix/SKILL.md) — debug and fix a bug end-to-end (trace → root cause → fix → test → PR).
+- [refactor](.agent/skills/refactor/SKILL.md) — restructure code without changing behavior.
+- [unit-testing](.agent/skills/unit-testing/SKILL.md) — running and writing Vitest specs.
+
+Conventions and how-to knowledge live as docs in `tools/notes/` (see [Key Documentation](#key-documentation)) — the single source of truth. A skill references the docs it depends on through relative symlinks in its `references/` folder, created with:
+
+```bash
+cd .agent/skills/<skill>/references/
+ln -s ../../../../tools/notes/<Doc>.md <Doc>.md
+```
+
+To add a skill: create `.agent/skills/<kebab-case-name>/SKILL.md` with `name` and `description` frontmatter (the description states *when* to use it — that is what triggers loading), keep the body a short workflow that links docs via `./references/`, and list it here. When moving or renaming a doc, check for skill symlinks pointing at it: `grep -rl '<Doc>' .agent/skills/*/references/`.
+
+## Platform-Specific Code
+
+`packages/core` uses filename suffixes (`foo.ios.ts` / `foo.android.ts`, shared `foo-common.ts`, handwritten `foo.d.ts`) to split implementations per platform; the bundler picks the right file at build time. Read [Core Platform Modules](tools/notes/CorePlatformModules.md) before touching any module there — the short version: keep both platform files in parity, and update the neighboring `.d.ts` whenever a public API changes.
+
+## Testing
+
+- Unit tests (Vitest) are colocated `*.spec.ts` files. Run with `npx nx run core:test`.
+  - Watch mode: `npx nx run core:test --watch`
+  - Single suite by describe name: `npx nx run core:test -t 'XmlParser'`
+- Unit tests run in Node with NativeScript platform globals mocked in `packages/core/vitest.setup.ts` — they cannot exercise real native APIs. Behavior that touches iOS/Android at runtime is covered by the e2e suite: `npx nx run apps-automated:ios` or `npx nx run apps-automated:android` (requires a configured NativeScript environment with simulators/emulators).
+- Prefer adding a unit test for logic changes; add or extend an `apps/automated` test for native runtime behavior.
+
+## Formatting & Commits
+
+- Prettier formats the workspace: `npx nx format:write` (also auto-runs on the pre-commit hook).
+- Commit messages and PR titles follow the conventional format `type(scope): message` (e.g. `fix(core): ...`, `feat(ios): ...`) per the [commit guidelines](tools/notes/CONTRIBUTING.md#commit-messages).
+
+## Pull Requests
+
+- Use the `gh` CLI (GitHub CLI) for creating and managing pull requests.
+- Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md): reference the related issue, ensure existing tests pass, and include tests for the change.
diff --git a/apps/automated/src/image-source/image-source.md b/apps/automated/src/image-source/image-source.md
@@ -8,18 +8,18 @@ previous_url: /ApiReference/image-source/HOW-TO
 # Image source
 Using the image source requires the image-source module.
 ```TypeScript
-import * as imageSource from "tns-core-modules/image-source";
+import * as imageSource from "@nativescript/core/image-source";
 ```
 ```JavaScript
-var imageSource = require("tns-core-modules/image-source");
+var imageSource = require("@nativescript/core/image-source");
 ```
 The pre-required `imageSource` module is used throughout the following code snippets.
 We also use fs module defined as follows:
 ```TypeScript
-import * as fs from "tns-core-modules/file-system";
+import * as fs from "@nativescript/core/file-system";
 ```
 ```JavaScript
-var fs = require("tns-core-modules/file-system");
+var fs = require("@nativescript/core/file-system");
 ```
 
 ## Loading and saving images

diff --git a/apps/automated/src/ui/image/image.md b/apps/automated/src/ui/image/image.md
@@ -10,14 +10,16 @@ previous_url: /ApiReference/ui/image/HOW-TO
 
 The purpose of this article is to show the basic functionality of the Image view. The snippets demonstrates some scenarios and the usage of the ImageView specifics properties
 
-* [Binding image source property](#binding-image-source-property)
-* [Loading an image from app resources](#loading-an-image-from-app-resources)
-* [Loading an image from URL](#loading-an-image-from-url)
-* [Loading an image from file within the application](#loading-an-image-from-file-within-the-application)
-* [Loading an image from Data URI](#loading-an-image-from-data-uri)
-* [Setting image stretching](#setting-image-stretching)
-  * [via XML](#via-xml)
-  * [via code-behind](#via-code-behind)
+- [Image](#image)
+    - [Binding image source property](#binding-image-source-property)
+    - [Loading an image from app resources](#loading-an-image-from-app-resources)
+    - [Loading an image from URL](#loading-an-image-from-url)
+    - [Loading an image from file within the application](#loading-an-image-from-file-within-the-application)
+    - [Loading an image from Data URI](#loading-an-image-from-data-uri)
+    - [Setting image stretching](#setting-image-stretching)
+    - [via XML](#via-xml)
+    - [via code-behind](#via-code-behind)
+    - [See also](#see-also)
 
 Using an image in the code behind requires the Image module to be loaded.
 
@@ -123,7 +125,7 @@ This code snippet demonstrates the first scenario, when we setup the stretch in
 The second example shows, how we could set up the property via code behind. In this scenario, we get an instance of the image and set up the appropriate string value. The Image stretch could also be set by using `Stretch` enum. For example:
 
 ```TypeScript
-import * as Enums from "tns-core-modules/ui/enums"
+import * as Enums from "@nativescript/core/ui/enums"
 
 const image = new ImageModule.Image();
 image.stretch=CoreTypes.Stretch.none;

diff --git a/apps/ui/README.md b/apps/ui/README.md
@@ -30,8 +30,8 @@
         `npm run test-watch`
     - It is highly recommended during the development to use
 
-        `npm run test [android|ios]` along with `tns run [android|ios]`. This command will use already installed app on the device.
-        For example: Open terminal1 and run: `tns run android` and open new terminal2 and run: `npm run test android`
+        `npm run test [android|ios]` along with `ns run [android|ios]`. This command will use already installed app on the device.
+        For example: Open terminal1 and run: `ns run android` and open new terminal2 and run: `npm run test android`
 3. Debug test.
     - Run:
 

diff --git a/tools/notes/CONTRIBUTING-webpack.md b/tools/notes/CONTRIBUTING-webpack.md
@@ -76,7 +76,7 @@ NOTE: There are three test apps in the repository, located in the `/demo` direct
 
 4. Build the app for Android or iOS.
     ``` bash
-    tns run android/ios
+    ns run android/ios
     ```
 
 5. Install [appium](http://appium.io/) globally.